Диаграммы Санки — это высокоэффективные инструменты визуализации, используемые для отображения направления потока количества между различными узлами в системе. Пропорционально изменяя физическую ширину соединяющих линий в зависимости от объема потока, они позволяют инженерам, аналитикам и командам по эксплуатации мгновенно выявлять основных участников, распределение ресурсов, неэффективность или утечки в сложных сетях, таких как энергетические сети, цепочки поставок и финансовые портфели.
Базовая структура синтаксиса
Определения макета Санки основаны на оптимизированном формате структуры CSV (значения, разделенные запятыми) с тремя столбцами. Каждый файл начинается с одной из следующих строк: “sankey или sankey-beta заголовка объявления типа, за которым следуют отдельные строки потока, строго соответствующие формату Источник,Назначение,Значение шаблону.
sankey
Исходный узел,Целевой узел,150.50
Целевой узел,Финальный выходной узел,90.25
Справочник по синтаксису
В таблице ниже приведены основные правила и параметры данных, необходимые для правильного анализа диаграммы Санки в Mermaid.js.
| Элемент синтаксиса | Требование к типу | Описание и правила использования |
|---|---|---|
| Объявление | Идентификатор ключевого слова | Инициализирует движок отрисовки макета потока. Принимает “sankey или совместимую с предыдущими версиями “sankey-beta строку. |
| Исходный узел | Строчная метка | Исходная категория, с которой начинается поток ресурсов. Регистрозависимый идентификатор. |
| Целевой узел | Строка метки | Узел-получатель, где завершается конкретный объем связи. |
| Значение | Положительное число с плавающей точкой / целое число | Числовое значение потока. Толщина отображаемого пути напрямую рассчитывается относительно этого значения. |
| Строка комментария | Индикатор синтаксиса | Любой текст, предваряемый двойным знаком процента (“%%), игнорируется компилятором, что позволяет делать чистые аннотации данных. |
Обработка специализированных символов в метках узлов
Поскольку запятые и кавычки служат в качестве разделителей структурной системы внутри движка макета, специализированные вводы имен требуют определенных способов экранирования, чтобы обеспечить правильное отображение на холсте фронтенда.
1. Запятые в именах
Если конкретная метка узла требует буквальной запятой, оберните весь контейнер строки узла в пару стандартных двойных кавычек:
sankey
Бюджетный фонд,"Операции, заработная плата и администрирование",45000
2. Кавычки в именах
Чтобы явно отобразить двойные кавычки внутри имени метки, оберните весь параметр в внешние кавычки и используйте удвоенную пару двойных кавычек (“"") внутри строки целевого значения:
sankey
Серверные кластеры,"Внутренний ""Край"" узел",850
Расширенная конфигурация темы (директивы)
Вы можете точно настроить внешний вид диаграммы, передав блок конфигурации frontmatter в начале фрагмента документа. Это позволяет управлять стилями связей, отступами макета, стилями текста и выравниванием элементов непосредственно из редактора исходного текста.
Матрица атрибутов конфигурации Санки
| Имя свойства | Допустимые значения | Визуальный результат |
|---|---|---|
showValues |
true | false |
Переключает отображение текста числового значения потока непосредственно внутри полей меток узлов. |
linkColor |
'source' | 'target' | 'gradient' | '#hex' |
Определяет сопоставление цветов для путей связей.'gradient' плавно смешивает цвета между соединёнными объектами. |
nodeAlignment |
'justify' | 'left' | 'right' | 'center' |
Выравнивает структурные столбцы по сетке пространства холста. |
labelStyle |
'legacy' | 'обведенный' |
'обведенный' добавляет маску обводки фона за текстом, чтобы гарантировать высокую читаемость на сложных макетах. |
nodeWidth |
Целое число (пиксели) | Задает ширину прямоугольников узлов (по умолчанию: 10). |
nodePadding |
Целое число (пиксели) | Задает параметры вертикального расстояния между стекающимися строками (по умолчанию: 12). |
Реальный проект: Распределение чистой энергетической сети
Этот всесторонний проект отслеживает систему управления инфраструктурой энергетической сети. Он демонстрирует настройки заголовка — установку плавных градиентов цветов связей, стили обводки шрифтов и отключение подсчета метрик в строке — в сочетании со структурой многоуровневого макета.
---
config:
sankey:
showValues: false
linkColor: 'gradient'
nodeAlignment: 'justify'
labelStyle: 'outlined'
nodeWidth: 15
nodePadding: 18
---
sankey
%% Исходные строки данных
Солнечная ферма,Сетевая система хранения энергии,120.50
Ветряные турбины,Сетевая система хранения энергии,180.75
Гидроэлектростанция,Прямая промышленная линия,210.00
Импорт биотоплива,Тепловая резервная станция,45.25
%% Узлы распределения
Сетевая система хранения энергии,Жилые потребительские линии,145.00
Сетевая система хранения энергии,Прямая промышленная линия,110.25
Сетевая система хранения энергии,Потери и рассеивание энергии в системе,46.00
%% Финальные узлы доставки
Прямая промышленная линия,Тяжелый производственный хаб,295.00
Прямая промышленная линия,Коммерческие розничные сектора,25.25
Тепловая резервная станция,Коммерческие розничные сектора,45.25
Распространённые синтаксические ошибки и системные ограничения
При компиляции сильно плотных массивов данных небольшие скрытые ошибки конфигурации могут вызвать сбои при обработке макета. Помните об этих правилах устранения неполадок:
- Точная проверка колонок: Каждая строка данных после объявления основного заголовка должна содержать ровно три параметра, разделённые запятыми. Добавление четвёртой колонки или отсутствие значения приведёт к полной остановке компиляции диаграммы.
- Разрешение пустых строк: В отличие от жёстких правил традиционного парсинга данных, Mermaid позволяет добавлять пустые, чистые строки внутри блока кода, чтобы логически разделить различные уровни или этапы обработки ваших данных модели.
- Циклические блоки: Структуры Санки разработаны строго на основе направленных ациклических графов (DAG). Если вы соединяете узел А с узлом Б, а затем пытаетесь создать строку пути, соединяющую узел Б обратно с узлом А, математика движка макета столкнётся с циклическим обратным связью и выдаст ошибку.
- Ограничения данных значений: Поля значений могут обрабатывать только положительные числа. Отрицательные значения или буквенные символы не могут быть отображены в параметрах ширины.