快速開始
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。
文件結構
- 第一個非空白行是圖表標頭,決定這份文件是哪一種圖(見下表)。標頭前面可以有一段 Mermaid 的 frontmatter(
---…---),見與 Mermaid 共通的差異。 - 接著是圖表本體,語法和 Mermaid 相同。
- 最後是可選的 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,則照文件寫的畫。見主題。