Markdown 甘特圖

1. 前言

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

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

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

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

2. 語(yǔ)法詳解

2.1 甘特圖語(yǔ)法

2.1.1 一個(gè)基本的甘特圖

基本的甘特圖由「標(biāo)題」、「日期格式約定」、「分組及任務(wù)」三部分組成。

實(shí)例 1：

一個(gè)基本的甘特圖。

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

渲染效果如下：

2.1.2 規(guī)定日期格式

通過(guò)設(shè)置 dateFormat 屬性，可以指定甘特圖定義日期時(shí)的解析方式。

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

2.1.3 任務(wù)的定義

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

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

實(shí)例 2：

在甘特圖中定義任務(wù)。

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

渲染效果如下：

2.1.4 定義對(duì)象的生命周期

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

完整的定義語(yǔ)法如下：

%a - 周維度名稱（簡(jiǎn)寫形式）。
%A - 周維度名稱（完整形式）。
%b - 月維度名稱（簡(jiǎn)寫形式）。
%B - 月維度名稱（完整形式）.
%c - 日期時(shí)間，相當(dāng)于"%a %b %e %H:%M:%S %Y"。
%d - 月中日期固定寬度寫法，取值范圍 [01,31].
%e - 月中日期變動(dòng)寬度寫法，取值范圍 [ 1,31]；等同于 %_d.
%H - 小時(shí)數(shù)（24小時(shí)制）取值范圍 [00,23]。
%I - 小時(shí)數(shù)（12小時(shí)制）取值范圍 [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 - 時(shí)間，等同于 "%H:%M:%S"。
%y - 年，僅后兩位，取值范圍 [00,99]。
%Y - 年，完整四位。
%Z - 時(shí)區(qū)，例如："-0700"。
%% - 用于輸出百分號(hào) "%" 。

3. 使用場(chǎng)景及實(shí)例

甘特圖通常用于項(xiàng)目管理。

實(shí)例 3：

一個(gè)完整的甘特圖。

gantt
       dateFormat           :YYYY-MM-DD
       title                :甘特圖實(shí)例

       section 基本任務(wù)
       已完成任務(wù)            :done,    des1, 2014-01-06,2014-01-08
       進(jìn)行中任務(wù)            :active,  des2, 2014-01-09, 3d
       未開(kāi)始任務(wù)1           :         des3, after des2, 5d
       未開(kāi)始任務(wù)2           :         des4, after des3, 5d

       section 緊急任務(wù)
       已完成的緊急任務(wù) :crit, done, 2014-01-06,24h
       已完成緊急任務(wù)1       :crit, done, after des1, 2d
       進(jìn)行中緊急任務(wù)2       :crit, active, 3d
       未開(kāi)始緊急任務(wù)3       :crit, 5d
       未開(kāi)始一般任務(wù)4       :2d
       未開(kāi)始一般任務(wù)5       :1d

       section 文檔編寫
       進(jìn)行中文檔任務(wù)1       :active, a1, after des1, 3d
       未開(kāi)始文檔任務(wù)2       :after a1  , 20h
       未開(kāi)始文檔任務(wù)3       :doc1, after a1  , 48h

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

其渲染效果如下：

4. 小結(jié)

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