Markdown 狀態圖

1. 前言

Markdown 的原生語法不支持繪制圖形，但通過擴展模塊，我們可以將一些格式化的文字渲染成我們需要的圖形。常用的圖形有 “流程圖”、“時序圖”、“類圖”、“狀態圖”、“甘特圖”、"餅圖" 等。

本節將重點介紹如何通過 Mermaid 繪制「狀態圖」。

狀態圖 (Statechart) 是描述一個實體基于事件反應的動態行為，是使對象達到某種狀態的事件、條件或操作的圖形化描述。

一個完整的狀態圖由狀態、轉換組成。

環境說明：
考慮到 Markdown 工具之間的不兼容，有的內容直接從頁面復制粘貼到本地不會正常顯示，大家學習時自己動手寫是肯定沒問題的。本節所有實例代碼及演示效果均使用 Typora 工具完成。
Mermaid 為 Markdown 擴展語法，需要在 Typora 設置中開啟對圖表的語法支持。其方式為：「設置」->「Markdown」->「Markdown 擴展語法」-> 勾選「圖表」，如下圖：

2. 語法詳解

2.1 狀態圖中的「狀態」

狀態代表某一對象在某一特定的條件、時間下所保持的靜態值。

使用 Mermaid 擴展繪制狀態圖時，有多種方式聲明一個狀態節點。

實例 1：

通過設置狀態 ID 聲明狀態

?```mermaid
stateDiagram
    狀態1
?```

上述代碼將會渲染成如下效果：

實例 2：

使用 「state」關鍵字來描述共同聲明狀態節點。

?```mermaid
stateDiagram
    state "狀態描述性文字" as 狀態2
?```

上述代碼將會渲染成如下效果：

實例 3：

使用「狀態 ID + 冒號」的方式簡化狀態節點的聲明。

?```mermaid
stateDiagram
    狀態3 : 狀態3的文字描述
?```

上述代碼將會渲染成如下效果：

2.2 狀態圖中的「轉換」

「轉換」在狀態圖中表現為連接兩個狀態節點的單向箭頭，在 Mermaid 擴展語法中的寫法為「字符箭頭 -->」。

實例 4：

用單向箭頭表示轉換。

?```mermaid
stateDiagram
    狀態1 --> 狀態2
?```

此代碼渲染效果如下：

通過 (行內容):label 的形式，為轉換添加描述文本。

實例 5：

增加描述。

?```mermaid
stateDiagram
    狀態1 --> 狀態2: 咻~
?```

渲染效果如下：

狀態圖中有兩個特殊的狀態節點：開始節點和結束節點。如果需要在狀態圖中顯示開始或結束節點，可以通過 [*] 方式聲明。

實例 6：

增加開始和結束節點。

?```mermaid
stateDiagram
    [*] --> 狀態節點
    狀態節點 --> [*]
?```

渲染結果如下：

2.3 狀態圖中的「嵌套」

在負責的狀態描述中，有的狀態節點會包含一系列的子狀態，我們可以用組合「嵌套」的方式來描繪它們。在 Mermaid 擴展中，描述嵌套的方式，是使用「花括號 {}」描述子狀態。

實例 7：

?```mermaid
stateDiagram
    [*] --> 父狀態節點
    state 父狀態節點 {
        [*] --> 子狀態節點
        子狀態節點 --> [*]
    }
?```

渲染結果如下：

「嵌套」的層數沒有限制。

實例 8：

多層嵌套。

?```mermaid
stateDiagram
    [*] --> 第一層狀態節點

    state 第一層狀態節點 {
        [*] --> 第二層

        state 第二層 {
            [*] --> 第二層
            第二層 --> 第三層

            state 第三層 {
                [*] --> 第三層
                第三層 --> [*]
            }
        }
    }
?```

渲染效果如下：

狀態轉換可以在「嵌套」的外層，也就是群組間實現。

實例 9：

群組之間的嵌套。

?```mermaid
stateDiagram
    [*] --> 第一層
    第一層 --> 第二層
    第一層 --> 第三層

    state 第一層 {
        [*] --> 第一層子節點
        第一層子節點 --> [*]
    }
    state 第二層 {
        [*] --> 第二層子節點
        第二層子節點 --> [*]
    }
    state 第三層 {
        [*] --> 第三層子節點
        第三層子節點 --> [*]
    }
?```

渲染效果如下：

2.4 狀態圖中的「分支」

對于非單一結果的狀態轉換，我們可以使用 <<fork>> 和 <<join>> 標簽實現。

實例 10：

使用 <<fork>> 描述分支，使用 <<join>> 描述聚合。

?```mermaid
stateDiagram
    state 分支 <<fork>>
      [*] --> 分支
      分支 --> 分支2
      分支 --> 分支3

      state 合并 <<join>>
      分支2 --> 合并
      分支3 --> 合并
      合并 --> 狀態4
      狀態4 --> [*]
?```

渲染效果如下：

2.5 狀態圖中的「并行」

對于一些同步完成的狀態轉換，我們可以用 -- 符號聲明并行效果。

實例 11：

?```mermaid
stateDiagram
        [*] --> 激活狀態

        state 激活狀態 {
            [*] --> NumLock關
            NumLock關 --> NumLock開 : 按下 NumLock 鍵
            NumLock開 --> NumLock關 : 按下 NumLock 鍵
            --
            [*] --> CapsLock關
            CapsLock關 --> CapsLock開 : 按下 CapsLock 鍵
            CapsLock開 --> CapsLock關 : 按下 CapsLock 鍵
            --
            [*] --> ScrollLock關
            ScrollLock關 --> ScrollLock開 : 按下 ScrollLock 鍵
            ScrollLock開 --> ScrollLock關 : 按下 ScrollLock 鍵
        }
?```

渲染效果如下：

2.6 為狀態圖增加「備注」

有時候圖表元素不能完全表達我們的設計思路，這時候需要在圖中加入文字描述。在 Mermaid 語法中，使用 note <right|left> of <state ID> 備注內容 end notes 的方式，將備注添加到狀態節點的右側（左側）。

實例 12：

?```mermaid
stateDiagram
        狀態1 : 描述將出現在右側
        note right of 狀態1
            這里添加描述內容
        end note
        狀態1 --> 狀態2
        note left of 狀態2 : 在節點左側添加描述
?```

渲染效果如下：

3. 使用場景及實例

狀態圖專門用于表示依賴于狀態的行為。

實例 13：

出貨狀態示意圖。

?```mermaid
stateDiagram
        [*] --> 下單成功
        下單成功 --> 備貨
        state 出貨中 <<fork>>
        備貨 --> 出貨中
        出貨中 --> 出貨失敗
        出貨失敗 --> [*]
        出貨中 --> 出貨確認
        出貨確認 --> 出貨完畢
        出貨完畢 --> 訂單完成
        訂單完成 --> [*]
?```

其渲染效果如下：

4. 小結

• Mermaid 為 Markdown 擴展了使用普通文本生成狀態圖的語法及渲染支持；
• Mermaid 狀態圖的基本元素包含「狀態節點」、「轉換」；
• Mermaid 狀態圖還可以將節點合并，實現「嵌套」的效果；
• Mermaid 狀態圖的邏輯支持「分支」、「并行」；
• Mermaid 狀態圖還可以通過「備注」的方式，為狀態圖提供更多的細節描述。