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 端點退場但連線還在(警告)