Markdown 状态图绘制详解

??作者简介：小北编程（专注于HarmonyOS、Android、Java、Web、TCP/IP等技术方向）
🐳博客主页： 开源中国、稀土掘金、51cto博客、博客园、知乎、简书、慕课网、CSDN
🔔如果文章对您有一定的帮助请👉关注?、点赞👍、收藏📂、评论💬。
🔥如需转载请参考【转载须知】

一、前言

Markdown 的原生语法不支持绘制图形，但通过扩展模块，我们可以将一些格式化的文字渲染成我们需要的图形。常用的图形有 “流程图”、“时序图”、“类图”、“状态图”、“甘特图”、“饼图” 等。

本节将重点介绍如何通过 Mermaid 绘制「状态图」。

状态图 (Statechart) 是描述一个实体基于事件反应的动态行为，是使对象达到某种状态的事件、条件或操作的图形化描述。

二、状态图简介

状态图是一种描述对象在不同状态之间转换的图形工具。在软件工程中，状态图通常用于建模有限状态机（Finite State Machine，FSM），表示系统在特定条件下从一个状态切换到另一个状态。Markdown 提供了一种简单而直观的方式来绘制状态图，使得开发者能够更清晰地理解和展示系统的状态变化。

三、语法详解

3.1 新旧写法

Mermaid 可以渲染状态图。语法试图与 plantUml 中使用的语法相一致，因为这将使用户更容易在 mermaid 和 plantUml 之间分享图表。

旧的写法：

```mermaid
stateDiagram
    老写法
```

新写法：

```mermaid
stateDiagram-v2
    新写法
```

新老写法区别不大就是后缀多了一个 v2

3.2 状态

可以通过多种方式声明状态。最简单的方法是定义一个状态id作为描述。

```mermaid
stateDiagram-v2
    s1
```

另一种方法是使用状态关键字和描述：

```mermaid
stateDiagram-v2
    state "这是一个状态描述" as s2
```

另一种方法是使用状态关键字和描述：

```mermaid
stateDiagram-v2
    s2 : 这是一个状态描述
```

3.3 转换

「转换」在状态图中表现为连接两个状态节点的单向箭头，在 Mermaid 扩展语法中的写法为「字符箭头 -->」。

转换是一种状态进入另一种状态时的路径/边线。使用箭头 --> 表示。

```mermaid
stateDiagram-v2
    s1 --> s2
```

可以将文本添加到转换中，描述它代表什么：

```mermaid
stateDiagram-v2
    s1 --> s2: 一个转换
```

3.4 开始和结束

有两种特殊状态表示图的开始和停止。用 [*] 语法，转换到它的方向将其定义为开始或停止状态。

```mermaid
stateDiagram-v2
    [*] --> s1
    s1 --> [*]
```

3.5 嵌套

单嵌套

在负责的状态描述中，有的状态节点会包含一系列的子状态，我们可以用组合「嵌套」的方式来描绘它们。在 Mermaid 扩展中，描述嵌套的方式，是使用「花括号 {}」描述子状态。

```mermaid
stateDiagram-v2
   [*] --> 父状态节点
    state 父状态节点 {
     	[*] --> 子状态节点
     	子状态节点 --> [*]
    }
```

多层嵌套

在负责的状态描述中，有的状态节点会包含一系列的子状态，我们可以用组合「嵌套」的方式来描绘它们。在 Mermaid 扩展中，描述嵌套的方式，是使用「花括号 {}」描述子状态。

```mermaid
stateDiagram-v2
    [*] --> 第一层状态节点
    
    state 第一层状态节点 {
    	[*] --> 第二层
    	 state 第二层 {
    		[*] --> 第三层
    		state 第三层 {
    			[*] --> 第四层
    			第四层 --> [*] 
    		}
   	 	}
    }
```

状态转换可以在「嵌套」的外层，也就是群组间实现。

群组之间嵌套

```mermaid
stateDiagram-v2
    [*] --> 第一层
    第一层 --> 第二层
    第一层 --> 第三层

    state 第一层 {
        [*] --> 第一层子节点
        第一层子节点 --> [*]
    }
    state 第二层 {
        [*] --> 第二层子节点
        第二层子节点 --> [*]
    }
    state 第三层 {
        [*] --> 第三层子节点
        第三层子节点 --> [*]
    }
```

3.6 选择

有时您需要在两条或多条路径之间设定选择模型，您可以使用 <> 进行建模。

