Timeline 區塊
timeline: 區塊是 Siren 在 Mermaid 之外唯一新增的語法。它寫在圖表本體之後,描述按下每一次 Next 時畫面要怎麼變。一份文件也可以有好幾個具名區塊 timeline <name>:,讓同一張圖說好幾個故事,見一份文件裡的多條 timeline。
flowchart LR
A[Plan] --> B[Build]
B --> C[Review]
C --> D[Ship]
timeline:
enter B fade, enter A-B fade
enter C fade, enter B-C fade
enter D fade, enter C-D fade
highlight B outline
highlight D glow, unhighlight B
exit B slide-left, exit A-B slide-left, exit B-C slide-left, unhighlight D
exit C-D slide-top
寫法
timeline:
<動作>, <動作>, ...
<動作>, ...
- 標頭:
timeline:,或具名區塊的timeline <name>:。全小寫,名字前面一個空白,名字和冒號之間不能有東西,冒號後面也不能接其他文字。前面可以縮排。其他以timeline開頭的行都不是標頭,照原本的意思讀。 - 位置:放在圖表本體之後。從第一個 timeline 標頭開始到檔案結尾都算 timeline,所以圖表語法不能寫在它後面。一份文件只能二選一:一個不具名的
timeline:,或是多個具名區塊;不具名的也不能出現兩次。 - 一行就是一步:第一行是第 1 步,第二行是第 2 步,依此類推。不用、也不能寫步數。
- 一步可以有多個動作,用逗號分隔,依書寫順序套用。最後不能多一個逗號。
- 每個動作是
動作 目標 [效果],用空白隔開。一個動作只能指一個目標,沒有all或萬用字元。 - 縮排不影響;timeline 區塊裡的
%%註解可以放在任何地方,和圖表本體不同(那裡只有整行才是註解)。唯一的例外是流程圖裡本身就以%%開頭的目標(A --> %%B畫出一個叫%%B的節點):緊貼在目標開頭的%%是 id 的一部分,所以enter %%B fade指得到它。要寫註解請用%% 說明,中間空一格。 - 動作和效果都分大小寫。
步數怎麼算
- 步數就是這一行在區塊裡的順序,從 1 開始,總步數就是非空白行的行數。
- 空行不算步數,可以用來把很長的 timeline 分段。只有
%%註解的行也算空行。 - 寫錯的行仍然占一個步數。這一行會報錯、整份文件不會畫出來,但後面的行保持原本的步數,修好之後也不會改號。錯誤訊息裡的
at step N就是從上往下數第 N 個非空白行。 - 要插入一步,直接在中間加一行就好,後面的行會自動往後推。
- 按 Prev 會直接回到上一步的狀態,不播放反向動畫;Reset 回到第 0 步(尚未開始)。
flowchart LR
A --> B --> C
timeline:
%% 先讓 B 進場
enter B fade, enter A-B fade
%% 再讓 C 進場並強調
enter C fade, enter B-C fade
highlight C glow
上面這個 timeline 有三步:兩行註解和中間的空行都不算。
舊版 Siren 的寫法是
step 1: enter B fade,這個前綴已經拿掉了。現在寫step 1:會報Unrecognized timeline action,把step N:刪掉就好。
動作與效果
| 動作 | 效果(必填) | 說明 |
|---|---|---|
enter |
fade、slide-left、slide-right、slide-top、slide-bottom |
元素在這一步出現。在這之前它是隱形的,但仍然佔著位置。 |
exit |
fade、slide-left、slide-right、slide-top、slide-bottom |
元素在這一步消失,位置保留,其他元素不會重新排列。 |
highlight |
outline、glow |
強調元素。再次 highlight 同一個元素會換掉原本的強調,不會疊加。 |
unhighlight |
不接效果 | 取消強調。原本沒有強調也不會報錯。 |
enter、exit、highlight 一定要寫效果,沒有預設值。unhighlight 則不能接效果。
效果長什麼樣子
| 效果 | 動畫 | 時間 |
|---|---|---|
fade |
淡入/淡出 | 600ms |
slide-left |
enter:從左邊 60px 滑進來;exit:往左滑出 |
500ms |
slide-right |
enter:從右邊滑進來;exit:往右滑出 |
500ms |
slide-top |
enter:從上方滑進來;exit:往上滑出 |
500ms |
slide-bottom |
enter:從下方滑進來;exit:往下滑出 |
500ms |
outline |
外框換成強調色並加粗 | 300ms |
glow |
元素周圍發光 | 300ms |
時間、距離和強調色都是設計 token,可以自己調:--siren-fade-duration、--siren-slide-duration、--siren-slide-distance、--siren-highlight-duration、--siren-highlight-color、--siren-highlight-stroke-width。見主題。
outline 和 glow 對所有圖表的所有元素都有效,而且一律贏過作者寫的 stroke:元素被強調時外框用強調色畫,就算文件給它上了樣式(style A stroke:#f00)也一樣,結束後作者的顏色會回來。流程圖邊的箭頭跟著線走,所以會一起被強調。隱形的流程圖邊(A ~~~ B)強調了還是隱形,要讓它看得見請用 linkStyle,不是 timeline。
目標 id
目標用 id 指定,規則依圖表而不同。共通的模式是:
- 作者自己取名的元素(節點、類別、參與者、狀態、實體、甘特圖任務)就用那個名字。沒寫 id 的甘特圖任務是
task1、task2…,和 Mermaid 一樣。 - 連線(邊、關係、訊息、轉移)用
起點-終點。同一對起訖點出現第二次起寫成A-B#2、A-B#3,依出現順序編號。方向有差:A-B和B-A是兩條不同的連線。 - Siren 自己產生 id 的元素(subgraph、namespace、note、區塊等)用
種類:編號,從 1 開始、依原始碼順序(巢狀的依開啟順序)編號。
| 圖表 | 可以當目標的元素 | 例子 |
|---|---|---|
| 流程圖 | 節點、邊、subgraph | B、A-B、A-B#2、e1(寫成 A e1@--> B 的邊)、subgraph:1 |
| 類別圖 | 類別、關係、namespace、note | Animal、Animal-Dog、namespace:1、note:1 |
| 序列圖 | 參與者、訊息、區塊、box、note、啟用條 | Web、Web-Orders、loop:1、alt:1、box:1、note:1、activation:1 |
| 狀態圖 | 狀態、轉移、起訖點、並行區域 | Idle、Idle-Working、start:1、start:1-Idle、region:1 |
| ER 圖 | 實體、關係、subgraph | CUSTOMER、CUSTOMER:ORDER、subgraph:1 |
| 甘特圖 | 任務、vert 標記、section | api、task1、section:1 |
ER 圖的關係 id 用冒號分隔(CUSTOMER:ORDER),因為實體名稱本身可以含 -。
以下元素不能當目標:流程圖 subgraph 的名稱(要用 subgraph:N)、類別的成員、狀態圖的 note(它跟著所屬的狀態一起動)、ER 圖的屬性。
一個目標只能指到一個畫出來的東西。流程圖裡叫 A-B 的節點和邊 A --> B 都帶著 id A-B,所以對 A-B 做動作會報錯;請給那條邊自己的 id(A e1@--> B),或把節點改名。序列圖被 destroy 的參與者,結尾那個方框也帶著參與者的 id,所以對參與者的動作也會作用到它。
規則
- 沒提到的元素從一開始就看得到。
- 每個目標最多一次
enter、一次exit。 重複的話保留最早那一步的,其餘發出警告並略過。所以元素退場後不能再進場。 - 元素出現之前不能對它做別的事。 例如某元素在第 3 步才
enter,在第 2 步對它highlight會報錯,那一條會被略過。和enter同一步則沒問題。 - 連線不會跟著端點自動退場。 端點
exit了、連線還留著的話,Siren 會發出警告,請在同一步或更早幫連線也加上exit。進場也一樣:節點和邊要分別enter。
一份文件裡的多條 timeline
同一張圖有不只一個故事要講時,給每個故事一個具名區塊,不用把圖表複製到第二個檔案。具名區塊以 timeline <name>: 開頭,一直到下一個 timeline 標頭或檔案結尾。
flowchart LR
Cart --> Card --> Done
Cart --> Wallet --> Done
timeline card:
enter Card fade, enter Cart-Card fade
enter Done fade, enter Card-Done fade
timeline wallet:
enter Wallet fade, enter Cart-Wallet fade
enter Done fade, enter Wallet-Done fade
- 名字只能用字母、數字、
_和-,分大小寫。同一個名字只能宣告一次。 - 不具名和具名二選一,不能混用。 有具名區塊的文件,不能再有不具名的
timeline:。 - 每個區塊都是一條獨立的 timeline。 步數從 1 數起,上面所有規則(包括第 0 步)都只看這個區塊:某個區塊沒提到的元素,從這個區塊一開始就看得到,就算別的區塊之後會讓它進場也一樣。所以每個區塊都要自己
enter它一開始想藏起來的東西。例子裡card沒提到Wallet,所以在 card 這個故事裡,wallet 那條路從頭到尾都看得到。 - 每次渲染都會檢查所有區塊,不管顯示的是哪一條。具名區塊的訊息會以
timeline <name>:開頭,而不是timeline:。 - 預設播放第一個區塊。 文件有兩條以上具名 timeline 時,Playground、範例頁和
siren-board會在控制列顯示一個下拉選單列出名字,選一個就從第 0 步播放那條 timeline。直接用siren-core的話,把名字傳給render(source, container, { timeline: "wallet" }),名字清單在回傳值的timelines。
multi-timeline 範例用同一張類別圖走過兩種結帳流程:信用卡和電子錢包。
錯誤訊息
格式錯誤會讓整份文件無法畫出:
| 訊息 | 原因 |
|---|---|
Unrecognized timeline action: "..." |
動作的字數不對、結尾多了逗號,或還在用舊的 step N: 寫法 |
Unrecognized timeline verb "..." |
動作不是 enter、exit、highlight、unhighlight |
Unknown enter effect "..." |
效果拼錯,或忘了寫效果 |
"unhighlight" takes no effect |
unhighlight 後面接了效果 |
A document declares at most one unnamed "timeline:" block; name each block ("timeline <name>:") to declare several |
出現第二個 timeline: |
An unnamed "timeline:" block cannot share a document with named ones; name every block, or declare only the unnamed one |
同一份文件裡同時有 timeline: 和 timeline <name>: |
Timeline "..." is already declared on line N |
兩個區塊用了同一個名字 |
Invalid timeline name "..." (a name is letters, digits, "_" and "-") |
名字裡有其他字元,例如 a.b |
把圖表語法寫在 timeline: 後面時,依那一行的寫法會報 Unrecognized timeline verb 或 Unrecognized timeline action。
內容錯誤只會略過那一條,圖照畫。在具名區塊裡,訊息會以 timeline <name>: 開頭,而不是 timeline::
| 訊息 | 原因 |
|---|---|
timeline: references unknown id "..." |
目標 id 不存在。常見原因是把 subgraph 的名稱當成 id,或 ER 關係寫成 A-B |
timeline: "..." already has a "enter" action |
同一個目標 enter 或 exit 了兩次(警告) |
timeline: "highlight" on "..." at step N comes before it becomes visible |
在元素出現之前就對它動作 |
timeline: edge "..." remains visible after its endpoint "..." exits |
端點退場但連線還在(警告) |