Documentação HorusBI
Buscar K

Aparência

KPI (Indicador-Chave de Desempenho) ​

O Widget KPI (Key Performance Indicator) é utilizado para destacar números únicos e importantes, como faturamento total, número de vendas ou tickets abertos. Ele suporta até dois valores (primário e secundário), comparação histórica e indicadores de variação.

🏗️ Estrutura do Widget ​

O KPI é composto por:

  1. Valor Primário: O número principal em destaque
  2. Título Primário: Rótulo do valor principal
  3. Valor/Título Secundário (Opcional): Um segundo dado de apoio (meta ou média)
  4. Variação (Opcional): Indicador percentual ou absoluto de mudança em relação a um período anterior
  5. Gráfico de Evolução (Opcional): Uma sparkline (minigráfico de área) ao fundo mostrando a tendência histórica

⚙️ Configuração ​

1. Aba Dados ​

Configure as fontes de dados para o valor principal e secundário.

Dados Primários ​

  • Coluna de dados: Selecione a métrica (número) que será agregada
  • Título: O texto que aparece acima ou abaixo do número. Suporta Expressão para textos dinâmicos
  • Filtros: Define o contexto de dados específico para este número (filtrar apenas por "Status = Fechado")

Dados Secundários ​

  • Coluna de dados: Selecione a segunda métrica
  • Título: Rótulo para o dado secundário. Suporta Expressão
  • Filtros: Contexto específico para o dado secundário

TIP

Se os filtros forem idênticos aos dados primários, o sistema fará apenas uma consulta ao banco de dados para otimizar a performance

2. Aba Visual ​

Personalize a aparência, cores e formatação.

🎨 Aparência Geral ​

  • Estilo:
    • Padrão: Fundo sólido (configurável)
    • Transparente: Sem fundo, ideal para sobrepor em imagens ou mapas
    • Destacado: Estilo visual com sombras ou bordas enfáticas
  • Cor do Fundo: (Disponível no estilo Padrão). Suporta Expressão para mudar a cor condicionalmente (vermelho se a meta não for batida)

Dados Primários / Secundários ​

Para cada conjunto de dados, é possível configurar independentemente:

  • Tamanho do Valor/Título: Pequeno (12px), Médio (24/16px), Grande (36/24px)
  • Cor do Número: Cor estática ou Expressão (verde se positivo, vermelho se negativo)
  • Cor do Título: Cor estática ou Expressão
  • Formato do Número:
    • Padrão do Campo: Usa o formato definido na modelagem do DW
    • Número: Decimal padrão (2 casas)
    • Moeda: Formato monetário (R$)
    • Porcentagem: Multiplica por 100 e adiciona %
    • Reduzido: Abrevia números grandes (1K, 1M, 1B, 1T)
    • Inteiro: Sem casas decimais
  • Alinhamento: Esquerda, Centro ou Direita

3. Aba Clique (Interação) ​

Define o que acontece ao clicar no Widget.

  • Link no Indicador: Se ativado, transforma o Widget em um botão clicável

🎨 Configuração Visual e Layout ​

Aparência Geral ​

  • Estilo: Padrão (Card com sombra), Transparente (Clean), Destacado (Borda forte)
  • Alinhamento: Alinhe o conteúdo à esquerda, centro ou direita do card
  • Tamanhos: Controle individual do tamanho da fonte para o Título e para o Número (Pequeno, Médio, Grande)

Cores Avançadas ​

Quase tudo no KPI pode ser colorido dinamicamente via Expressão (JavaScript):

  • Fundo do Widget
  • Cor do Número (Primário e Secundário)
  • Cor do Título
  • Cor da Linha de Evolução

TIP

Use Expressões: É possível pintar o fundo de vermelho se a meta não for batida:

javascript
if (this.value < 1000) return "#fee2e2"; // Vermelho claro
return "#ffffff";

📈 Evolução Histórica (Sparkline) ​

O grande diferencial do KPI é mostrar não apenas a "foto" atual, mas o "filme" da evolução ao longo do tempo.

Configuração ​

  • Período Padrão: Define o intervalo histórico ("Último Ano", "Últimos 30 dias")
  • Gráfico de Linha: Exibe uma sparkline (minigráfico) no fundo do card mostrando a tendência

Variação (Delta) ​

Calcula automaticamente a diferença em relação ao período anterior.

  • Tipos de Comparação:
    • Mesmo período ano anterior (YoY)
    • Mês anterior (MoM)
    • Valor Primário vs Secundário (Realizado vs Meta)
  • Ícones e Cores:
    • Setas ▲ / ▼ automáticas
    • Cores Semânticas: "Maior (Verde), Menor (Vermelho)" para receitas, ou invertido para custos/despesas

💻 Cheat Sheet: Expressões Comuns ​

O KPI suporta expressões "Low-Code" (JavaScript) para cores e textos dinâmicos. O objeto this contém o contexto do Widget.

Variáveis Disponíveis:

  • this.primaryValue: Valor numérico principal
  • this.secondaryValue: Valor numérico secundário
  • this.variation: Valor da variação calculada (0.15 para 15%)

1. Cor Condicional (Semáforo) ​

Use no campo Cor do Número ou Cor do Fundo.

javascript
// Verde se positivo, Vermelho se negativo
if (this.primaryValue >= 0) return '#22c55e';
return '#dc2626';

2. Atingimento de Meta (Cor) ​

Use quando tiver Valor (Vendas) e Secundário (Meta).

javascript
// Calcula atingimento
const atingimento = this.primaryValue / this.secondaryValue;

if (atingimento >= 1) return '#22c55e'; // Meta batida (Verde)
if (atingimento >= 0.8) return '#f59e0b'; // Quase lá (Laranja)
return '#dc2626'; // Ruim (Vermelho)

3. Título Dinâmico ​

Use no campo Título.

javascript
// Exibe a variação no título
const diff = this.primaryValue - this.secondaryValue;
return `Vendas (Diferença: ${diff})`;