```mermaid
stateDiagram-v2
    state if_state <<choice>>
    [*] --> IsPositive
    IsPositive --> if_state
    if_state --> False: if n < 0
    if_state --> True : if n >= 0
```

3.7 分叉

可以使用 <> <> 在图中指定一个分叉。

```mermaid
stateDiagram-v2
 state fork_state <<fork>>
   [*] --> fork_state
   fork_state --> State2
   fork_state --> State3

   state join_state <<join>>
   State2 --> join_state
   State3 --> join_state
   join_state --> State4
   State4 --> [*]
```

3.8 说明 Notes

有时没有什么比“便利贴说明”更好用的了，在状态图中也是如此。
可以选择将说明放在节点的右侧或左侧。

```mermaid
stateDiagram-v2
    State1: The state with a note
    note right of State1
        Important information! You can write
        notes.
    end note
    State1 --> State2
    note left of State2 : This is the note to the left.
```

3.9 并发

就像在plantUml中一样，您可以使用 – 指定并发。

```mermaid
stateDiagram-v2
    [*] --> Active

    state Active {
        [*] --> NumLockOff
        NumLockOff --> NumLockOn : EvNumLockPressed
        NumLockOn --> NumLockOff : EvNumLockPressed
        --
        [*] --> CapsLockOff
        CapsLockOff --> CapsLockOn : EvCapsLockPressed
        CapsLockOn --> CapsLockOff : EvCapsLockPressed
        --
        [*] --> ScrollLockOff
        ScrollLockOff --> ScrollLockOn : EvScrollLockPressed
        ScrollLockOn --> ScrollLockOff : EvScrollLockPressed
    }
```

3.10 设置图表的方向

对于状态图，你可以使用方向语句来设置图渲染的方向，如本例所示。

```mermaid
stateDiagram-v2
    direction LR
    [*] --> A
    A --> B
    B --> C
    state B {
      direction LR
      a --> b
    }
    B --> D
```

在Mermaid中，状态图（stateDiagram）可以通过设置图表的方向来控制状态之间的布局。Mermaid支持六个主要的方向，它们分别是：

符号/术语	含义
TB	从上到下（Top to Bottom）的流程方向
BT	从下到上（Bottom to Top）的流程方向
LR	从左到右（Left to Right）的流程方向
RL	从右到左（Right to Left）的流程方向
HZ	水平方向（Horizontal）的流程方向
VT	垂直方向（Vertical）的流程方向

3.11 注解

可以在状态图里写注释，解析器将忽略该注释。注释需要单独起一行并且必须以 %% 开头。注释开始到下一个换行符之后的任何文本都将被视为注释，包括任何图的语法。

```mermaid
stateDiagram-v2
    [*] --> 静止
    静止 --> [*]
%% this is a comment
    静止 --> 运动
    运动 --> 静止 %% another comment
    运动 --> 撞毁
    撞毁 --> [*]
```

四、使用场景及实例

出货状态示意图。

```mermaid
stateDiagram-v2
        [*] --> 下单成功
        下单成功 --> 备货
        state 出货中 <<fork>>
        备货 --> 出货中
        出货中 --> 出货失败
        出货失败 --> [*]
        出货中 --> 出货确认
        出货确认 --> 出货完毕
        出货完毕 --> 订单完成
        订单完成 --> [*]
```

stateDiagram-v2
   direction TB

   accTitle: This is the accessible title
   accDescr: This is an accessible description

   classDef notMoving fill:white
   classDef movement font-style:italic
   classDef badBadEvent fill:#f00,color:white,font-weight:bold,stroke-width:2px,stroke:yellow

   [*]--> Still
   Still --> [*]
   Still --> Moving
   Moving --> Still
   Moving --> Crash
   Crash --> [*]

   class Still notMoving
   class Moving, Crash movement
   class Crash badBadEvent
   class end badBadEvent

五、总结

Mermaid 为 Markdown 扩展了使用普通文本生成状态图的语法及渲染支持；
Mermaid 状态图的基本元素包含「状态节点」、「转换」；
Mermaid 状态图还可以将节点合并，实现「嵌套」的效果；
Mermaid 状态图的逻辑支持「分支」、「并行」；
Mermaid 状态图还可以通过「备注」的方式，为状态图提供更多的细节描述。

文章写作不易，您的支持是我最大的动力，请👉关注?、点赞👍、收藏📂、评论💬。

---

无论是哪个阶段，坚持努力都是成功的关键。不要停下脚步，继续前行，即使前路崎岖，也请保持乐观和勇气。相信自己的能力，你所追求的目标定会在不久的将来实现。加油！