OD(8)之Mermaid甘特图(Gantt diagrams)使用详解
Author: Once Day Date: 2024年2月24日
漫漫长路才刚刚开始…
全系列文章可参考专栏: Mermiad使用指南_Once_day的博客-CSDN博客
参考文章:
- 关于 Mermaid | Mermaid 中文网 (nodejs.cn)
- Mermaid | Diagramming and charting tool
- Mermaid 绘图语法介绍 - 飞书云文档 (larkoffice.com)
- Draw Diagrams With Markdown - Typora Support (typoraio.cn)
- Mermaid 使用教程：从入门到精通——流程图、时序图、甘特图、类图等图形绘制轻松搞定 - 知乎 (zhihu.com)
- 序列图 | Mermaid 中文网 (nodejs.cn)
- mermaid live 在线mermiad工具
文章目录
- OD(8)之Mermaid甘特图(Gantt diagrams)使用详解
- 1. 甘特图概述
- 2. 具体使用介绍
- 2.1 基础语法
- 2.2 任务格式
- 2.3 任务标签(taskLabel)含义
- 2.4 日期格式
- 2.5 日期输入格式表
- 2.6 横轴日期格式表
- 2.7 紧凑显示模式
- 2.7 支持交互(click)
- 2.8 趣味使用(生成柱状图)
1. 甘特图概述
甘特图，以其创始人亨利·甘特（Henry Gantt）的名字命名，是一种广泛使用的项目管理工具，它通过直观的横向条形图来展示项目进度和时间表。甘特图的起源可以追溯到1910年左右，当时亨利·甘特为提高工厂效率，设计了这一工具。随着时间的推移，甘特图已经成为项目经理的重要工具，用于规划、调度和跟踪项目的各个方面。
在甘特图中，每个条形代表一个项目任务，它的长度表示任务的持续时间，位置则显示了任务的起始和结束日期。可以通过不同颜色和长度的条形来区分任务的优先级、状态（如完成、未完成、延期）或者负责人。此外，甘特图还可以显示任务之间的依赖关系，通常以箭头或连线的形式表示，这有助于项目管理者理解任务顺序和时间上的制约因素。
甘特图的优点在于其直观性，非专业人士也能快速理解项目的时间规划。它有助于团队成员看到自己的任务如何与整个项目的进度相连，并且可以作为沟通和协调的工具。然而，它也有缺点，例如在处理复杂项目时，随着任务数量的增加，图表可能变得杂乱无章，难以跟踪。此外，传统的甘特图在显示任务的动态变化或实时更新方面不够灵活。
在使用场景上，甘特图非常适合于需要细致规划的项目，如建筑工程、软件开发、活动策划等。它面向的主要问题是项目时间管理和资源分配，帮助项目团队清晰地看到每个阶段的目标和截止日期，确保项目按时完成。
有趣的是，甘特图的普及和发展与计算机软件的进步密切相关。随着电子表格和项目管理软件的出现，如Microsoft Project，甘特图变得更加易于创建和修改，大大提高了其实用性和普及度。现在，许多项目管理软件都内置了甘特图功能，允许用户轻松地拖动条形来调整任务时间线，同时自动更新整个项目的进度。这种技术进步使得甘特图不仅仅是一个静态的规划工具，而是一个动态的、可以随时调整和优化的项目管理伴侣。
Mermaid是一种基于文本的图表定义语言，它允许开发人员使用代码的方式来创建图表，非常适合嵌入Markdown文件或在线文档中。下面是一个简单的Mermaid甘特图实例：
gantt
dateFormat YYYY-MM-DD
title 项目开发计划
section 设计阶段
需求分析 :done, des1, 2023-04-01, 2023-04-03
原型设计 :active, des2, 2023-04-04, 3d
设计评审 : des3, after des2, 2d
section 开发阶段
基础框架搭建 :crit, active, dev1, 2023-04-08, 2023-04-10
功能模块开发 : dev2, after dev1, 5d
内部测试 : dev3, after dev2, 3d
section 发布阶段
预发布 : pre1, after dev3, 2d
正式发布 : pre2, after pre1, 2d
在这段代码中，首先定义了日期的格式，接着是甘特图的标题。之后，通过section关键字划分了不同的项目阶段，比如设计阶段、开发阶段和发布阶段。每个任务都有一个名称，可能还有其他的状态标记，比如done表示已完成，active表示当前正在进行，crit表示关键路径上的任务。任务的开始和结束日期可以是具体的日期，也可以是相对于其他任务的时间点，如after des2表示任务在des2之后开始。任务的持续时间可以是天数，例如3d表示该任务持续3天。
要将这段代码转换为可视化的甘特图，你可以将其插入支持Mermaid语法的Markdown编辑器或者某些在线Mermaid预览工具中。Mermaid会处理这段代码，并生成一个美观的甘特图，使项目进度一目了然。
一个可用的mermaid在线网站是: Mermaid Live。
2. 具体使用介绍
2.1 基础语法
Mermaid甘特图通过定义一系列任务和里程碑，以图形方式展示项目的时间线。
让我们来看看Mermaid甘特图的基本语法和一些注意事项：
-
定义甘特图：使用
gantt关键字开始描述甘特图。 -
设置日期格式：使用
dateFormat关键字设置日期格式，例如YYYY-MM-DD。 -
设置标题：使用
title关键字后跟标题文本为甘特图设置标题。 -
定义节：使用
section关键字定义不同的项目阶段或任务分类，此名称是必需的。 -
定义任务：
- 任务条目开始于项目节标题后的新行。
- 任务描述后跟冒号和任务ID（可选）、状态（如
active、done）、开始日期和持续时间。 - 状态标记可以是
done（已完成）、active（进行中）、crit（关键路径）、或者不指定。 - 开始日期可以是具体日期或是相对于另一个任务结束的时间（例如
after taskId）。 - 持续时间可以用天数（
d）、周数（w）等表示。
-
里程碑：里程碑通常表示项目中的关键事件，使用类似任务的语法，但持续时间通常是1天。
-
依赖关系：可以通过指定一个任务开始的时间是在另一个任务之后来创建依赖关系，例如
after des2。 -
注意事项：
- 保持代码的结构化和缩进，以提高可读性。
- 确保任务ID的唯一性，因为它们用于定义任务间的依赖关系。
- 日期格式必须与
dateFormat指定的格式相匹配。 - 使用版本支持的Mermaid工具或库，因为不同版本的Mermaid可能在语法支持上有差异。
Mermaid甘特图的一个关键优点是它们可以被版本控制，因为它们是以文本形式编写的，这意味着它们可以很容易地与团队成员共享并集成到工作流程中。
可以在甘特图中输入注释，解析器将忽略该注释。注释需要独占一行，并且必须以 %%（双百分号）开头。注释开始后到下一个换行符的任何文本都将被视为注释，包括任何图表语法。
下面是一个简单的实例，如下:
gantt
%% 定义日期格式
dateFormat YYYY-MM-DD
%% 定义标题
title 文章写作流程(示例)
%% 下面是具体章节的任务
section 开始阶段
选题: done, A1, 2024-02-20, 2d
编写大纲: done, A2, after A1, 1d
section 正式工作
撰写正文: active, A3, after A2, 2d
交稿: milestone, A4, after A3, 1d
2.2 任务格式
mermaid gantt图的任务格式如下，默认是连续的，任务开始日期默认为前一任务的结束日期(如果不填写日期数据):
section 开始阶段
选题: done, A1, 2024-02-20, 2d
<taskDesc>: <taskLabel>, <taskID>, <startDate>, <length>
一个基本的任务定义包括任务的描述、状态、标识符、起始日期以及持续时间，当编写Mermaid甘特图代码时，需要注意以下几点：
- 确保任务ID的唯一性，因为它们会用来定义任务间的依赖关系。
- 遵守定义好的日期格式，以确保Mermaid正确解析日期。
- 如果不指定起始日期，任务将默认在前一个任务结束后开始。
- 各个属性之间要用逗号分隔开，并且保持正确的顺序。
- 冒号
:将任务标题与其元数据分隔开。元数据项由逗号,分隔。 - 有效标签为
active、done、crit和milestone。标签是可选的，但如果使用，则必须首先指定它们。
任务的元数据格式(<taskID>, <startDate>, <length>这部分内容)描述如下表:
| 元数据语法 | 开始日期 | 结束日期 | ID |
|---|---|---|---|
<taskID>, <startDate>, <endDate> | 使用 dateformat 解释的 startdate | 使用 dateformat 解释的 endDate | taskID |
<taskID>, <startDate>, <length> | 使用 dateformat 解释的 startdate | 开始日期 + length | taskID |
<taskID>, after <otherTaskId>, <endDate> | 先前指定任务的结束日期 otherTaskID | 使用 dateformat 解释的 endDate | taskID |
<taskID>, after <otherTaskId>, <length> | 先前指定任务的结束日期 otherTaskID | 开始日期 + length | taskID |
<startDate>, <endDate> | 使用 dateformat 解释的 startdate | 使用 dateformat 解释的 enddate | n/a |
<startDate>, <length> | 使用 dateformat 解释的 startdate | 开始日期 + length | n/a |
after <otherTaskID>, <endDate> | 先前指定任务的结束日期 otherTaskID | 使用 dateformat 解释的 enddate | n/a |
after <otherTaskID>, <length> | 先前指定任务的结束日期 otherTaskID | 开始日期 + length | n/a |
<endDate> | 上一任务的结束日期 | 使用 dateformat 解释的 enddate | n/a |
<length> | 上一任务的结束日期 | 开始日期 + length | n/a |
在实际使用中，除了taskLabel之外(必须在第一个位置)，其他元数据按照以上几种形式排布就好，可以满足我们甘特图所需。此外，还有一个after接多任务的形式，如下:
gantt
apple :a, 2017-07-20, 1w
banana :crit, b, 2017-07-23, 1d
cherry :active, c, after b a, 1d
after <taskId1> <taskId2> ...表明任务的开始日期将根据taskid表示全部任务的最晚结束日期进行设置。
2.3 任务标签(taskLabel)含义
在 Mermaid 的甘特图语法中，active、done、crit 和 milestone 是用来标记任务状态的特殊标签，它们的含义如下：
active：这个标签用来表示任务当前正在进行中。在甘特图中，通常会用不同的颜色或样式来区分活跃的任务，以便于用户识别哪些任务目前是活动的。done：这个标签表示任务已经完成。使用这个标签的任务在甘特图中通常会以不同的方式显示，比如标记为绿色或者用斜线划掉，以表明任务已经结束。crit：这个标签用来标记关键任务。关键任务是指那些对项目进度有重大影响的任务，它们的完成情况对整个项目的按时完成至关重要。在甘特图中，这些任务可能会用特殊的颜色或标记来突出显示。milestone：这个标签用来表示项目中的重要里程碑。里程碑是项目中的关键时间点，通常标志着一个主要阶段的完成或者一个重要决策点。在甘特图中，里程碑通常会以特殊的图标或者标记来表示，以便用户能够快速识别这些重要的时间点。
2.4 日期格式
在Mermaid甘特图中，日期格式的正确设置对于确保任务和里程碑按预期显示至关重要。这里涉及到三个主要方面：
-
输入格式：输入格式是指定义甘特图中任务起始和结束日期时所使用的日期格式。这是通过
dateFormat指令在甘特图定义开始时设置的。它告诉Mermaid如何解析接下来在任务定义中使用的日期字符串。例如，如果你使用
dateFormat YYYY-MM-DD，那么你在定义任务时应该使用格式为“2023-04-01”的日期。这是国际标准格式，也是最常用的一种。 -
坐标轴格式：坐标轴格式影响甘特图中时间轴上日期的显示方式。这是通过
axisFormat指令设置的。axisFormat指令允许你自定义甘特图下方时间轴上的日期和时间显示格式。例如，如果你想在时间轴上显示更详细的日期，可以使用
axisFormat %Y-%m-%d。这里使用的是strftime格式，这种格式在许多编程语言中用于日期和时间的格式化。 -
轴刻度：轴刻度定义了时间轴上日期的间隔和粒度，由甘特图的起始和结束日期、任务的持续时间以及Mermaid的内部算法共同决定的。
轴刻度会自动调整以适应甘特图中的任务跨度。如果任务跨度几个月，轴刻度可能会显示为月份。如果任务跨度很短，可能会显示为天数。
(v10.3.0+)版本后日期间隔可以手动指定，使用
tickInterval关键字，例如1day/1week。基于周的tickInterval默认从星期日开始一周。如果希望指定tickInterval应开始的另一个工作日，请使用weekday选项：gantt tickInterval 1week weekday monday支持以下的格式指定时间刻度:
/^([1-9][0-9]*)(millisecond|second|minute|hour|day|week|month)$/;
下面是一个甘特图的示例，它包含了日期格式和坐标轴格式的定义：
gantt
dateFormat YYYY-MM-DD
axisFormat %Y-%m-%d
tickInterval 0.5day
title Adding Gantt Diagram to Project
section Documentation
Write specification :done, spec1, 2023-04-01, 3d
Review specification :crit, active, after spec1, 2d
在这个示例中：
dateFormat指定了输入格式为“年-月-日”。axisFormat指定了坐标轴上的日期也将以“年-月-日”的格式显示。- 指定轴刻度为2day。
正确使用日期格式有助于确保甘特图的准确性和可读性，使得项目的时间安排一目了然。
2.5 日期输入格式表
| 输入 | 示例 | 描述 |
|---|---|---|
YYYY | 2014 | 4 位数字年份 |
YY | 14 | 2 位数字年份 |
Q | 1…4 | 年的季度。将月份设置为季度的第一个月。 |
M MM | 1…12 | 月份数 |
MMM MMMM | 一月…十二月 | 由 dayjs.locale() 设置的语言环境中的月份名称 |
D DD | 1…31 | 一个月中的哪一天 |
Do | 1st…31st | 带序数的月份中的某一天 |
DDD DDDD | 1…365 | 一年中的某一天 |
X | 1410715640.579 | Unix 时间戳 |
x | 1410715640579 | Unix 毫秒时间戳 |
H HH | 0…23 | 24 小时时间 |
h hh | 1…12 | 与 a A 一起使用的 12 小时时间。 |
a A | 上午下午 | 午后或午前 |
m mm | 0…59 | 分钟 |
s ss | 0…59 | 秒数 |
S | 0…9 | 十分之一秒 |
SS | 0…99 | 一秒几百 |
SSS | 0…999 | 千分之一秒 |
Z ZZ | +12:00 | 与 UTC 的偏移量为 ±HH:mm、±HHmm 或 Z |
更多信息请参考文档: 字符串 + 格式 · Day.js 中文网 (nodejs.cn)。
2.6 横轴日期格式表
| 格式 | 定义 |
|---|---|
| %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(Sunday),6] |
| %W | 一年中的周数（星期一为一周的第一天），十进制数 [00,53] |
| %x | 日期，如 “%m/%d/%Y” |
| %X | 时间，如 “%H:%M:%S” |
| %y | 没有世纪的年份作为十进制数 [00,99] |
| %Y | 年份，世纪为十进制数 |
| %Z | 时区偏移量，例如 “-0700” |
| %% | 一个 “%” 字面字符 |
更多信息请参考文档: GitHub - d3/d3-time-format at v4.0.0。
2.7 紧凑显示模式
Mermaid 甘特图的紧凑模式输出是一个配置选项，它允许你调整甘特图的布局，使得图表以更紧凑的形式显示，减少不必要的空白区域，从而更有效地利用空间。这在绘制包含大量任务的复杂甘特图时尤其有用，因为它可以帮助提升图表的可读性和整体外观。
在Mermaid中，可以通过在定义的开始部分添加displayMode指令来设置紧凑模式。
以下是一个如何开启紧凑模式输出的示例：
---
displayMode: compact
---
gantt
title A Very Tight Gantt Chart
dateFormat YYYY-MM-DD
section Section
A task :a1, 2014-01-01, 30d
Another task :a2, 2014-01-20, 25d
Another one :a3, 2014-02-10, 20d
紧凑模式对于在页面或屏幕上显示更多的信息非常有用，但同时也要注意，如果任务太过密集可能会影响清晰度和可读性。因此，设计时应平衡紧凑性和可用性，确保甘特图既能有效利用空间，又保持良好的可读性。
2.7 支持交互(click)
在使用Mermaid 创建甘特图时，Mermaid 提供了一种增强交互性的功能，允许用户为甘特图中的元素定义点击事件。这个功能通过使用 click 指令来实现，它可以将图表中的任务或部分与JavaScript函数或超链接关联起来，当用户点击这些元素时，就会执行相应的操作。
这种交互功能极大地扩展了Mermaid 甘特图的用途，使得它们不仅仅是静态的图表，而是可以与用户进行动态交云的信息展示工具。
下面是一个简单的例子，展示了如何在Mermaid 甘特图中使用 click 指令来定义点击事件：
gantt
title Interactive Gantt Chart
dateFormat YYYY-MM-DD
section Section
A task :a1, 2023-04-01, 30d
Another task :a2, after a1 , 20d
click a2 href "https://mermaidjs.github.io/"
不过，需要注意的是，Mermaid 是一个基于Markdown和图表库的工具，实现点击功能可能需要与具体使用的平台或应用程序配合。例如，在某些不支持JavaScript执行的环境中，点击事件可能无法正常工作。因此，在设计交互式甘特图时，需要考虑到这些因素。
2.8 趣味使用(生成柱状图)
mermaid的甘特图，可以用一种特殊的方式打开，如下:
gantt
title 这是一个甘特图特殊的用法(我对水果的热爱程度)
dateFormat X
axisFormat %s
section 喜欢苹果
10 : 0, 10
section 喜欢香蕉
30 : 0, 30
section 喜欢西瓜
80 : crit, 0, 80
section 喜欢葡萄
40 : 0, 40
section 喜欢草莓
60 : 0, 60
是不是很有趣，通过甘特图能绘出柱状图出来。
