Mermaid.js 狀態圖語法指南

什麼是狀態圖？

一個狀態圖（又稱為狀態圖）是一種行為UML 圖，用來模擬單一物件或子系統的有限生命週期。被視為核心UML 圖類型，它展示了實體可能處於的離散條件（狀態）、促使狀態之間轉移的外部事件或觸發條件（轉移），以及改變執行路徑的條件性規則分支。這種映射對於追蹤複雜物件生命週期至關重要，例如訂單從履行到交付的進展、使用者會話逾時序列，或嵌入式硬體開關迴圈。

使用Mermaid.js，您可以使用宣告式、以文字為導向的架構來定義反應式狀態機。解析引擎會自動計算最佳佈局間距，處理遞迴迴圈箭頭，並平滑地調整狀態容器邊界。

核心語法指南：元素與構造

要在 Mermaid 中設計出準確且符合標準的 UML 狀態圖，您必須掌握進入/離開標記、轉移字串、複合巢狀結構以及條件選擇區塊。

1. 定義進入、離開與標準狀態

您可以在第一行使用stateDiagram-v2關鍵字來初始化狀態畫布。生命週期需要明確的起點與終點，以實心圓形符號（[*]):

• 初始狀態（進入）： [*] --> 狀態名稱（標示生命週期的起點）。
• 終止狀態（離開）： 狀態名稱 --> [*]（標示生命週期的結束點）。

stateDiagram-v2
    [*] --> 空閒
    空閒 --> [*]

2. 設定轉換觸發條件和事件標籤

要繪製狀態變更，請使用標準箭頭線連接您定義的狀態標記（”-->）。要記錄導致此轉換的精確事件、API 回應或按鈕點擊，請在後面加上冒號（”:）再接上您的描述性文字字串：

stateDiagram-v2
    進行中 --> 暫停中 : 付款失敗
    暫停中 --> 進行中 : 帳單結清

3. 實作條件選擇區塊

要處理分支評估迴圈，請使用<<choice>>範式。這會在畫布上產生一個清晰的菱形，根據執行時期的邏輯檢查，將單一的入站轉換路徑拆分成多個不同的出站路徑：

stateDiagram-v2
    state 檢查狀態 <<choice>>
    [*] --> 檢查狀態
    檢查狀態 --> 高級使用者 : 如果餘額 >= 100
    檢查狀態 --> 標準使用者 : 如果餘額 < 100

4. 結構化複合（巢狀）狀態

在建模複雜系統時，單一的高階狀態可以包含其自身的獨立內部生命週期。您可透過定義父狀態，再接上以大括號包覆的內容區塊，來建立巢狀子狀態佈局：

stateDiagram-v2
    state 訂單處理 {
        [*] --> 包裝
        包裝 --> 標籤
    }

建立清晰狀態機佈局的最佳實務

• 保持狀態標記簡短： 為您的內部狀態標記使用簡短的駝峰式文字字串（例如，等待退款）。如果您需要在畫布上使用長篇描述性標題，請使用state "描述性文字區塊" as Token 語法以建立明確別名。
• 強制使用單一入口點： 始終從單一[*] 節點開始。擁有多个起始點可能會讓試圖追蹤系統根初始化路徑的使用者感到困惑。
• 始終使用 stateDiagram-v2： 始終選擇stateDiagram-v2 關鍵字，而非舊版stateDiagram 標誌。v2 渲染引擎使用更新的佈局演算法，可提供更清晰的線路路由與更佳的嵌套框對齊。

現實世界中的 Mermaid.js 狀態圖範例

範例 1：數位錢包交易生命週期（選擇分支與失敗循環）

此功能藍圖模擬數位支付交易的生命週期，展示交易如何從初始提交點，經過詐欺檢查分支，進入最終的帳本狀態。

stateDiagram-v2
    state fraud_check <<choice>>

    [*] --> TransSubmitted
    TransSubmitted --> fraud_check : ExecuteRiskAssessment

    fraud_check --> TransApproved : 風險分數低
    fraud_check --> TransFlagged : 風險分數提高
    
    TransFlagged --> TransApproved : 手動管理員覆蓋
    TransFlagged --> TransDeclined : 安全超時
    
    TransApproved --> SettlementPending : 提交帳本
    SettlementPending --> TransCompleted : 銀行結算成功
    
    TransDeclined --> [*]
    TransCompleted --> [*]

語法解析： 此工作流程使用<<choice>> 模塊在起始階段評估安全分數。交易根據這些分數沿著不同的路徑轉移，並在轉移箭頭上明確標註事件名稱（例如ExecuteRiskAssessment）直接記錄在轉移箭頭上。

範例 2：電子商務訂單履行管道（複合嵌套系統）

此進階企業藍圖概述了完整的運送與訂單管理生命週期，利用嵌套的複合區塊來展示履行階段內發生的內部運作。

stateDiagram-v2
    [*] --> OrderPlaced
    
    OrderPlaced --> InFulfillment : 支付已扣款
    
    state InFulfillment {
        [*] --> ItemPicking
        ItemPicking --> QualityAudit : 批次已挑選
        QualityAudit --> SecureBoxPacking : 審核通過
        SecureBoxPacking --> CarrierManifest Generated : 標籤已列印
    }
    
    InFulfillment --> Shipped : 承運商握手
    Shipped --> Delivered : 已出貨確認
    
    Delivered --> [*]

語法分解： 透過將步驟包裝在 state InFulfillment {...} body 範圍內，您在畫布上建立了一個清晰的結構邊界。引擎在渲染其內部工作流程步驟時，會將此範圍視為單一整合的父狀態，依序進行，使複雜的多層級生命週期變得容易導航。