甘特圖

gantt
  title 網站改版
  dateFormat YYYY-MM-DD
  todayMarker off
  section 探索
  專案簡報 :done, brief, 2024-03-04, 4d
  利害關係人訪談 :done, 2024-03-06, 5d
  section 設計
  線框稿 :active, wire, after brief, 6d
  視覺設計 :2024-03-18, 5d
  section 開發
  前端 :crit, build, after wire, 8d
  QA :qa, after build, 3d
  上線 :milestone, launch, after qa, 0d

timeline:
  enter section:1 fade, enter brief fade, enter task1 fade
  enter section:2 fade, enter wire slide-right, enter task2 slide-right
  enter section:3 fade, enter build slide-right, enter qa fade
  enter launch fade, highlight launch glow

標頭

gantt。敘述關鍵字(section、dateFormat、title 等)不分大小寫;標記(done、crit 等)和時間長度的單位則要照寫。

任務

任務寫成 名稱 :資料。資料以逗號分隔:先寫任意幾個標記,再寫一到三個欄位。

  • 標記一律小寫:done、active、crit、milestone 和 vert(見 Vert 標記)。crit 可以和 done 或 active 一起用。
  • 只寫 結束:從前一個任務結束的地方開始。第一個任務不能用這種寫法。
  • 開始, 結束。
  • id, 開始, 結束。寫第四個欄位會報錯。

開始是符合 dateFormat 的日期,或 after a b:所列任務中最晚的結束時間。結束是符合 dateFormat 的日期、一段時間長度,或 until a b:所列任務中最早的開始時間。指到不存在的 id 會發出警告;一個都對不上時,任務從今天零點開始或結束。

  • 時間長度是數字加單位:ms、s、m、h、d、w、M(月)或 y,例如 3d、2w、1.5h。一天以上的小數會取整成整天。
  • 一定要寫 dateFormat(YYYY-MM-DD、DD/MM/YYYY、YYYY-MM-DD HH:mm、代表 epoch 毫秒的 x 等)。沒寫的話,用日期寫的結束時間讀不出來,任務會畫成沒有長度。
  • inclusiveEndDates 讓結束日期包含當天。
  • 列的順序就是任務寫的順序,跟日期無關;精簡模式例外。
  • 任務名稱放得進長條時畫在長條裡,放不下就畫在旁邊,和 Mermaid 一樣。
  • 日期用當地時間,和 Mermaid 一樣。

Section

section 名稱 開始一個 section,一直到下一個 section 為止。同名的兩個 section 視為同一個。各列以兩種底色交替。

排除的日子

gantt
  dateFormat YYYY-MM-DD
  excludes weekends, 2024-05-27
  todayMarker off
  section 開發
  API :api, 2024-05-20, 8d
  前端 :after api, 3d
  • excludes 接 weekends、星期名稱(friday)和日期,以逗號或空白分隔,可以寫好幾行。任務跨過排除的日子時,結束時間會往後延,除非結束時間寫成 YYYY-MM-DD 日期。排除的日子會畫上底色。
  • includes 指定照常上班的日子。
  • weekend friday 把週末改成週五和週六;預設是 saturday。

時間軸

  • axisFormat 使用 d3 的時間格式代碼:預設 %Y-%m-%d,也可以寫 %b %d、%H:%M 等。
  • tickInterval 是整數加上 millisecond、second、minute、hour、day、week 或 month(1week、2day)。用 week 時,刻度落在 weekday 指定的那天,預設是 sunday。
  • 會畫出超過 10,000 個刻度的間隔會被忽略並發出警告,請配合圖的時間跨度設定。

今日線

圖上會在今天的位置畫一條線。todayMarker off 拿掉這條線;todayMarker 後面寫其他文字,就是這條線的樣式,宣告之間用 , 分隔(todayMarker stroke-width:3px,stroke:#d6336c)。在這個網站上,不論選的是風格還是自訂主題,這段樣式都會被接管,今日線照 --siren-gantt-today-stroke 畫,見主題。

「今天」指的是頁面畫圖的那一刻,所以有今日線的圖換一天看會不一樣。本站的範例都關掉了今日線,讓畫面固定不變。

Vert 標記

gantt
  dateFormat YYYY-MM-DD
  todayMarker off
  section 開發
  API :api, 2024-05-13, 8d
  程式凍結 :vert, freeze, 2024-05-20, 0d
  前端 :after api, 5d

vert 任務是在開始時間畫一條貫穿整張圖的細線,名稱寫在時間軸下方。它不占列、也不屬於任何 section,但後面只寫一個欄位的任務仍然接在它後面,它也算進 task1、task2… 的編號,它的日期也會撐開時間軸。通常寫成 0d。

精簡模式

---
displayMode: compact
---
gantt
  dateFormat YYYY-MM-DD
  todayMarker off
  section 團隊
  規格 :2024-05-06, 3d
  審查 :2024-05-09, 2d
  文件 :2024-05-07, 4d

精簡模式(compact)把同一個 section 裡的任務擠到共用的列上:依開始時間排序,每個任務放進第一個「最後一個任務已經結束」的列。開啟方式是在 front matter 最上層寫 displayMode: compact,或用 config.gantt.displayMode,或 %%{init: {"gantt": {"displayMode": "compact"}}}%%。只有一字不差的 compact 會擠列,其他值都照一般方式畫。

Vert 標記仍然畫到沒擠列時的高度,所以在精簡模式下,它的線和名稱會超出圖的底部,和 Mermaid 一樣。

寬度

甘特圖不管畫在哪裡都是 1200px 寬。front matter 寫 config: { gantt: { useWidth: 900 } } 可以換成別的寬度。除了 displayMode 之外,其他 config.gantt 設定都會發出警告、不會套用。

互動

click id href "url" 讓任務變成連結,click id call fn(args) 把 fn 交給頁面處理。一個 click 可以列好幾個 id,用逗號分隔、中間不留空白(click a,b href "…"),也可以同時有 call 和 href。

顏色

列的底色、格線、各狀態的長條、今日線、排除的日子和 vert 標記,各有一個 --siren-gantt-* 設計 token;一般任務的長條畫得和節點一樣。任務名稱、section 標題和刻度文字用 --siren-node-text。見主題。

無障礙

title 文字 在圖的上方畫標題。accTitle: 文字、accDescr: 文字 和大括號的 accDescr { … } 區塊是圖的無障礙標題與描述。

Timeline 目標

元素 id 例子
任務 資料裡寫的 id brief(專案簡報 :done, brief, 2024-03-04, 4d)
沒寫 id 的任務 taskN,只算沒寫 id 的任務,vert 標記也算 task1
Vert 標記 它的 id,和任務一樣 freeze
Section section:N,依 section 名稱第一次出現的順序 section:1
  • 任務的長條和名稱一起動,vert 標記的線和名稱也是。
  • Section 的 id 只會讓它的列底色和標題出現,不包括裡面的任務;任務要另外 enter。
  • after、until 後面也可以寫 taskN(after task1)。

尚未支援

語法 目前的行為
topAxis 報錯,Mermaid 12.2.0 本身也畫不出來
任務名稱以日期開頭(2024-05-01 開工 :…) 報錯;只有年份(2024 計畫 :…)沒問題
任務名稱以敘述關鍵字開頭(Title page :…) 會被當成那個敘述,和 Mermaid 一樣
第二個字元是 % 的行(5% done :…) 當成註解,並發出警告
Mermaid 可點擊任務的粗體、變色名稱 沒有照做;任務只會換成手指游標