Diagramas Sankey são ferramentas de visualização altamente eficazes usadas para representar o fluxo direcional de quantidades entre nós distintos dentro de um sistema. Ao escalar a largura física das ligações conectadas proporcionalmente ao volume numérico do fluxo, permitem que engenheiros, analistas e equipes de operações identifiquem instantaneamente principais contribuintes, alocações de recursos, ineficiências ou vazamentos em redes complexas, como redes de energia, cadeias de suprimentos e portfólios financeiros.
Estrutura Básica da Sintaxe
sankeysankey ou sankey-beta cabeçalho de declaração de tipo, seguido por linhas individuais de fluxo que seguem um padrão estrito de Fonte,Alvo,Valor padrão.
sankey
Nó de Origem,Nó de Destino,150,50
Nó de Destino,Nó de Saída Final,90,25
Referência da Sintaxe
A tabela abaixo detalha as regras e parâmetros principais de dados necessários para analisar corretamente um gráfico Sankey no Mermaid.js.
| Elemento da Sintaxe | Requisito de Tipo | Descrição e Regras de Uso |
|---|---|---|
| Declaração | Identificador de Palavra-Chave | Inicializa o motor de renderização de layout em fluxo. Aceita sankey ou o compatível com versões anteriores sankey-beta string. |
| Nó de Origem | Rótulo de String | A categoria de origem onde o fluxo de recursos começa. Identificador sensível a maiúsculas e minúsculas. |
| Nó de Alvo | Rótulo de String | O nó destinatário onde o volume específico de ligação termina. |
| Valor | Número Positivo / Inteiro | O peso numérico do fluxo. A espessura da trajetória renderizada é calculada diretamente em relação a este valor. |
| Linha de Comentário | Indicador de Sintaxe | Qualquer texto precedido por um sinal duplo de porcentagem (“%%) é ignorado pelo compilador, permitindo anotações de dados limpas. |
Manipulação de Caracteres Especializados nos Rótulos de Nós
Como vírgulas e aspas servem como delimitadores estruturais do sistema dentro do motor de layout, entradas de nome especializadas exigem técnicas específicas de escape para garantir que sejam exibidas corretamente na tela do frontend.
1. Vírgulas em Nomes
Se um rótulo de nó específico exigir uma vírgula literal, envolva todo o contêiner de string do nó com um par de aspas duplas padrão:
sankey
Pool de Orçamento,"Operações, Folha de Pagamento e Administração",45000
2. Aspas em Nomes
Para renderizar explicitamente aspas duplas dentro de um nome de rótulo, envolva todo o parâmetro com aspas externas e use um par duplicado de aspas duplas (“"") dentro da string de valor-alvo:
sankey
Clusters de Servidores,"Nó Interno ""Edge""",850
Configuração Avançada de Tema (Diretivas)
Você pode ajustar com precisão a apresentação do seu diagrama passando um bloco de configuração de frontmatter no início do seu trecho de documento. Isso permite controlar estilos de ligação, espaçamento de layout, estilos de texto e alinhamentos de elementos diretamente do seu editor de texto bruto.
Matriz de Atributos de Configuração de Sankey
| Nome da Propriedade | Valores Aceitos | Resultado Visual |
|---|---|---|
mostrarValores |
verdadeiro | falso |
Alternar se o texto do valor numérico do fluxo é impresso diretamente dentro das caixas de rótulo do nó. |
corLigacao |
'fonte' | 'destino' | 'gradiente' | '#hex' |
Determina o mapeamento de cor dos caminhos de ligação.'gradiente' mistura as cores suavemente entre as entidades conectadas. |
alinhamentoNo |
'justificar' | 'esquerda' | 'direita' | 'centro' |
Alinha as colunas estruturais na grade do espaço da tela. |
estiloRotulo |
'herança' | 'contornado' |
'contornado' adiciona uma máscara de traço de fundo atrás do texto para garantir alta legibilidade em layouts complexos. |
nodeWidth |
Inteiro (Pixels) | Define a largura dos retângulos dos nós (Padrão: 10). |
nodePadding |
Inteiro (Pixels) | Define os parâmetros de espaçamento vertical entre linhas empilhadas (Padrão: 12). |
Projeto Prático: Distribuição de Rede de Energia Limpa
Este projeto abrangente rastreia um sistema de gestão de rede de infraestrutura elétrica. Ele demonstra configurações de frontmatter—definindo gradientes suaves de cor em links, estilos tipográficos contornados e desativando contagens de métricas embutidas—associadas a uma estrutura de layout em múltiplos níveis.
---
config:
sankey:
showValues: false
linkColor: 'gradiente'
nodeAlignment: 'justificar'
labelStyle: 'contornado'
nodeWidth: 15
nodePadding: 18
---
sankey
%% Linhas de Dados de Origem
Fazenda Solar,Grade de Armazenamento de Energia,120.50
Turbinas Eólicas,Grade de Armazenamento de Energia,180.75
Usina Hidrelétrica,Linha Industrial Direta,210.00
Importações de Biocombustível,Estação de Backup Térmico,45.25
%% Nós de Distribuição
Grade de Armazenamento de Energia,Linhas de Consumo Residencial,145.00
Grade de Armazenamento de Energia,Linha Industrial Direta,110.25
Grade de Armazenamento de Energia,Perdas do Sistema e Dissipação,46.00
%% Nós Finais de Entrega
Linha Industrial Direta,Hub de Manufatura Pesada,295.00
Linha Industrial Direta,Sets Comerciais de Varejo,25.25
Estação de Backup Térmico,Sets Comerciais de Varejo,45.25
Armadilhas Comuns de Sintaxe e Restrições do Sistema
Ao compilar matrizes de dados altamente densas, alguns erros sutis de configuração provocarão falhas na análise do layout. Mantenha estas regras de solução de problemas em mente:
- Verificação Exata de Colunas: Cada linha de item após a declaração do cabeçalho principal deve conter exatamente três parâmetros separados por vírgulas. Adicionar uma quarta coluna ou omitir um valor impedirá completamente a compilação do diagrama.
- Permissões de Linhas Vazias: Diferentemente das regras rígidas tradicionais de análise de dados, o Mermaid permite que você adicione linhas vazias e limpas dentro do bloco de código para separar logicamente diferentes níveis ou fases de processamento dos seus dados do modelo.
- Blocos de Laço Circular: As estruturas Sankey são projetadas estritamente em torno de Grafos Direcionais Acíclicos (DAGs). Se você conectar o Nó A ao Nó B, e depois tentar escrever uma linha de caminho conectando o Nó B de volta ao Nó A, o motor de layout terá uma falha de feedback e apresentará erro.
- Restrições de Dados de Valor: Os campos de valor só podem analisar números positivos. Valores negativos ou caracteres alfabéticos brutos não podem ser renderizados em parâmetros de largura.