Documentação HorusBI
Buscar K

Aparência

Abrir no Claude Abrir no ChatGPT

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
    • Customizado: Destrava a galeria de Aparência do Card (borda, sombra, destaque lateral e preenchimento) — ver seção abaixo
  • 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

🖼️ Layouts e Recursos Visuais (Novidades) ​

NOTE

Retrocompatibilidade total. KPIs já criados continuam funcionando exatamente como antes — nenhuma configuração existente é alterada. Os recursos descritos nesta seção são opt-in: só são ativados ao escolher um layout diferente de Clássico.

Galeria de Layouts ​

Na aba Visual, o campo Layout exibe uma galeria com 8 predefinições visuais. Cada layout define uma composição padrão (posição do ícone, destaque do valor, presença de barra de progresso etc.) que pode ser ajustada livremente após a seleção.

LayoutCaracterística principal
ClássicoComportamento atual do KPI — sem alterações
Valor em destaqueNúmero central em tipografia maior, sem elementos laterais
Ícone à esquerdaÍcone alinhado à esquerda do valor e título
Ícone no topoÍcone centralizado acima do valor
Valor + variaçãoValor e delta lado a lado em destaque
Valor + tendênciaValor acompanhado de sparkline de tendência
Progresso / MetaBarra ou anel de progresso como elemento principal
CompactoLayout reduzido para cards pequenos em grids densos

TIP

Selecionar um layout aplica padrões sensatos automaticamente, mas todos os campos permanecem editáveis. Use o layout como ponto de partida, não como restrição.

🏷️ Ícone ​

Disponível quando o layout escolhido inclui posição de ícone (ou ao ativar manualmente):

  • Ícone: Código Iconify no formato prefixo:nome — ex: mdi:currency-usd, carbon:chart-line, heroicons:arrow-trending-up. Use o seletor visual (IconPicker) para navegar pela biblioteca
  • Posição: Esquerda (ao lado do valor) ou Topo (acima do valor)
  • Cor do Ícone: Cor estática ou Expressão para cor condicional (ver Cheat Sheet)
  • Tamanho: Tamanho em px (ex: 32)
  • Fundo do ícone (opcional): exibe uma pílula ou círculo atrás do ícone. Escolha a forma, a cor de fundo (vazia = tom suave derivado da cor do ícone) e a opacidade

✍️ Tipografia ​

Controle de estilo tipográfico por elemento e por contexto. O KPI usa sempre a fonte do tema do dashboard — não há seleção de família de fonte.

  • Dados Primários — para o Número e o Título primários, ative individualmente Negrito e Itálico
  • Dados Secundários — o Número e o Título secundários têm controle independente do primário (ex.: primário em negrito, secundário normal)
  • Textos adicionais — quando ativados, Overline, Subtítulo e Helper oferecem Negrito, Itálico, Cor (estática ou Expressão) e Tamanho (px) próprios

📝 Textos Adicionais ​

Campos de texto extras para enriquecer o contexto do indicador, todos com suporte a Expressão:

  • Overline: Texto pequeno exibido acima do valor — útil para categoria ou período (ex: "Jan/2025")
  • Subtítulo: Texto exibido abaixo do valor — complemento ou contexto adicional
  • Helper: Legenda discreta no rodapé do card — ideal para notas metodológicas curtas
  • Prefixo: Texto inline antes do número — ex: "R$ ", "US$ "
  • Sufixo: Texto inline depois do número — ex: " un", " h", "%"

TIP

Prefixo e sufixo são renderizados junto ao número, sem espaço extra. Se precisar de espaço, inclua-o na string: "R$ " (com espaço no final).

📉 Variação (Delta) ​

A variação continua sendo alimentada pela configuração de Evolução Histórica (período de comparação). Os novos controles são de apresentação:

  • Posição: Abaixo do valor (padrão) ou À direita do valor
  • Modo de exibição:
    • Percentual: Diferença relativa ao período anterior (ex: +12,3%)
    • Diferença absoluta: Valor numérico da diferença (ex: +1.450)
    • Valor: Exibe o valor do período comparado, sem cálculo de diferença
    • % da meta: Razão entre o Valor Primário e o valor da Meta configurada (campo Meta, fixo ou por expressão) — ex: 87% da meta
  • Selo (badge): quando ativado, a variação aparece dentro de uma pílula tingida com a cor semântica, em vez de texto simples

