Buscar K
Aparência
Are you an LLM? You can read better optimized documentation at /dataviz/widgets/kpi.md for this page in Markdown format
KPI
- Tipo
- Referência
- Para
- Analista
- Na tela
- DataViz › Aplicação › Dashboards › Editando Widget › KPI
O KPI mostra um número em destaque, como faturamento do mês ou pedidos em aberto. Ao lado dele cabem um segundo valor (a meta, o mês passado), a variação entre os dois, um mini-gráfico da evolução e uma barra de progresso até a meta.
Use o KPI quando a pergunta tem uma resposta só: "quanto vendemos?". Para comparar categorias, use Barras e linhas. Nome, aparência, formato do número e regras em JavaScript seguem as opções comuns; abaixo está o que é só do KPI.
Aba Dados
O KPI tem dois blocos com os mesmos campos: Dados Primários, o número principal, e Dados Secundários, opcional.
| Na tela | O que faz |
|---|---|
| Coluna de dados | A coluna ou expressão que vira o número, já agregada (soma, contagem, média). |
| Título | O texto junto do número. Aceita regra em JavaScript. |
| Filtros | Restringe só este número. O valor secundário pode ter filtros diferentes do primário, o que permite, por exemplo, "vendas do mês" no primário e "vendas do mesmo mês, só loja física" no secundário. Veja Filtros. |
Aba Visual
| Na tela | O que faz |
|---|---|
| Layout | Galeria de composições: Clássico, Valor em destaque, Ícone à esquerda, Ícone no topo, Valor + variação, Valor + tendência, Progresso / Meta, Compacto. O layout é ponto de partida: os campos continuam editáveis. Quando o layout esconde algo que está configurado, a tela avisa em Este layout não exibe (ícone, dado secundário, evolução histórica ou variação). |
| Ícone | Aparece nos layouts com ícone, ou quando já há um ícone escolhido. Nome do ícone, Posição (Esquerda ou Topo), Cor do Ícone, Tamanho do ícone e Fundo do ícone (Nenhum, Círculo ou Quadrado, com cor, espaçamento e transparência). |
| Textos adicionais | Overline (acima do título), Subtítulo (abaixo do valor) e Helper (caption discreto), cada um com negrito, itálico, cor, tamanho e alinhamento. Prefixo do valor e Sufixo do valor grudam no número, sem espaço: para R$ 10, escreva R$ com o espaço. |
| Aparência | Padrão, Transparente, Destacado (veja Aparência) ou Customizado. Cor do Fundo aparece em Padrão e Customizado. |
| Aparência do card | Só com Customizado. Espessura da borda, Cor da borda, Arredondamento, Sombra, Espaçamento interno, Preenchimento (Nenhum, Sólido, Suave, Gradiente) e Borda de destaque numa lateral (Esquerda, Topo ou Embaixo), com cor e espessura. |
| Dados Primários e Dados Secundários | Para cada valor: Tamanho do Valor e Tamanho do Título (Pequeno, Médio, Grande), Cor do Número, Cor do Título, negrito e itálico, Formato do Número e Alinhamento. |
Aba Comportamento
Clique
| Na tela | O que faz |
|---|---|
| Colocar link no Indicador | Ligado, clicar no KPI abre o relatório do widget. |
| Campos para Relatório | Colunas extras desse relatório. Veja Campos para Relatório. |
Evolução histórica e variação
| Na tela | O que faz |
|---|---|
| Coluna de Data | A data que ordena a evolução e define o período da variação. |
| Mostrar Evolução Histórica | Desenha o mini-gráfico do valor ao longo do tempo. |
| Mini-gráfico como fundo | Põe o mini-gráfico esmaecido atrás do número. |
| Forma do mini-gráfico | Área, Linhas ou Barras, com Suavizar a curva (ou Arredondar as barras) e Mostrar pontos. |
| Cor do gráfico de evolução | Cor fixa ou regra em JavaScript. |
| Período Padrão | Último Ano ou Último Mês Completo. |
| Mostrar Variação | Liga o selo de variação. |
| Tipo de Variação | A comparação: veja a tabela abaixo. |
| Ícone de Variação | A cor do selo: Maior (verde), Menor (vermelho) para receita, Menor (verde), Maior (vermelho) para custo, ou Cor Fixa, que abre Cor da Variação. |
| Posição da variação | Abaixo do valor ou Ao lado do valor. |
| Modo de exibição da variação | Percentual (%) e Valor (variação %) mostram a variação em percentual. Absoluto (diferença) mostra a diferença no formato do número. % da meta mostra o valor principal dividido pela meta. |
| Variação como badge | Mostra a variação dentro de uma pílula colorida. |
| Tipo de Variação | Compara o valor principal com |
|---|---|
| Variação Valor Primário sob Secundário | O valor secundário, em variação percentual. |
| Valor Primário sob Secundário | O valor secundário, como razão (quanto do secundário foi atingido). |
| Mesmo Período Ano Anterior | O mesmo intervalo de datas um ano antes. |
| Período Anterior Relativo ao Selecionado | O período anterior ao filtrado, conforme a tabela seguinte. |
Os dois últimos tipos dependem de um filtro de data na Coluna de Data. Sem esse filtro no Dashboard, o KPI não tem período para comparar e não mostra a variação.
| Filtro de data | Período anterior relativo |
|---|---|
| Um dia, 10/09 | O dia anterior, 09/09 |
| Mês cheio, 01/09 a 30/09 | O mês anterior inteiro, agosto |
| Mês até a data, 01/09 a 09/09 | Os mesmos dias do mês anterior, 01/08 a 09/08 |
| Começa em 01/01, como 01/01 a 15/03 | O mesmo intervalo no ano anterior |
| Qualquer outro, como 10/09 a 19/09 (10 dias) | Os 10 dias logo antes, 31/08 a 09/09 |
Meta (progresso)
| Na tela | O que faz |
|---|---|
| Exibir meta | Liga a barra ou o anel de progresso. |
| Fonte da meta | Valor fixo (um número ou regra em JavaScript em Valor da meta), Dado secundário (usa o valor secundário já carregado) ou Coluna (soma a Coluna da meta). |
| Forma do indicador | Barra, Anel ou Nenhum. |
Com Coluna, a meta é calculada com os mesmos filtros do valor principal. Se a tabela de metas tem uma linha por grupo (uma por loja, uma por vendedor), todas entram na soma, a menos que o Dashboard esteja filtrado por esse grupo. Para a meta de um grupo só, use Dado secundário com filtro próprio.
Descrição
Exibir botão de descrição (ⓘ) põe um ⓘ ao lado do título. Quem vê o Dashboard clica nele e lê o texto escrito em Editar descrição: o que o número mede, como é calculado, o que fica de fora.
Regras em JavaScript
Quase todo campo de cor e de texto do KPI aceita uma regra em JavaScript: título, cor do fundo, cor do número e do título (primário e secundário), cor do gráfico de evolução, ícone e fundo do ícone, overline, subtítulo, helper, borda, destaque e preenchimento do card, e a meta.
| Variável | O que tem | Onde existe |
|---|---|---|
this.primaryValue | O valor principal, sem formato. | Em todos os campos |
this.secondaryValue | O valor secundário, sem formato. | Em todos os campos |
this.datefns | A biblioteca date-fns. | Em todos os campos |
this.variation | A variação calculada, como fração: 0,12 é +12%. | Só em Cor da Variação |
this.categories e this.values | As datas e os valores do mini-gráfico, em listas. | Só em Cor do gráfico de evolução |
Exemplo
Faturamento do mês contra a meta, com fundo que muda de cor:
- Em Dados Primários, Coluna de dados =
Vendas.Valor(soma). Em Dados Secundários, Coluna de dados =Metas.Valor(soma). - Em Comportamento, ligue Exibir meta com Fonte da meta = Dado secundário e Forma do indicador = Barra.
- Em Visual, na Cor do Fundo, use a regra:
js
const atingimento = this.primaryValue / this.secondaryValue;
if (atingimento >= 1) return "#dcfce7"; // verde-claro: meta batida
if (atingimento >= 0.8) return "#fef9c3"; // amarelo-claro: perto
return "#fee2e2"; // vermelho-claro: longeCom R$ 85.000 vendidos e meta de R$ 100.000, o atingimento é 0,85: o fundo fica amarelo-claro e a barra, em 85%.
Limites
this.valuenão existe no KPI. Uma regra que usathis.valuerecebeundefinede nunca entra noif.- A variação por período (Mesmo Período Ano Anterior, Período Anterior Relativo ao Selecionado) faz uma consulta a mais, e a evolução histórica outra.
- Adicionar aos KPIs Mobile, no menu do widget, só aparece no aplicativo de celular.
Pelo Lumo CLI
Este widget também pode ser criado e versionado em YAML, com type: Kpi. Veja a referência de app.