甘特圖
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 可點擊任務的粗體、變色名稱 | 沒有照做;任務只會換成手指游標 |