狀態圖

stateDiagram-v2
  [*] --> Idle
  Idle --> Working : start
  Working --> Idle : pause
  Working --> Done : finish
  Done --> [*]
  note right of Working : 可以中途暫停

timeline:
  enter Working slide-top, enter Idle-Working fade
  enter Working-Idle fade, highlight Working glow
  unhighlight Working, enter Done slide-bottom, enter Working-Done fade
  enter Done-end:1 fade

標頭

stateDiagram 和 stateDiagram-v2 是同一種圖。

狀態與轉移

  • 單獨一行寫 Idle 就宣告了一個狀態;轉移提到的狀態也會自動宣告。狀態 id 只能用英數字和 _。
  • 一行可以寫好幾個敘述,和 Mermaid 相同:單獨的 id 到後面的空白就結束,所以 Foo Bar 宣告兩個狀態,Foo Bar --> Done 宣告 Foo 加上轉移 Bar --> Done。
  • 轉移:A --> B,加標籤寫成 A --> B : 標籤。
  • 自己轉移到自己:A --> A。
  • [*] 寫在箭頭左邊是起點,寫在右邊是終點。每一層(整份文件、每個複合狀態)各只有一個起點和一個終點。單獨一行的 [*] 是這一層的起點,之後的 [*] --> A 從同一個圓點出發。
  • 轉移會停在它碰到的圖形上:<<choice>> 的菱形、[*] 的圓,而不是外面的方框。
  • 敘述的關鍵字不分大小寫:CLASSDEF、STATE C {、Direction Rl 都可以。

描述

stateDiagram-v2
  state "等待中" as Idle
  Idle : 沒有工作
  Idle --> Busy
  • Idle : 描述 或 state "描述" as Idle。as 不會改 id,id 還是 Idle。
  • 描述會取代畫出來的 id。寫了兩條以上的話,第一條會變成標題,下面加分隔線列出其餘的。
  • 太長的描述、引號名稱和 note,文字寬度超過 175px 會自己換行;轉移標籤畫在線上、底下墊一塊主題 --siren-edge-label-fill 的底色,太長的超過 150px 也會換行,和 Mermaid 一樣:英文在空白處拆、中文在任兩個字之間拆,收尾標點不會出現在行首。<br> 寫在哪裡就在哪裡換行。複合狀態的標題不會換行。

保留字

state、note、classDef、class、style、click、scale、href、default、stateDiagram(不分大小寫)這十個 Mermaid 保留的字不能當狀態名稱,也不能當描述的主詞(note : hi),否則會報錯。end、fork、choice、direction 等則可以。

複合狀態

stateDiagram-v2
  [*] --> Active
  state Active {
    [*] --> Loading
    Loading --> Ready
    Ready --> [*]
  }
  Active --> Closed
  • state 名稱 { … },或 state "描述" as 名稱 { … }。
  • 可以巢狀,每一層都有自己的 [*] 起訖點。
  • 轉移可以連到複合狀態本身。
  • 外框的底色是主題的 --siren-subgraph-fill,預設 none,見主題。
  • 必須跨多行寫,state X { A --> B } 寫在一行會報錯。

並行區域

在複合狀態裡用只有 -- 的一行分隔並行區域:

stateDiagram-v2
  state Running {
    [*] --> Audio
    --
    [*] --> Video
  }

-- 只能寫在複合狀態裡。

選擇、分岔、合併

stateDiagram-v2
  state Check <<choice>>
  state Split <<fork>>
  state Merge <<join>>
  [*] --> Check
  Check --> Split : ok
  Check --> [*] : fail
  Split --> A
  Split --> B
  A --> Merge
  B --> Merge
  • <<choice>> 畫成菱形,<<fork>> 和 <<join>> 畫成粗橫條,都不顯示文字。
  • 標記必須寫在第一次提到這個狀態的那一行,之後才補上的不會生效(和 Mermaid 相同)。
  • [[fork]] 寫法不支援。

Note

  • note right of Idle : 文字、note left of Idle : 文字。左右不分大小寫,而且寫哪邊就畫哪邊:note LEFT OF X 畫在左邊,Mermaid 則會畫在右邊。
  • 多行 note:單獨一行 note right of Idle,接著是文字,最後 end note。每個非空白行是一列。
  • note right of [*] : 文字 掛在這一層的起點上;這一層沒有起點時會報錯,Mermaid 也畫不出來。
  • 每個狀態最多一個 note,後寫的會取代先寫的。
  • note 的連接線會停在狀態畫成的圖形上:[*] 的圓點、<<choice>> 的菱形。
  • note "文字" as N(浮動 note)會被接受但不畫出來,和 Mermaid 相同。

方向

direction TB、TD、BT、LR、RL。文件層級以第一個為準。寫在複合狀態或並行區域裡只影響那一層,但只要有一條轉移兩端的父層不同、又穿過它,它就會放棄自己的方向:一端在裡面(不管多深)、一端在外面就算,兩端都是它自己的成員但巢狀深度不同也算。這樣的轉移會讓從兩端往上、直到兩端最近的共同複合狀態(含)的每一層都放棄方向,改成照上一層排它的成員的方式排:外層複合狀態保有的方向、外層沒寫方向就由上往下、最外層則用整份文件的,和 Mermaid 12 相同。從旁邊直接連到複合狀態本身的轉移,或複合狀態連到自己,都不算。沒寫 direction 的複合狀態和並行區域一律由上往下排,不管文件的方向是什麼,和 Mermaid 相同。note 的連接線不會讓複合狀態放棄方向;Mermaid 的會。

樣式

stateDiagram-v2
  Idle --> Error
  classDef bad fill:#fee2e2,stroke:#dc2626
  class Error bad
  style Idle fill:#dbeafe,stroke:#2563eb
  • classDef 名稱 屬性:值,... 定義,class A,B 名稱 套用。class 後面的字一個字一個名稱,和 Mermaid 畫的一樣:class A c extra 套用 c,class Busy a,b 套用一個叫 a,b 的類別,而它沒有任何 classDef 定義。套用沒有定義的類別是警告:狀態照畫,只是沒有樣式。
  • style A 屬性:值,... 把宣告直接寫到狀態上,style A,B ... 則寫到每一個。style 和套在同一個狀態上的類別,不管哪一行先寫都是 style 贏,和 Mermaid 相同。
  • 複合狀態也可以上樣式;轉移不行。
  • timeline 的 highlight 一律贏過作者寫的 stroke:狀態被強調時,outline 和 glow 用強調色畫它的外框,結束後再把作者的還回去。

無障礙

accTitle: 標題、accDescr: 描述 和大括號的 accDescr { ... } 區塊是圖的無障礙標題與描述,不分大小寫,以最後一個為準。

Timeline 目標

元素 id 例子
狀態、複合狀態 狀態名稱(選擇、分岔、合併也是) Idle、Active
起點、終點 start:N、end:N,N 是層級編號 start:1、end:1
並行區域 region:N,依原始碼順序 region:1
轉移 起點-終點,重複的加 #2;[*] 用它的 id Idle-Working、start:1-Idle、Done-end:1
  • 層級編號:整份文件是 1,接著每個複合狀態依第一次宣告的順序編號,再來是它們的並行區域。沒用到 [*] 的層級也會占一個號碼。
  • note 沒有自己的 id,會跟著它所屬的狀態一起動。

尚未支援

語法 目前的行為
A:::名稱 不會報錯,但會把 ::名稱 當成描述畫出來,請改用 class A 名稱
note over X 報錯
hide empty description、click、scale 報錯