Velocímetro (Gauge)

O Widget Velocímetro é ideal para visualizar o desempenho em relação a uma meta ou limite definido. Ele exibe um valor realizado posicionado em uma escala colorida, com faixas que indicam a qualidade do resultado (Ruim, Médio, Bom).

📊 Tipos de Gauge

O Widget oferece dois tipos visuais distintos:

1. Velocímetro (Speedometer)

O tipo padrão. Exibe um arco colorido com ponteiro indicando o valor realizado em relação ao máximo da escala. Ideal para exibir uma única métrica com visual impactante — ou um grid de métricas lado a lado via Repetir por Dimensão.

2. Solid Gauge

Exibe múltiplos anéis circulares empilhados, cada um representando um item de uma dimensão. Ideal para comparar o desempenho de múltiplos itens simultaneamente.

Configurações específicas do Solid Gauge:

• Coluna de Dimensão: Define qual dimensão será usada para separar os anéis (Vendedor, Produto, Região)
• Limite de Itens: Quantidade máxima de itens a exibir (1 a 20)
• Ordenação: Exibir os itens com maior ou menor percentual primeiro

---

⚙️ Configuração de Dados

Aba Dados

Defina as colunas e o modelo de valor do gauge:

• Valor Realizado: Coluna de métrica que alimenta o ponteiro. Obrigatório.
• Máscara do Valor: Formato de exibição do valor realizado — Reduzido (1K, 1M), Padrão do Campo, Inteiro, Moeda, Porcentagem.
• Objetivo / Máximo da Escala: Define o teto da escala. Pode ser:
  • Constante: Um número fixo (ex: 100). Padrão quando nenhum campo é selecionado.
  • Campo: Uma coluna da tabela — o máximo é lido de cada linha, permitindo que cada card do grid use seu próprio máximo.
• Filtros: Define o contexto de dados para o cálculo.

NOTE

O ponteiro é posicionado na proporção Realizado / Máximo. As faixas (bandas de cor) são relativas ao máximo, então se o máximo vier de um campo, cada card do grid terá suas faixas ajustadas ao seu próprio teto.

Marcador de Meta (Velocímetro)

O Marcador de Meta é uma linha opcional que corta o arco indicando um valor de referência secundário (diferente do máximo da escala). Fica desligado por padrão — você o ativa quando precisa.

• Habilitar Marcador de Meta: Ativa a linha no arco.
• Fonte do valor: Constante ou campo (igual ao Objetivo acima).

---

🌈 Faixas de Cor (Bandas)

Defina "zonas de temperatura" no arco para indicar visualmente o status. Clique em Gerenciar Faixas para abrir o editor:

• Nome da Faixa: Texto opcional para a zona (ex: "Ótimo", "Atenção"). Quando preenchido, habilita o Status no layout de texto e a legenda.
• De / Até: Intervalo percentual da faixa (0 a 100, relativo ao máximo da escala).
• Cor de Fundo: Cor do arco nesta zona.

A barra visual no topo do editor mostra a proporção de cada faixa em tempo real, e você pode arrastar os divisores para ajustar os limites.

Faixas padrão (quando nenhuma faixa é configurada):

• 0% – 60%: Vermelho (Crítico)
• 60% – 85%: Laranja (Atenção)
• 85% – 100%: Verde (Ótimo)

---

🎨 Configuração Visual

Estilo (Presets)

Uma galeria de presets visuais permite mudar rapidamente a aparência geral do velocímetro — combinando forma do arco, espessura, tipo de ponteiro e coloração. Clique no preset desejado para aplicá-lo ao gauge atual.

Tipo de Ponteiro (Velocímetro)

Selecione o indicador de valor em um seletor visual com pré-visualização ao vivo:

• Gota: Ponteiro em forma de gota partindo do centro. Padrão.
• Ponteiro: Agulha tradicional partindo do centro.
• Interno: Indicador no lado interno do arco.
• Externo: Indicador no lado externo do arco.
• Sem Ponteiro: Esconde o ponteiro (útil quando apenas o valor central importa).

Opções complementares:

• Cor do Velocímetro: Cor do ponteiro/agulha.
• Cor do Ponto Central: Cor do círculo no eixo (apenas para o tipo Ponteiro).
• Contorno do Ponteiro (Halo): Borda que faz o ponteiro se destacar sobre o arco. Ativo por padrão; desative para um visual mais limpo.

Estilo do Marcador de Meta (Velocímetro)

Visível apenas quando o Marcador de Meta está habilitado na aba Dados:

• Estilo da linha: Linha sólida, Tracejada, Triângulo.
• Cor: Cor da linha de meta.
• Texto do Marcador: Rótulo opcional exibido ao lado da linha. Suporta cor, tamanho, negrito e itálico independentes.

Coloração do Arco

Quatro modos de coloração do arco, com seletor visual:

• Faixas: O arco é colorido segundo as faixas definidas em Gerenciar Faixas. Padrão.
• Gradiente: Transição suave de cor do início ao fim do arco.
• Barra (cor fixa): O arco inteiro em uma única cor configurável.
• Barra (cor da faixa): O arco inteiro assume a cor da faixa onde o ponteiro está posicionado.

Legenda

Exibe uma legenda das faixas nomeadas fora do arco (requer que ao menos uma faixa tenha nome preenchido):

• Nenhuma — sem legenda.
• Topo — legenda acima do gauge.
• Baixo — legenda abaixo do gauge.

No modo grid (Repetir por Dimensão), a legenda é única para todos os cards.

Layout de Texto (Velocímetro)

Define quais informações aparecem dentro do arco e onde. Uma galeria de presets (Limpo, KPI, Completo) oferece atalhos rápidos. Cada elemento também pode ser posicionado individualmente:

