流程圖
flowchart LR
A([Start]) --> B{OK?}
B -->|yes| C[(Database)]
B -- no --> D[/Input/]:::warn
C & D ==> E(((End)))
subgraph grp [Retry]
direction TB
F --> G
end
E -.-> grp
classDef warn fill:#fde68a,color:#92400e
timeline:
enter C slide-right, enter B-C fade
enter D slide-bottom, enter B-D fade, highlight D glow
enter subgraph:1 fade, enter E-grp fade
標頭與方向
flowchart 和 graph 意思相同,後面一定要接方向:
| 方向 | 意思 |
|---|---|
TB、TD |
由上而下 |
BT |
由下而上 |
LR |
由左而右 |
RL |
由右而左 |
方向要大寫,標頭後面不能接分號。只在 subgraph 裡可以用 direction 另外指定方向:寫在 subgraph 外面的 direction LR 不會有作用,整張圖維持標頭的方向,並發出警告。
註解
- 一行開頭(忽略前面的空白)是
%%的才是註解。寫在一行中間的%%不是註解:在節點標籤、連線標籤、subgraph 標題或click提示文字裡會當成文字保留(A[50 %% done]畫出「50 %% done」);接在完整敘述後面(A --> B %% note)則會報錯,提示把註解移到獨立的一行。 - 整行只有
%%也會報錯;請寫成%% 文字,或留空行。 - 在
timeline:區塊裡,%%寫在一行的任何位置都是註解。
節點
節點 id 由英數字、_、. 和 - 組成(例如 step1、api.v2、a-b);- 後面不能接 >、- 或 .,因為那會變成箭頭的開頭。只寫 id 的話,會畫成以 id 為標籤的矩形。
id 不能是 end、style、class、subgraph、graph 這類關鍵字,也不能以關鍵字開頭再接標點(end-x、style.x、A --> end 都會報錯,錯誤訊息會建議 endX 這樣的名字)。只是包含這個字的 id(endX、end_x、A-end)沒有問題。
| 語法 | 形狀 |
|---|---|
A[文字] |
矩形 |
A(文字) |
圓角矩形 |
A([文字]) |
體育場形 |
A[[文字]] |
子程序 |
A[(文字)] |
圓柱(資料庫) |
A((文字)) |
圓形 |
A(((文字))) |
雙圓 |
A>文字] |
旗形 |
A{文字} |
菱形(判斷) |
A{{文字}} |
六角形 |
A[/文字/] |
平行四邊形 |
A[\文字\] |
反向平行四邊形 |
A[/文字\] |
梯形 |
A[\文字/] |
倒梯形 |
形狀資料區塊
flowchart LR
A@{ shape: cloud, label: "網際網路" } --> B@{ shape: doc, label: "報表" }
C[佇列]@{ shape: h-cyl }
D@{
shape: person
label: "讀者"
}
A@{ … }用 YAML 指定節點的形狀和文字:寫在一行是 flow mapping,跨行就是 block YAML(引號字串裡的換行會畫成<br/>)。可以寫在節點自己的一行、連線的任一端、括號或:::名稱之後(A[x]:::c@{ shape: circle }),也可以加在前面已經寫過的節點上,原本的文字會保留。@前面不能有空白,}後面不能有東西,一個節點只能有一個區塊;寫在 subgraph 的 id 上會報錯。shape:指定形狀。上面表格的十四種括號形狀都可以用名字指定:rect、rounded、stadium、fr-rect、cyl、circle、dbl-circ、odd、diam、hex、lean-r、lean-l、trap-b、trap-t,以及它們的別名,例如db、decision、subroutine。其餘的列在下面的表格。不是形狀的名字(foo、Rect)會報錯;Siren 不認得的 key 會略過並發出警告。label:指定文字,會當成 Markdown 字串讀,除非labelType是text或string。icon: "prefix:name"從嵌入頁面註冊的圖示包畫出圖示,48px 見方或h像素,form可以是square、rounded或circle,標籤在圖示下方,pos: t改成上方。Playground 沒有註冊任何圖示包,所以在 Playground 裡圖示節點會報錯。img: "data:image/…"以原始大小畫出圖片,或用w、h指定(constraint: on維持比例),標籤在下方,pos: t改成上方。只畫 data URL;其他網址的圖片會報錯,提示把圖片嵌進文件。支援 PNG、GIF、JPEG、WebP 和 SVG,4 MB 以內。
| 形狀 | 名稱 |
|---|---|
| 缺角矩形(卡片) | notch-rect、card、notched-rectangle |
| 缺角五邊形(迴圈上限) | notch-pent、loop-limit、notched-pentagon |
| 斜邊矩形(手動輸入) | sl-rect、manual-input、sloped-rectangle |
| 三角形 | tri、extract、triangle |
| 倒三角形(手動檔案) | flip-tri、manual-file、flipped-triangle |
| 資料夾 | folder、directory |
| 帶線矩形 | lin-rect、lined-rectangle、lined-process、lin-proc、shaded-process |
| 分隔矩形 | div-rect、div-proc、divided-rectangle、divided-process |
| 窗格(內部儲存) | win-pane、internal-storage、window-pane |
| 堆疊矩形 | st-rect、procs、processes、stacked-rectangle |
| 標記矩形 | tag-rect、tagged-rectangle、tag-proc、tagged-process |
| 沒有外框的文字 | text |
| 資料儲存 | datastore、data-store |
| 半圓角矩形(延遲) | delay、half-rounded-rectangle |
| 弧形梯形(顯示) | curv-trap、curved-trapezoid、display |
| 橫放圓柱 | h-cyl、das、horizontal-cylinder |
| 帶線圓柱(磁碟) | lin-cyl、disk、lined-cylinder |
| 領結形矩形(儲存的資料) | bow-rect、stored-data、bow-tie-rectangle |
| 文件 | doc、document |
| 帶線文件 | lin-doc、lined-document |
| 標記文件 | tag-doc、tagged-document |
| 堆疊文件 | docs、documents、st-doc、stacked-document |
| 紙帶 | flag、paper-tape |
| 大括號,左、右或兩邊 | brace(comment、brace-l)、brace-r、braces |
| 水桶 | bucket |
| 人形 | person |
終端機(有 >_ 提示符的視窗) |
console |
| 瀏覽器(有工具列和網址列的視窗) | browser |
| 雲 | cloud |
| 爆炸形 | bang |
| 分叉橫條 | fork、join |
| 沙漏 | hourglass、collate |
| 閃電 | bolt、com-link、lightning-bolt |
| 小圓 | sm-circ、start、small-circle |
| 框線圓 | fr-circ、stop、framed-circle |
| 實心圓 | f-circ、junction、filled-circle |
| 打叉圓 | cross-circ、summary、crossed-circle |
最後七種是固定大小、沒有文字的形狀:替它們寫標籤(括號裡或 label:)會報錯。對小圓用 style 或樣式類別也會報錯,因為不會有任何改變。
標籤
- 標籤可以用中文。
- 標籤裡要放括號、
|、;、&或箭頭時,用雙引號包起來:A["a (b) | c"]。引號本身不會畫出來。標籤裡的%%是文字。 - 未加引號的標籤不能包含不屬於形狀本身的括號:
A[a]b]、A[a}b]、A{a]b},以及沒有配對的(或)(A[a)b])都會報錯,提示把標籤加上引號。成對的小括號會照樣畫出來(A[f(x)])。 - Markdown 字串:
A["`**粗體** 和 *斜體*`"]。反引號裡可以直接換行,換行會照樣畫出來。這個寫法只適用於節點標籤。 <br>寫在哪裡就在哪裡換行:A["第一行<br>第二行"]。換行之後還是太長的那一行,會再自己換行。- 太長的標籤會自己換行,和 Mermaid 一樣:文字寬度超過 175px 就會拆成好幾行,英文在空白處拆、中文在任兩個字之間拆,節點變高而不是變寬。
,、)這類收尾標點不會出現在行首;單一個太長的單字不會被拆開。subgraph 的標題不會換行。
flowchart LR
A["第一行<br>第二行"] --> B[這個標籤長到放不進一行,會自己換到第二行]
- 同一個節點宣告兩次、標籤不同時,保留第一次的標籤並發出警告。只寫 id 也算一次宣告:先寫
A --> B、之後才寫B[End]的話,標籤會是B。請在第一次提到節點時就寫上標籤。
連線
箭頭由三個部分組成:線、兩端的端點、長度。
| 線 | 寫法 |
|---|---|
| 實線 | -->、--- |
| 粗線 | ==>、=== |
| 虛線 | -.->、-.- |
| 端點 | 寫法 |
|---|---|
| 箭頭 | -->、雙向 <--> |
| 圓點 | --o、雙向 o--o |
| 叉叉 | --x、雙向 x--x |
| 無 | --- |
端點可以和三種線任意組合,例如 ==o、<-.->。雙向時兩端必須一樣,o--x 和 <-.- 會被拒絕(Mermaid 會默默畫錯,Siren 選擇明確報錯)。箭頭會停在節點的輪廓上:連到菱形、圓形或斜邊形狀時,碰到的是斜邊或弧線本身,而不是外面那個方框。
- 長度:多加幾個字元可以把線拉長,例如
---->、-...->、====>。 - 標籤:
A -->|文字| B或A -- 文字 --> B(粗線== 文字 ==>、虛線-. 文字 .->)。兩種寫法不能同時用在一條線上,標籤也不能是空的。連線標籤畫在線上,底下墊一塊主題--siren-edge-label-fill的底色;寬度超過 150px 會自己換行,規則和節點標籤相同,<br>在這裡也能換行。|文字|這種寫法裡,未加引號的括號(A -->|a{b| B)、第一個字含有@,或引號不在開頭,都會報錯:把整個標籤加上引號(A -->|"a{b"| B)。另一種寫法會照字面畫出來(A -- a{b --> B)。 - 隱形的邊:
A ~~~ B和一般的邊一樣會把 A 和 B 隔開,但不畫線。每多一個~,B 就再往後推一層。它也算進linkStyle的編號,linkStyle N stroke-width:4px會讓它現形;寫在上面的標籤會畫出來。 - 串接:
A --> B --> C會產生兩條邊。 - 多對多:
A & B --> C & D會產生 A-C、A-D、B-C、B-D 四條邊。&兩邊都要有空白:A&B是一個叫A&B的節點,A &B或A[x]&B會報錯。沒有箭頭的A & B會宣告兩個節點。 - 自己連自己:
A --> A。 - 分號:
A --> B; B --> C可以把多個敘述寫在同一行。
邊的 id 與邊的資料
flowchart LR
A e1@--> B e2@-->|重試| C
e1@{ animate: true }
e2@{ animation: slow, curve: step }
classDef hot stroke:#dc2626
class e2 hot
A e1@--> B把這條邊的 id 設成e1,timeline 和class用它取代A-B。兩種標籤寫法都能用,串接的每一段也都能有自己的 id。不能用在A & B --> C這種群組的邊上,不能和節點或其他邊的 id 重複(包含自動產生的A-B),不能以關鍵字開頭,也不能是 subgraph 的名字。- 寫在邊下面一行的
e1@{ … }是這條邊的資料。animate: true或animation: fast讓線的虛線以 20 秒一輪流動,animation: slow是 50 秒一輪;流動和 timeline 自己的效果同時進行,讀者設定減少動態效果時會停止。curve: step指定曲線,效果和linkStyle … interpolate相同,兩者都寫時以後寫的為準。其他 key 會略過並發出警告;fast、slow以外的 animation,或 Siren 還不會畫的曲線,會報錯。區塊寫在邊的上面會變成宣告一個叫e1的節點,因此報錯。 class e1 名稱把樣式類別套到這條邊:宣告套在線上,color套在標籤上,但指到這條邊的linkStyle優先。style e1 …和click e1 …會報錯;邊的樣式請用linkStyle。
Subgraph
flowchart TB
subgraph ingest [Ingest]
direction LR
Fetch --> Parse
end
subgraph store [Store]
Save
end
ingest --> store
- 開頭有幾種寫法:
subgraph ingest(id 和標題都是 ingest)、subgraph ingest [Ingest pipeline](有 id 也有標題)、subgraph "Ingest pipeline"(只有標題,其他地方無法用 id 指到它),以及不加引號的多個字subgraph Ingest pipeline,同樣只有標題。只有一個字的引號標題(subgraph "t")同時也是 id,subgraph "t" [Ingest]則是 idt加上標題。 - 不加引號的標題不能含有
,、(、[、{、|、<、=、~、@、--或:::,請改用引號。括號標題後面再接文字(subgraph s1 [t] zz)、最後一個字是end的標題,都會報錯;在 subgraph 的 id 上寫@{ … }區塊也會報錯。 - 用
end結束,可以巢狀。 - 裡面可以用
direction另外指定方向,只影響這一層;方向後面多出來的文字(direction LR zz)會略過並發出警告。但只要有一條連線兩端的父層不同、又穿過這個 subgraph,它就會放棄自己的方向:一端在裡面(不管多深)、一端在外面就算,兩端都是它自己的成員但巢狀深度不同也算。這樣的連線會讓從兩端往上、直到兩端最近的共同 subgraph(含)的每一層都放棄方向,改用外層 subgraph 的方向(找最近一層還保有自己方向的),都沒有就用整張圖的,和 Mermaid 12 相同。沒寫direction的 subgraph 也一樣,跟著外層 subgraph 的方向排。並排的兩個 subgraph 或節點之間的連線(ingest --> store)兩邊都不受影響;成員連到自己所屬 subgraph 的連線則算。 - 有一種圖排不出來,會報錯並點名相關的元素:在一個保有自己
direction的 subgraph 裡,巢狀的 subgraph 和它自己的成員之間有連線(B --> F,F在B裡面,兩者都在設了direction LR的A裡面)。請拿掉外層的方向,或讓巢狀的那個連到它外面的東西。 - 同一層的 subgraph 後結束(
end)的排前面,而且所有 subgraph 都排在外面的節點前面,和 Mermaid 相同:先寫subgraph SA … end、再寫subgraph SB … end、最後X,從左到右會是 SB、SA、X。 - 可以直接用 subgraph 的 id 連線(
ingest --> store),subgraph 寫在連線下面也可以。 - 一個節點只屬於第一個提到它的 subgraph。
樣式
flowchart LR
A:::hot --> B --> C
style B fill:#e0f2fe,stroke:#0284c7
classDef hot fill:#fee2e2,stroke:#dc2626,color:#991b1b
class C hot
linkStyle 0 stroke:#dc2626
linkStyle 1 interpolate step
linkStyle default stroke:#94a3b8
style 節點 屬性:值,屬性:值:套用在一個節點,或用 id 套用在一個 subgraph 上(style ingest fill:#f0f9ff,color:#1e3a8a會填滿外框並改標題的顏色)。同一個名字既是節點又是 subgraph 時,套用在 subgraph 上。這裡不接受邊的 id,請用linkStyle。classDef 名稱 屬性:值,...:定義樣式類別。名稱可以用英數字和_、任何文字的字母,以及夾在字中間的-、.、#、+;不能以數字開頭。classDef a,b ...會同時定義兩個類別。可以寫在套用它的敘述之前或之後。class A,B 名稱或A:::名稱:把樣式類別套用在節點或 subgraph 上;class e1 名稱則套用在有 id 的邊上。:::也可以接在有標籤的節點或連線端點上(A[x]:::hot --> B:::cold)。一次只能套一個類別:A:::c,d會報錯。套用沒有用classDef定義的類別會發出警告,目標照原樣畫、不上樣式。classDef default 屬性:值,...:套用到每一個節點,其他類別或style都會蓋過它。不會套用到 subgraph。linkStyle 0 ...、linkStyle 0,2 ...、linkStyle default ...:幫邊上樣式。編號依邊的宣告順序從 0 開始算,隱形的~~~邊也算;default會套到所有邊,但指定編號的逐屬性優先。linkStyle 1 interpolate step、linkStyle default interpolate linear,或是和樣式寫在同一行的linkStyle 1 interpolate step stroke:#f00:指定這條邊用哪種曲線畫,和 Mermaid 一樣。預設是rounded:橫直線段組成的路線加上圓角,和 Mermaid 12 畫的一樣,兩條邊交叉時其中一條會用小弧跳過另一條。其他可選basis(平滑曲線,不畫跨線小弧)、linear、step、stepBefore、stepAfter。名稱分大小寫,指定編號的曲線優先於default。Mermaid 有但 Siren 還沒實作的七種(cardinal、bumpX、bumpY、catmullRom、monotoneX、monotoneY、natural)會報錯,這條邊維持原本的曲線;Mermaid 也不認得的名稱會畫成rounded並發出警告。color會套在文字上,其他屬性套在形狀上(邊的stroke會同時影響線和箭頭)。- 同一個目標上,
style永遠蓋過樣式類別,不管誰先寫,和 Mermaid 相同。兩條style、或兩個類別套在同一個目標上時,同一個屬性以後寫的為準。 - timeline 強調某個目標的期間,強調效果的顏色和線寬會取代作者設定的
stroke和stroke-width,強調結束後恢復。 - 指到不存在的節點會直接略過、不報錯,和 Mermaid 相同。
- 值的寫法和 Mermaid 一樣:顏色寫十六進位色碼或顏色名稱(
fill:#ff0000、fill:red),字型用單引號(font-family:'Noto Sans')。rgb(…)、var(--x)這類 CSS 函式、括號、|、@、{、}、=、~、箭頭或連續兩個-、雙引號、;或反斜線都會報錯;值是rgb(r,g,b)時,錯誤訊息會告訴你該寫的色碼。值裡有空白沒有問題(stroke-dasharray:5 5)。
互動
flowchart LR
Docs --> API
click Docs href "https://example.com/docs" "說明文件" _blank
click API call openPanel("api")
| 寫法 | 效果 |
|---|---|
click A href "網址" 或 click A "網址" |
連結 |
click A href "網址" "提示" _blank 或 click A "網址" "提示" _blank |
滑鼠移上去顯示提示,並在新分頁開啟;也可以用 _self、_top、_parent |
click A call fn()、click A call fn("參數") |
呼叫 callback |
click A fn |
callback 的簡寫 |
- 網址只允許
http:、https:、mailto:和相對路徑。其他協定(如javascript:)會被拒絕,那一條互動會被丟掉。 - callback 會觸發嵌入端提供的
onClick。在 Playground 裡點擊不會有反應。 - 提示文字在滑鼠移到節點上時顯示。
click只能指到節點:寫邊的 id 會報錯。
無障礙
accTitle: 標題 和 accDescr: 描述 會成為 SVG 的 <title> 和 <desc>,描述也可以用 accDescr { ... } 跨好幾行。冒號前面有空白也可以。重複寫的話以最後一個為準。
Timeline 目標
| 元素 | id | 例子 |
|---|---|---|
| 節點 | 節點 id | B |
| 邊 | 起點-終點,重複的加 #2、#3 |
A-B、A-B#2 |
| 有 id 的邊 | 寫在箭頭前面的那個 id | e1 |
| subgraph | subgraph:N,依開啟順序編號,巢狀的也一起算 |
subgraph:1 |
A --> B --> C的兩條邊是A-B和B-C。A & B --> C的兩條邊是A-C和B-C。- 重複的次數是把同一對節點之間的每一條邊都算進去,有沒有 id 都算:先寫
A e1@--> B、再寫A --> B,兩條邊是e1和A-B#2。 - 連到 subgraph 的邊用原始碼裡寫的名字:
ingest --> store的 id 是ingest-store。但 subgraph 本身只能用subgraph:N指定,名字不行。 - 節點和邊共用一個 id 時(節點
A-B旁邊有A --> B),在 timeline 裡指到它會報錯;請給那條邊自己的 id,或把節點改名。
尚未支援
| 語法 | 目前的行為 |
|---|---|
非 ASCII 的節點 id(節點 --> B) |
報錯。中文請放在標籤裡:n1[節點] |
在 Playground 裡用 A@{ icon: "fa:user" } |
報錯:Playground 沒有註冊圖示包 |
A@{ img: "https://…" } |
報錯,只畫 data: URL |
A ~~ B、A ~~~> B |
報錯,隱形的邊是沒有端點的 ~~~ |
標籤裡的 #quot;、fa: 圖示 |
當成一般文字畫出來 |
| 邊標籤、subgraph 標題裡的 Markdown | 當成一般文字畫出來 |