桑基图是高效的可视化工具，用于描绘系统中不同节点之间数量的定向流动。通过将连接链接的物理宽度按数值流量大小成比例缩放，使工程师、分析师和运营团队能够立即识别出复杂网络（如能源电网、供应链和金融投资组合）中的主要贡献者、资源分配、低效率或泄漏点。
基本语法结构
桑基图布局定义基于优化的三列CSV（逗号分隔值）结构格式。每个文件均以以下任一类型声明头开始：sankey 或 sankey-beta 类型声明头，随后是遵循严格 源,目标,值 模式的单独流动行。
语法参考
下表分解了在Mermaid.js中正确解析桑基图所需的主要数据规则和参数。
| 语法元素 | 类型要求 | 描述与使用规则 |
|---|---|---|
| 声明 | 关键字标识符 | 初始化流渲染布局引擎。接受 sankey 或向后兼容的 sankey-beta 字符串。 |
| 源节点 | 字符串标签 | 资源流动开始的起始类别。区分大小写的标识符。 |
| 目标节点 | 字符串标签 | 链接体积终止的目标节点。 |
| 数值 | 正浮点数/整数 | 流量的数值权重。渲染路径的粗细直接根据此值计算。 |
| 注释行 | 语法指示符 | 任何以双百分号（”开头的文本%%将被编译器忽略，从而实现干净的数据注释。 |
处理节点标签中的特殊字符
由于逗号和引号在布局引擎中充当结构系统分隔符，因此特殊命名输入需要特定的转义技术，以确保它们在前端画布上正确显示。
1. 名称中的逗号
如果特定节点标签需要一个字面逗号，请将整个节点字符串容器用一对标准双引号包裹：
2. 名称中的引号
要在标签名称中显式渲染双引号，请将整个参数用外层引号包裹，并在目标值字符串内部使用一对重复的双引号（”""）在目标值字符串内部：
高级主题配置（指令）
您可以通过在文档片段顶部传递一个 frontmatter 配置块来微调图表的显示效果。这使您能够直接从原始文本编辑器中控制链接样式、布局内边距、文本样式和元素对齐方式。
桑基图配置属性矩阵
| 属性名称 | 接受的值 | 视觉结果 |
|---|---|---|
showValues |
true | false |
切换是否将数值流值文本直接打印在节点标签框内。 |
linkColor |
'source' | 'target' | 'gradient' | '#hex' |
确定链接路径的颜色映射。'gradient'在连接的实体之间平滑混合颜色。 |
nodeAlignment |
'justify' | 'left' | 'right' | 'center' |
对齐画布空间网格中的结构列。 |
labelStyle |
'legacy' | '轮廓' |
'轮廓' 在文本后添加背景描边遮罩，以确保在复杂布局中具有高可读性。 |
节点宽度 |
整数（像素） | 设置节点矩形的宽度（默认：10). |
节点间距 |
整数（像素） | 设置堆叠行之间的垂直间距参数（默认：12). |
现实世界蓝图：清洁能源电网分配
此全面的蓝图跟踪一个基础设施电力网格管理系统。它展示了前端配置——设置平滑的链接颜色渐变、轮廓字体样式，并禁用内联指标计数——并配合多层级布局结构。
Mermaid
Edit Mermaid in VPasCode
---
配置：
桑基图：
显示数值：否
链接颜色：'渐变'
节点对齐：'两端对齐'
标签样式：'轮廓'
节点宽度：15
节点间距：18
---
桑基图
%% 源数据行
太阳能农场,电力存储电网,120.50
风力涡轮机,电力存储电网,180.75
水力发电大坝,直接工业线路,210.00
生物燃料进口,热力备用站,45.25
%% 分配节点
电力存储电网,住宅用户线路,145.00
电力存储电网,直接工业线路,110.25
电力存储电网,系统损耗与耗散,46.00
%% 最终交付终止节点
直接工业线路,重型制造中心,295.00
直接工业线路,商业零售领域,25.25
热力备用站,商业零售领域,45.25
常见语法陷阱与系统限制
在编译高度密集的数据数组时，一些细微的配置错误将导致布局解析中断。请牢记以下排查规则：
- 列数精确验证： 主标题声明后的每一行数据都必须恰好包含三个用逗号分隔的参数。添加第四列或遗漏数值权重将完全中断图表的编译。
- 空行允许： 与传统严格的数据解析规则不同，Mermaid 允许你在代码块中添加空的、干净的行，以逻辑上分隔模型数据的不同层级或处理阶段。
- 循环环路限制： 桑基图结构严格基于有向无环图（DAG）。如果你将节点 A 连接到节点 B，然后尝试编写一条从节点 B 回到节点 A 的路径，布局引擎的数学计算将出现反馈中断并报错。
- 数值数据限制： 数值字段只能解析正数。负数或原始字母字符无法被渲染为宽度参数。