Elemento	Conteúdo	Posição padrão
Valor	Valor realizado formatado	Topo
Razão	Percentual (realizado/máximo)	Oculto
Status	Nome da faixa atual	Oculto — requer faixa com nome

Posições disponíveis por elemento: Oculto, Topo, Centro, Baixo.

Tratamento do centro/topo (quando algum elemento está em Topo ou Centro):

• Contorno (Halo): Contorno suave que contrasta o texto com o arco ao fundo.
• Pill: Caixinha com cor e borda configuráveis, raio de arredondamento (Nenhum / Pequeno / Médio / Grande) e opacidade.

Aparência

• Padrão: Fundo sólido.
• Transparente: Remove o fundo para integrar ao Dashboard.
• Destacado: Adiciona sombra e borda.

Rótulos de Dimensão (Solid Gauge)

• Tamanho da Fonte: Tamanho do texto dos rótulos de cada anel (10px a 24px).
• Largura Máxima do Rótulo: Limita a largura dos rótulos. Textos maiores são truncados com ... (60px a 300px). Passe o mouse sobre o rótulo para ver o texto completo.

---

🔧 Avançado (Velocímetro)

Controles detalhados disponíveis em painéis recolhidos na aba Visual.

Ângulos

• Personalizar Ângulos Manualmente: Ativa os controles de ângulo.
• Ângulo Inicial: Onde o arco começa (em graus, relativo ao centro).
• Ângulo Final: Onde o arco termina.

WARNING

Evite arcos com amplitude menor que 90° — dificulta a leitura do valor.

Rotação e Escala

• Rotação Global: Gira todo o gauge em torno do seu centro (-180° a 180°). Útil para posicionamento personalizado.
• Marcações (Ticks):
  • Nenhuma — sem marcações no arco.
  • Pontas — apenas os valores de início e fim. Padrão.
  • Graduado — marcações ao longo de todo o arco, com controle de Densidade (10px a 100px; valores menores = mais marcações).
  • Máscara dos Ticks: Formato dos valores nas marcações — Reduzido, Padrão, Inteiro, Moeda, Porcentagem, Decimal.
• Raio Interno: Espessura do arco. Valores maiores criam um arco mais fino.

Textos e Labels

Controles finos por elemento textual (Valor, Razão/%, Status, Marcações):

• Cor: Cor do texto do elemento.
• Tamanho: Pequeno, Médio ou Grande.
• Negrito / Itálico: Estilo tipográfico individual por elemento.

---

🔁 Repetir por Dimensão (Velocímetro)

Disponível apenas no tipo Velocímetro. O Solid Gauge não é afetado.

Quando uma Dimensão de Repetição é configurada, o widget exibe um grid responsivo de velocímetros — um card por valor da dimensão (ex: um por região, um por vendedor). É a forma de transformar um único medidor em um painel de "small multiples".

Configuração (seção "Repetir por Dimensão" na aba Dados)

• Dimensão de Repetição: Coluna de dimensão que gera os cards. Ao limpar este campo, o widget volta ao modo de medidor único.
• Largura Mínima do Card: Largura mínima de cada card (em pixels). O grid encaixa automaticamente quantas colunas couberem na largura do widget — a quebra de linha é automática, e a célula rola na vertical quando há muitos cards.
• Limite de Cards: Número máximo de cards exibidos. Aplicado após a ordenação.
• Ordenar Por: Ordena os cards por qualquer campo — inclusive um campo que não aparece no gauge. Suporta múltiplos campos, com sentido crescente/decrescente por coluna.

WARNING

Se o campo de ordenação tiver granularidade diferente da dimensão repetida (ex: ordenar por uma métrica diária quando a dimensão é mensal), os cards podem duplicar. Um aviso é exibido automaticamente quando isso é detectado.

Comportamento do Máximo no Grid

• Máximo constante: Todos os cards compartilham a mesma escala — facilita a comparação visual direta entre eles.
• Máximo por campo: Cada card usa o máximo da sua própria linha. As faixas se ajustam automaticamente ao teto de cada card, e o marcador de meta (quando vem de um campo) também varia por card.

---

🃏 Aparência do Card (modo grid)

Quando o grid está ativo, cada card já adota a estética padrão dos cards do sistema (fundo claro — escuro no tema escuro —, sombra suave e cantos arredondados). As opções abaixo personalizam a apresentação:

As configurações de aparência do card ficam dentro da seção "Repetir por Dimensão" na aba Dados, logo abaixo da ordenação.

Fundo do Card

• Fundo do Card: Cor personalizada para o fundo de cada card. O contorno do ponteiro se ajusta automaticamente a essa cor para manter o contraste.

Título do Card

O valor da dimensão (ex: "Norte", "SP") é exibido como título no topo de cada card. Opções de formatação:

• Cor do Título: Cor do texto do título.
• Fundo do Título: Cor de fundo do bloco de título (opcional; cria um destaque visual).
• Tamanho: Pequeno, Médio, Grande.
• Alinhamento: Centro ou Esquerda.
• Negrito: Engrossa o texto do título.
• Quebrar Linha: Quando desligado (padrão), nomes longos são truncados com ... (passe o mouse para ver o nome completo). Ative para exibir o nome inteiro em várias linhas.

Legenda em Card

• Legenda em Card: Coloca a legenda das faixas dentro de um cartão (com fundo e contorno do tema), em vez de flutuando solta sobre o gráfico.

---

🔍 Comportamento

Relatório (Drill-through)

• Campos para Relatório: Define quais colunas serão mostradas na tabela detalhada ao clicar para visualizar o Relatório no Widget. Permite explorar os dados que compõem o cálculo do gauge.