25 Markdown 甘特图

1. 前言

Markdown 的原生语法不支持绘制图形，但通过扩展模块，我们可以将一些格式化的文字渲染成我们需要的图形。常用的图形有 “流程图”、“时序图”、“类图”、“状态图”、“甘特图”、"饼图" 等。

本节将重点介绍如何通过 Mermaid 绘制「甘特图」。

甘特图 (Gantt chart) 也被称为横道图、条状图（Bar chart）。通常用于展示项目进度，它的核心对象是「时间」，并在时间的基础上，展示了「成本」和「范围」之间的联系。

环境说明：
考虑到 Markdown 工具之间的不兼容，有的内容直接从页面复制粘贴到本地不会正常显示，大家学习时自己动手写是肯定没问题的。本节所有实例代码及演示效果均使用 Typora 工具完成。
Mermaid 为 Markdown 扩展语法，需要在 Typora 设置中开启对图表的语法支持。其方式为：「设置」->「Markdown」->「Markdown 扩展语法」-> 勾选「图表」，如下图：

2. 语法详解

2.1 甘特图语法

2.1.1 一个基本的甘特图

基本的甘特图由「标题」、「日期格式约定」、「分组及任务」三部分组成。

实例 1：

一个基本的甘特图。

​```mermaid
gantt
    title 简单的甘特图
    dateFormat  YYYY-MM-DD
    section 分区1
    任务1-1           :a1, 2014-01-01, 30d
    任务1-2           :after a1  , 20d
    section 分区2
    任务2-1      :2014-01-12  , 12d
    任务2-2      : 24d
​```

渲染效果如下：

2.1.2 规定日期格式

通过设置 dateFormat 属性，可以指定甘特图定义日期时的解析方式。

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

2.1.3 任务的定义

Mermaid 甘特图中，每个任务隶属于一个分组，一个分组内可以定义多个任务，一张甘特图表中可以包含多个分组。

甘特图中的任务定义格式形如：<任务名> : [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 - 小时数（24小时制）取值范围 [00,23]。
%I - 小时数（12小时制）取值范围 [01,12]。
%j - 年中日期固定宽度写法，取值范围 [001,366]。
%m - 年中月份固定宽度写法，取值范围 [01,12]。
%M - 分钟数固定宽度写法，取值范围 [00,59]。
%L - 毫秒数固定宽度写法，取值范围 [000, 999]。
%p - 上午  下午。
%S - 秒数固定宽度写法，取值范围 [00,61]。
%U - 年中周数的固定宽度写法，以周日为每周第一天，取值范围 [00,53]。
%w - 周中日期写法，取值范围 [0（周日）,6]。
%W - 年中周数的固定宽度写法，以周一为每周第一天，取值范围 [00,53]。
%x - 日期，等同于 "%m/%d/%Y"。
%X - 时间，等同于 "%H:%M:%S"。
%y - 年，仅后两位，取值范围 [00,99]。
%Y - 年，完整四位。
%Z - 时区，例如："-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 甘特图支持自定义节点样式，使其具备更丰富的表现力。