🎯 Meta (Progresso) ​

Indicador visual de atingimento de meta, comparando o Valor Primário com o valor da Meta configurada:

  • Origem da Meta:
    • Valor fixo: um número fixo ou por Expressão
    • Dado secundário: reaproveita o valor secundário já carregado (sem nova consulta)
    • Coluna: agrega uma métrica do modelo como denominador da meta
  • Tipo de indicador:
    • Barra: Barra horizontal de progresso abaixo do valor
    • Anel: Anel circular de progresso (semelhante a um mini-gauge)
  • A barra/anel usa as mesmas cores semânticas configuradas na seção de Variação

NOTE

O progresso compara o Valor Primário com o valor do campo Meta (configurável como valor fixo ou por expressão na própria seção Meta). O denominador é esse valor de Meta, não o Dado Secundário.

ℹ️ Descrição (ⓘ) ​

Permite ao construtor do dashboard adicionar uma explicação rica sobre o indicador, visível ao consumidor final:

  • Conteúdo: Editor rich-text — suporta negrito, itálico, listas e links
  • Acesso: O consumidor clica no botão ⓘ ao lado do título do KPI para abrir um modal com a descrição
  • Uso recomendado: Explicar o que o indicador mede, como é calculado, quais exclusões foram aplicadas ou como interpretar o valor

TIP

Use a Descrição para reduzir dúvidas recorrentes em reuniões: explique a fórmula, o período de referência e as principais regras de negócio do indicador.

📊 Sparkline como Fundo ​

Além da sparkline tradicional (minigráfico abaixo do valor), é possível renderizar a tendência histórica esmaecida atrás do número — o valor fica em primeiro plano e o histórico vira um fundo discreto. Requer a Evolução Histórica configurada.

🃏 Aparência do Card ​

Quando o Estilo (aba Visual → Aparência Geral) é definido como Customizado, o KPI desenha a própria moldura, com uma galeria de estilos prontos e controles finos.

Galeria de Estilos de Card ​

Um seletor com pré-visualização (igual ao de Layouts) oferece estilos prontos:

EstiloCaracterística
PlanoSem borda nem sombra
ContornadoBorda fina ao redor
ElevadoSombra (efeito flutuante)
Destaque à esquerdaBarra de cor na lateral esquerda
Destaque no topoBarra de cor no topo
SólidoFundo preenchido com cor sólida
SuaveFundo com um leve banho da cor (wash)
GradienteFundo com gradiente entre duas cores
Bloco à esquerdaBarra lateral larga colorida

TIP

Assim como nos Layouts, escolher um estilo é um ponto de partida — todos os controles finos abaixo continuam editáveis.

Controles Finos ​

  • Borda: Espessura (Nenhuma, Fina, Média, Grossa) e cor
  • Cantos (raio): Pequeno, Médio ou Grande
  • Sombra: Nenhuma, Suave ou Média
  • Espaçamento interno (padding)
  • Borda de destaque (accent): Uma faixa colorida em uma única lateral (Esquerda, Topo ou Base), com cor e espessura próprias — ótima para dar identidade sem fundo pesado
  • Preenchimento: Sólido, Suave (banho leve da cor) ou Gradiente (entre duas cores)

NOTE

Em fundos escuros (Sólido/Gradiente), defina a Cor do Número e a Cor do Título em um tom claro (ex.: branco) para manter o contraste. Ao escolher um estilo de fundo escuro na galeria, o editor já ajusta esse contraste automaticamente.

💻 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})`;

4. Cor do Ícone por Expressão ​

Use no campo Cor do Ícone (layout com ícone ativo). As expressões do KPI expõem apenas this.primaryValue e this.secondaryValue — para comparar com uma meta numa expressão, use um limite fixo:

javascript
// Ícone verde se meta atingida, vermelho se não
const meta = 1000;
if (this.primaryValue >= meta) return '#22c55e';
return '#dc2626';

5. Modo de Exibição do Delta: % da Meta ​

Configure o Modo de exibição como % da meta e preencha o campo Meta. O sistema calcula (Valor Primário / Meta) * 100 automaticamente — não é necessária expressão adicional.