Sankey 圖表是極其有效的視覺化工具，用於呈現系統中不同節點之間數量的流向。透過將連接連結的物理寬度按數值流動量成比例縮放，工程師、分析師和運營團隊能立即識別出複雜網絡（如能源網絡、供應鏈和金融投資組合）中的主要貢獻者、資源配置、效率低下或洩漏點。
基本語法結構
Sankey 布局定義建立在優化的三欄 CSV（逗號分隔值）結構格式之上。每個檔案都以「sankey」或「sankey-beta」類型宣告標頭開始，後接單獨的流動行，遵循嚴格的「來源,目標,數值」模式。
語法參考
下表分解了在 Mermaid.js 中正確解析 Sankey 圖表所需的主數據規則與參數。
| 語法元素 | 類型要求 | 描述與使用規則 |
|---|---|---|
| 宣告 | 關鍵字識別符 | 初始化串流渲染佈局引擎。接受sankey或向後相容的sankey-beta字串。 |
| 來源節點 | 字串標籤 | 資源流動開始的原始類別。區分大小寫的識別符。 |
| 目標節點 | 字串標籤 | 特定連結量終止的接收節點。 |
| 數值 | 正浮點數 / 整數 | 流量的數值權重。渲染路徑的粗細直接根據此值計算。 |
| 註解行 | 語法指示符 | 任何以雙百分比符號（”%%）的內容會被編譯器忽略，從而允許進行乾淨的資料註解。 |
處理節點標籤中的特殊字元
由於逗號和引號在佈局引擎中作為結構性系統分隔符，特殊命名輸入需要特定的轉義技術，以確保它們在前端畫布上正確顯示。
1. 名稱中的逗號
如果特定節點標籤需要文字逗號，請將整個節點字串容器包在標準雙引號內：
2. 名稱中的引號
若要明確在標籤名稱中顯示雙引號，請將整個參數包在外部引號中，並在目標值字串內使用一對重複的雙引號（”""）在目標值字串內：
進階主題設定（指令）
您可以在文件片段的頂部傳遞一個 frontmatter 設定區塊，以微調圖表的呈現方式。這讓您能直接從原始文字編輯器中控制連結樣式、佈局邊距、文字樣式和元素對齊。
Sankey 設定屬性矩陣
| 屬性名稱 | 接受的值 | 視覺結果 |
|---|---|---|
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，版面引擎的數學運算將產生反饋中斷並報錯。
- 數值資料限制： 數值欄位只能解析正數。負數或原始字母字元無法轉換為寬度參數。