Mermaid.js 状态图语法指南

什么是状态图？

一个状态图（也称为状态图）是一种行为UML 图，用于建模单个对象或子系统的有限生命周期。被认定为一种核心UML 图类型，它展示了实体可以处于的离散状态（条件），外部事件或触发器导致状态间转换（转换），以及改变执行路径的条件规则分支。这种映射对于追踪复杂对象生命周期至关重要，例如订单从履行到交付的进展、用户会话超时序列，或嵌入式硬件开关循环。

使用Mermaid.js，你可以使用声明式、基于文本的模式来定义你的响应式状态机。解析引擎会自动计算最优布局间距，处理递归循环箭头，并平滑地调整状态容器边界的大小。

核心语法指南：元素与结构

要在 Mermaid 中设计准确且符合标准的 UML 状态图，你必须掌握入口/出口标记、转换字符串、复合嵌套以及条件选择块。

1. 定义入口、出口和标准状态

你可以在第一行使用stateDiagram-v2关键字来初始化状态画布。生命周期需要明确的起始和终止点，它们由实心圆符号（[*]):

• 初始状态（入口）： [*] --> 状态名称（标记生命周期的开始位置）。
• 终止状态（出口）： 状态名称 --> [*]（标记生命周期的结束位置）。

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

2. 配置转换触发器和事件标签

要映射状态变化，请使用标准箭头线连接您定义的状态标记（”-->）。要记录导致此转换的精确事件、API 响应或按钮单击，请在末尾添加冒号（”:）后跟您的描述性文本字符串：

stateDiagram-v2
    Active --> Suspended : PaymentFailed
    Suspended --> Active : InvoiceSettled

3. 实现条件选择块

要处理分支评估循环，请使用<<choice>>样式。这会在画布上创建一个清晰的菱形，根据运行时逻辑检查，将单一的入站转换路径拆分为多个不同的出站路径：

stateDiagram-v2
    state check_status <<choice>>
    [*] --> check_status
    check_status --> PremiumUser : if balance >= 100
    check_status --> StandardUser : if balance < 100

4. 构建复合（嵌套）状态

在建模复杂系统时，一个单一的高层状态可以包含其自身独立的内部生命周期。您可以通过定义父状态，然后使用花括号包裹一个主体块来创建嵌套的子状态布局：

stateDiagram-v2
    state OrderProcessing {
        [*] --> Packaging
        Packaging --> Labeling
    }

清晰状态机布局的最佳实践

• 保持状态标记简短： 为内部状态标记使用简短的驼峰命名文本字符串（例如，AwaitingRefund）。如果需要在画布上显示较长的描述性标题，请使用state "描述性文本块" as Token 语法用于创建显式别名。
• 强制使用单一入口点： 始终从一个单一的[*] 节点开始。拥有多个起点可能会让用户在追踪系统根初始化路径时感到困惑。
• 始终使用 stateDiagram-v2： 始终选择stateDiagram-v2 关键字，而不是旧版的stateDiagram 标志。v2 渲染引擎使用了更新的布局算法，可提供更清晰的线路路由和更好的嵌套框对齐。

现实世界中的 Mermaid.js 状态图示例

示例 1：数字钱包交易生命周期（选择分支与失败循环）

此功能蓝图模拟了数字支付交易的生命周期，展示了交易如何从初始提交点，经过欺诈检查分支，进入最终的账本状态。

stateDiagram-v2
    state fraud_check <<choice>>

    [*] --> TransSubmitted
    TransSubmitted --> fraud_check : 执行风险评估

    fraud_check --> TransApproved : 风险评分低
    fraud_check --> TransFlagged : 风险评分升高
    
    TransFlagged --> TransApproved : 手动经理覆盖
    TransFlagged --> TransDeclined : 安全超时
    
    TransApproved --> SettlementPending : 提交账本
    SettlementPending --> TransCompleted : 银行结算成功
    
    TransDeclined --> [*]
    TransCompleted --> [*]

语法解析： 此工作流利用一个<<choice>> 块在开始时评估安全评分。交易根据这些评分沿着不同的路径进行转换，并在转换箭头上清晰地标记事件名称（例如执行风险评估），直接记录在转换箭头上。

示例 2：电子商务订单履行流水线（复合嵌套系统）

此高级企业蓝图概述了完整的发货和订单管理生命周期，使用嵌套的复合块来展示履行阶段内部发生的操作。

stateDiagram-v2
    [*] --> OrderPlaced
    
    OrderPlaced --> InFulfillment : 支付已捕获
    
    state InFulfillment {
        [*] --> ItemPicking
        ItemPicking --> QualityAudit : 批次已选取
        QualityAudit --> SecureBoxPacking : 审核通过
        SecureBoxPacking --> CarrierManifest Generated : 标签已打印
    }
    
    InFulfillment --> Shipped : 承运商交接
    Shipped --> Delivered : 已确认派送
    
    Delivered --> [*]

语法分解： 通过将步骤包裹在 state InFulfillment {...} body 块中，您在画布上创建了一个清晰的结构边界。引擎在渲染其内部工作流步骤时，会将此块视为一个单一的合并父状态，按顺序执行，从而使复杂的多层生命周期变得易于导航。