快速開始

Siren 文件(.srn)就是一張 Mermaid 圖表,後面可以再接一個 timeline: 區塊描述動畫。沒有 timeline: 的文件就是一張靜態圖;有的話,每按一次 Next 就往前走一步。同一張圖也可以帶好幾個具名區塊 timeline <name>:,各說各的故事,見一份文件裡的多條 timeline。

flowchart TB
  A[Start] --> B[Fetch data]
  B --> C[Publish]

timeline:
  enter B fade, enter A-B fade
  enter C fade, enter B-C fade
  highlight C glow

timeline: 沒提到的元素從一開始就看得到;有 enter 的元素會先藏起來,等到它那一步才出現。完整寫法見 Timeline 區塊。

到 Playground 直接試試看。

在網頁裡使用

Siren 在 npm 上有兩個套件,原始碼都在 GitHub:

套件 用途
siren-board 現成的播放器:一行放進頁面,附步驟按鈕與步數、可選間隔的自動播放、完整圖、具名 timeline 切換、拖曳與縮放(附 Reset view 按鈕)、全螢幕(全螢幕時點一下圖就前進一步),以及圖後方的點狀網格。
siren-core 渲染器本身:把文件畫成 SVG,回傳控制步驟的 controller,介面自己做。

想直接把圖放上頁面,用 siren-board:

npm install siren-board siren-core
import { createBoard } from "siren-board";
import "siren-core/theme.css";

createBoard(document.getElementById("board"), { source });

播放器會填滿容器,所以容器一定要有高度,不然什麼都看不到。主題 CSS 來自 siren-core,圖的外觀都在裡面,所以兩個套件都要裝。

要自己做控制介面,就直接用 siren-core:

import { render } from "siren-core";
import "siren-core/theme.css";

const container = document.getElementById("diagram");
const { svg, controller, diagnostics } = render(source, container);

if (svg === null) {
  for (const d of diagnostics) console.error(`${d.line}:${d.column} ${d.message}`);
} else {
  document.getElementById("next").onclick = () => controller.next();
  document.getElementById("prev").onclick = () => controller.prev();
}

render() 播放文件的第一條 timeline。要播別條具名的,把 { timeline: "name" } 當第三個參數傳進去;回傳值的 timelines 列出文件宣告的所有名字。

兩個套件都需要 DOM,在瀏覽器裡執行。不用打包工具、從 CDN 載入,以及完整的 API,見 siren-board 和 siren-core 的 README。

文件結構

  1. 第一個非空白行是圖表標頭,決定這份文件是哪一種圖(見下表)。標頭前面可以有一段 Mermaid 的 frontmatter(--- … ---),見與 Mermaid 共通的差異。
  2. 接著是圖表本體,語法和 Mermaid 相同。
  3. 最後是可選的 timeline 區塊:一個不具名的 timeline:,或多個具名的 timeline <name>:(小寫、冒號後面不能接東西)。從第一個標頭開始到檔案結尾都算 timeline,所以它們一定要放在最後。

在圖表本體裡,只有整行才是註解:第一個非空白字元是 %% 的那一行,和 Mermaid 相同。寫在一行中間的 %% 不是註解:在標籤或其他文字裡會當成文字保留(A[50 %% done] 畫出「50 %% done」);接在完整敘述後面(A --> B %% note)在多數圖表會報錯,訊息會請你把註解搬到單獨一行。有兩種圖改照 Mermaid 的讀法:狀態圖在狀態、轉移、大括號、[*] 或 direction 後面遇到 %%,會把它和同一行後面的內容當註解丟掉(A --> B %% note 畫出這條轉移),標籤、描述與 note 裡的 %% 仍保留為文字;類別圖只有在文件最後一行的關係後面才這樣處理,其他行都會報錯。註解行的 %% 後面要有文字:只有 %% 的一行在流程圖和 ER 圖會被拒絕,請寫 %% 文字 或留空行。timeline 區塊裡的 %% 則照舊,寫在一行的任何地方都是註解。

支援的圖表

圖表 標頭 文件
流程圖 flowchart TB、graph LR 等 流程圖
類別圖 classDiagram、classDiagram-v2 類別圖
序列圖 sequenceDiagram 序列圖
狀態圖 stateDiagram、stateDiagram-v2 狀態圖
ER 圖 erDiagram ER 圖
甘特圖 gantt 甘特圖

其他 Mermaid 圖表(圓餅圖、git graph、mindmap 等)還不支援,寫了會在第一行就報錯。

錯誤訊息怎麼看

Siren 的原則是:Mermaid 畫得出來的,Siren 也要畫得出來;還沒支援的語法會明確報錯,而不是默默畫錯。 訊息分兩種嚴重程度:

  • 整份拒絕:語法看不懂,例如 Unrecognized flowchart line: "...",或 timeline 的格式寫錯。這時整張圖都不會畫出來,只顯示錯誤。
  • 只丟掉一條:語法對但內容有問題,例如 timeline 指到不存在的 id、click 用了不允許的網址、套用了沒定義的 class。圖照樣畫,只有那一條被略過,並附上錯誤或警告。

每則訊息都帶行號,Playground 會把它標在編輯器對應的那一行。

與 Mermaid 共通的差異

以下幾點對所有圖表都一樣:

  • frontmatter 會讀進來,但還不會套用。 開頭的 --- … --- 會照 Mermaid 的方式讀:只認文件最開頭、以縮排相同的第一個 --- 結束、裡面是 YAML。它的 config(theme、themeVariables 等)和 title 會保留下來,但目前都不影響畫出來的圖;每個設定都會在開頭的 --- 那一行發出警告,圖照樣畫。只有 look: classic 不會警告,因為 Siren 本來就這樣畫;頂層的 siren: key 也不會:Mermaid 會忽略它,Siren 不檢查它,render() 會把它的值以 siren 原樣交回給頁面使用。本站 Playground 把圖的顏色設定存在這裡,見主題。不是合法 YAML 的 frontmatter 會報錯。外觀請改用 --siren-* 設計 token,見主題。
  • %%{init: ...}%% 指令也是同樣的讀法。 單行或跨行、init 或 initialize 都一樣,依序合併在 frontmatter 的 config 之上,%%{wrap}%% 也是:讀進來、保留、不套用,每個設定一則警告。不是合法 JSON 的 init 會被報告,然後和 Mermaid 一樣,整份文件的 init 都不讀。其他 %%{...}%% 指令會被移除並警告。
  • 錯誤訊息不會提到 Mermaid。 每一則都說明哪裡錯、要改寫成什麼。
  • 標頭後面不能接分號:graph TD; 會被拒絕,請寫 graph TD。
  • 在本站,風格會接管文件裡的顏色。 在 Playground 和範例頁,style、classDef/class/:::name、linkStyle 設定的填色、邊框、文字顏色等,會改用所選風格(例如 Siren)的顏色重新上色;選了自訂主題也一樣,改用那份主題自己的顏色。只有 label 自己標記裡的顏色照原樣畫。在自己的網頁用 siren-core,則照文件寫的畫。見主題。