Mermaid 圖表語法

Flowchart、Sequence、Class、State、ER、Pie、Gantt 七種圖表的語法與實用範例

本篇涵蓋 Mermaid 最常用的七種圖表類型。每種都附上語法說明和可互動的範例 — 點擊 Source 查看原始碼，Diagram 查看渲染結果。

Flowchart##

最常用的圖表類型，適合流程圖、決策樹、系統架構。

方向###

關鍵字	方向
`TD` / `TB`	上到下
`LR`	左到右
`BT`	下到上
`RL`	右到左

節點形狀###

語法	形狀	適用場景
`A[Text]`	矩形	步驟、動作
`A(Text)`	圓角矩形	一般節點
`A{Text}`	菱形	判斷、決策
`A((Text))`	圓形	起點、終點
`A>Text]`	旗形	標記、事件
`A[[Text]]`	雙框矩形	子流程
`A[(Text)]`	圓柱	資料庫

箭頭類型###

語法	樣式
`-->`	實線箭頭
`-.->`	虛線箭頭
`==>`	粗線箭頭
`---`	實線無箭頭
`-->\|label\|`	帶標籤的箭頭
`<-->`	雙向箭頭

範例：CI/CD Pipeline###

Subgraph 分組###

用 subgraph 將相關節點分組：

Tip

Subgraph 可以巢狀。用 direction LR 在 subgraph 內指定獨立方向。

Sequence Diagram##

描述系統之間的互動時序，最適合 API 呼叫流程和通訊協議。

箭頭類型###

語法	樣式
`->>`	實線 + 實心箭頭（同步請求）
`-->>`	虛線 + 實心箭頭（回應）
`->>+`	實線 + 啟動目標（activate）
`-->>-`	虛線 + 停用目標（deactivate）
`-x`	實線 + 叉號（失敗）
`-)`	實線 + 開放箭頭（非同步）

關鍵語法###

participant A as Alias    # declare participant (box)
actor U as User           # declare participant (person)
Note over A,B: text       # note spanning participants
Note right of A: text     # side note
alt / else / end          # conditional branch
loop / end                # loop
opt / end                 # optional block
par / and / end           # parallel
autonumber                # auto numbering

範例：OAuth 2.0 Flow###

Note

+ 和 - 控制 activation bar（參與者下方的長條）。->>+ 啟動，-->>- 停用。成對使用可以清楚顯示處理時間。

Class Diagram##

描述物件導向設計中的類別關係，適合 API model 設計和型別系統。

關係類型###

語法	關係	說明
`<\|--`	Inheritance	繼承
`*--`	Composition	組合（生命週期相依）
`o--`	Aggregation	聚合（生命週期獨立）
`-->`	Association	關聯
`..>`	Dependency	依賴
`..\|>`	Realization	實作介面

可見性修飾###

符號	意義
`+`	public
`-`	private
`#`	protected
`~`	package/internal

範例：Repository Pattern###

State Diagram##

描述狀態機和生命週期轉換，適合訂單流程、UI 狀態管理。

語法###

[*] --> State          # initial state
State --> [*]          # final state
State1 --> State2 : event   # transition
state State {          # nested state
    [*] --> SubState
}

範例：Order Lifecycle###

Tip

使用 stateDiagram-v2 而非 stateDiagram，v2 版本支援更多功能且是目前推薦的版本。

ER Diagram##

描述資料庫實體關係，適合 schema 設計和資料建模。

Cardinality 符號###

語法	意義
`\|\|`	exactly one
`o\|`	zero or one
`}\|`	one or more
`o{`	zero or more

連接方式：--（identifying）、..（non-identifying）

範例：Blog Schema###

Note

ER Diagram 中可以在實體內定義欄位，用 PK、FK、UK 標註 primary key、foreign key、unique key。

Pie Chart##

最簡單的圖表類型，用於顯示比例分佈。

語法就是 "Label" : value，Mermaid 會自動計算百分比。

Gantt Chart##

專案排程和時間線，適合 roadmap 和 sprint planning。

語法###

gantt
    title Project Title
    dateFormat YYYY-MM-DD
    section Section Name
    Task Name : id, start, duration
    Task Name : after id, duration

狀態標記###

標記	意義
`done`	已完成
`active`	進行中
`crit`	關鍵路徑
`milestone`	里程碑

範例：Product Launch###

Warning

Gantt chart 的 dateFormat 必須與 task 的日期格式一致。常見錯誤是用 DD-MM-YYYY 但 dateFormat 設定為 YYYY-MM-DD。

Selection Guide##

你想表達的	選擇
步驟流程、決策邏輯	Flowchart
系統間的 API 互動	Sequence Diagram
物件導向設計、型別	Class Diagram
狀態轉換、生命週期	State Diagram
資料庫 schema	ER Diagram
比例分佈	Pie Chart
時間排程、Roadmap	Gantt Chart

Quiz##

Single Choice

在 Mermaid Flowchart 中，A{Text} 會渲染成什麼形狀？

Single Choice

在 Sequence Diagram 中，->>+ 的 + 代表什麼？

Multiple Select

以下哪些是 Mermaid 圖表類型的正確配對？

Code Challengepython

寫一個函式 parse_flowchart_edges(mermaid_text)，從 Mermaid flowchart 文字中提取所有邊（edge），回傳 (source, target) 的 list。只需處理 --> 箭頭語法。

Ctrl+Enter to run

Summary##

Flowchart 是最常用的類型，掌握節點形狀和箭頭語法就能應付大多數場景
Sequence Diagram 用 autonumber 和 alt/loop 讓互動流程更清晰
Class Diagram 支援可見性修飾（+/-/#）和完整的 OOP 關係
State Diagram 用 [*] 表示起始和結束，用 stateDiagram-v2 版本
ER Diagram 可以在實體內定義欄位和 key 約束
所有圖表的 label 建議使用英文，含特殊字元時用雙引號包裹
點擊範例的 Source tab 可以查看原始語法，直接複製使用

留言 (0)

登入後即可留言