Markdown 甘特圖

1. 前言

Markdown 的原生語法不支持繪制圖形，但通過擴展模塊，我們可以將一些格式化的文字渲染成我們需要的圖形。常用的圖形有 “流程圖”、“時序圖”、“類圖”、“狀態(tài)圖”、“甘特圖”、"餅圖" 等。

本節(jié)將重點介紹如何通過 Mermaid 繪制「甘特圖」。

甘特圖 (Gantt chart) 也被稱為橫道圖、條狀圖（Bar chart）。通常用于展示項目進度，它的核心對象是「時間」，并在時間的基礎上，展示了「成本」和「范圍」之間的聯(lián)系。

環(huán)境說明：
考慮到 Markdown 工具之間的不兼容，有的內(nèi)容直接從頁面復制粘貼到本地不會正常顯示，大家學習時自己動手寫是肯定沒問題的。本節(jié)所有實例代碼及演示效果均使用 Typora 工具完成。
Mermaid 為 Markdown 擴展語法，需要在 Typora 設置中開啟對圖表的語法支持。其方式為：「設置」->「Markdown」->「Markdown 擴展語法」-> 勾選「圖表」，如下圖：

2. 語法詳解

2.1 甘特圖語法

2.1.1 一個基本的甘特圖

基本的甘特圖由「標題」、「日期格式約定」、「分組及任務」三部分組成。

實例 1：

一個基本的甘特圖。

?```mermaid
gantt
    title 簡單的甘特圖
    dateFormat  YYYY-MM-DD
    section 分區(qū)1
    任務1-1           :a1, 2014-01-01, 30d
    任務1-2           :after a1  , 20d
    section 分區(qū)2
    任務2-1      :2014-01-12  , 12d
    任務2-2      : 24d
?```

渲染效果如下：

2.1.2 規(guī)定日期格式

通過設置 dateFormat 屬性，可以指定甘特圖定義日期時的解析方式。

日期的格式支持以下情形：

2.1.3 任務的定義

Mermaid 甘特圖中，每個任務隸屬于一個分組，一個分組內(nèi)可以定義多個任務，一張甘特圖表中可以包含多個分組。

甘特圖中的任務定義格式形如：<任務名> : [crit], [active], [任務ID], [前置任務], <周期>，其中「任務名」和「周期」兩項是必要項。

實例 2：

在甘特圖中定義任務。

 gantt
        蘋果 :a, 2017-07-20, 1w
        香蕉 :crit, b, 2017-07-23, 1d
        櫻桃 :active, c, after b a, 1d

渲染效果如下：

2.1.4 定義對象的生命周期

甘特圖上的對象都是以時間為基礎而存在的，對于時間，我們可能有非常多的定義需求，比如精度上的「年」、「月」、「日」、「時」等，又比如「24H」或者 「12H」這樣寫法上的不同等。Mermaid 為時間提供了豐富的語法支持。

完整的定義語法如下：

%a - 周維度名稱（簡寫形式）。
%A - 周維度名稱（完整形式）。
%b - 月維度名稱（簡寫形式）。
%B - 月維度名稱（完整形式）.
%c - 日期時間，相當于"%a %b %e %H:%M:%S %Y"。
%d - 月中日期固定寬度寫法，取值范圍 [01,31].
%e - 月中日期變動寬度寫法，取值范圍 [ 1,31]；等同于 %_d.
%H - 小時數(shù)（24小時制）取值范圍 [00,23]。
%I - 小時數(shù)（12小時制）取值范圍 [01,12]。
%j - 年中日期固定寬度寫法，取值范圍 [001,366]。
%m - 年中月份固定寬度寫法，取值范圍 [01,12]。
%M - 分鐘數(shù)固定寬度寫法，取值范圍 [00,59]。
%L - 毫秒數(shù)固定寬度寫法，取值范圍 [000, 999]。
%p - 上午 \ 下午。
%S - 秒數(shù)固定寬度寫法，取值范圍 [00,61]。
%U - 年中周數(shù)的固定寬度寫法，以周日為每周第一天，取值范圍 [00,53]。
%w - 周中日期寫法，取值范圍 [0（周日）,6]。
%W - 年中周數(shù)的固定寬度寫法，以周一為每周第一天，取值范圍 [00,53]。
%x - 日期，等同于 "%m/%d/%Y"。
%X - 時間，等同于 "%H:%M:%S"。
%y - 年，僅后兩位，取值范圍 [00,99]。
%Y - 年，完整四位。
%Z - 時區(qū)，例如："-0700"。
%% - 用于輸出百分號 "%" 。

3. 使用場景及實例

甘特圖通常用于項目管理。

實例 3：

一個完整的甘特圖。

gantt
       dateFormat           :YYYY-MM-DD
       title                :甘特圖實例

       section 基本任務
       已完成任務            :done,    des1, 2014-01-06,2014-01-08
       進行中任務            :active,  des2, 2014-01-09, 3d
       未開始任務1           :         des3, after des2, 5d
       未開始任務2           :         des4, after des3, 5d

       section 緊急任務
       已完成的緊急任務 :crit, done, 2014-01-06,24h
       已完成緊急任務1       :crit, done, after des1, 2d
       進行中緊急任務2       :crit, active, 3d
       未開始緊急任務3       :crit, 5d
       未開始一般任務4       :2d
       未開始一般任務5       :1d

       section 文檔編寫
       進行中文檔任務1       :active, a1, after des1, 3d
       未開始文檔任務2       :after a1  , 20h
       未開始文檔任務3       :doc1, after a1  , 48h

       section 其他部分
       其他任務1            :after doc1, 3d
       其他任務2            :20h
       其他任務3            :48h

其渲染效果如下：

4. 小結

• Mermaid 為 Markdown 擴展了使用普通文本生成甘特圖的語法及渲染支持；
• Mermaid 可以用文本形式描述甘特圖中的「標題」、「日期格式約定」、「分組及任務」；
• Mermaid 甘特圖支持自定義節(jié)點樣式，使其具備更豐富的表現(xiàn)力。