Mermaid图表工具

​ 此文作为Markdown教程的附属章节，将带你了解如何在Markdown中绘制常用的流程图等图表，希望能让你体会到“文生图”的魅力。

了解Mermaid

​ Mermaid 是一种使用代码块生成流程图、饼状图、甘特图等图表的描述语言。Mermaid可以作为 JavaScript 库使用，也可以作为独立的命令行工具使用。使用 Mermaid，用户可以在文本编辑器中编写图表定义，而无需使用专业的图表工具或图形用户界面。

​ 对于绘制图表来说，直接使用图形化界面来绘制似乎是最简单方便的选择，而且市面上有那么多好用方便的画图工具，不仅全程可视化操作，模板、组件样样齐全，为什么还要使用Mermaid这样的代码工具来生成图片？

​ 作为开发者，我们习惯了使用代码来控制一切，常见的绘图工具（如Visio，WPS等）直接在可视化界面中绘制图表，固然操作简单明了，但你不仅需要花时间进行排版、格式等细微操作，还要面临不同格式导入导出、版本管理困难（难以追踪修改历史）等诸多问题。简而言之，你不再能用代码掌控一切，并且绘制图表需要你“切换上下文”，跳出去画图再截图粘贴，或导出再导入，不仅摧毁了你简洁和谐的代码和排版，还严重打断了你的代码思路。毫无疑问，这太致命了。

​ Mermaid 最大的优点是它的简单性和可移植性。用户可以轻松地将图表嵌入到任何支持 HTML或Markdown的文档中，并且任何文字编辑器都可以编辑这些图表。

使用Mermaid

使用内置支持Mermaid的文本编辑器：

  • Typora

使用内置支持Mermaid的Markdown渲染器：

-

安装 Mermaid

  • NPM: npm i mermaid
  • Yarn: yarn add mermaid
  • Pnpm: pnpm add mermaid

Mermaid语法基础——快速开始

以下列举几个常用图表类型的的基础写法，帮助您快速开始使用Mermaid。

流程图（Flowchart）

代码示例：

1
2
3
4
5
6
graph TD
    A[开始] --> B[审批]
    B --> C{审批通过?}
    C -- 否 --> D[修改]
    D --> C
    C -- 是 --> E[结束]

效果图：

graph TD
    A[开始] --> B[审批]
    B --> C{审批通过?}
    C -- 否 --> D[修改]
    D --> C
    C -- 是 --> E[结束]

时序图（Sequence Diagram）

代码示例：

1
2
3
4
5
6
7
sequenceDiagram
  //参与者的声明顺序即表示绘制的顺序，也可以隐式定义
  participant A as 服务端
  participant B as 客户端
  A->>B: SYN=1, seq=x
  B->>A: SYN=1, ACK=1, seq=y, ack=x+1 
  A->>B: ACK=1, seq=x+1, ack=y+1

示意图：

sequenceDiagram
  participant A as 服务端
  participant B as 客户端
  A->>B: SYN=1, seq=x
  B->>A: SYN=1, ACK=1, seq=y, ack=x+1 
  A->>B: ACK=1, seq=x+1, ack=y+1

引用官方说明，单词“end”可能会破坏图表，这是由于 mermaid 语言的编写方式造成的。 如果不可避免，则必须使用括号()、引号””或方括号{}、[]将单词“end”括起来。例如：(end)、[end]、{end}。

甘特图（Gantt Chart）

使用gantt关键字定义一个甘特图，title定义图表标题，dateFormat 定义日期格式。

然后，定义了一个部分 Section，并定义三个任务 task 1、task 2 和 task 3，并指定了开始日期和持续时间。

代码示例：

1
2
3
4
5
6
7
gantt
   title Example Gantt Chart
   dateFormat  YYYY-MM-DD
   section Section
   task 1: 2019-01-01, 30d
   task 2: 2019-02-01, 14d
   task 3: 2019-03-01, 7d
gantt
   title Example Gantt Chart
   dateFormat  YYYY-MM-DD
   section Section
   task 1: 2019-01-01, 30d
   task 2: 2019-02-01, 14d
   task 3: 2019-03-01, 7d

饼图（pie chart）

代码示例：

1
2
3
4
5
pie
   title Example Pie Chart
   "First slice": 30
   "Second slice": 20
   "Third slice": 50
pie
   title Example Pie Chart
   "First slice": 30
   "Second slice": 20
   "Third slice": 50

Mermaid 进阶语法

流程图

节点形状

在流程图中，你可以自定义各个节点的形状，各形状对应的语法如下：

​ 带圆边的方形节点： id1[自定义文本]

​ 体育馆形状的节点：id1([自定义文本])

​ 框中框形状的节点：id1[[自定义文本]]

​ 圆柱形节点：id1[(自定义文本)]

​ 圆形节点：id1((自定义文本))

​ 标签形状（不对称形状）的节点：id1>自定义文本]

​ 菱形节点：id1{自定义文本}

​ 六边形节点：id1{{自定义文本}}

​ ……

还有很多节点类型，这里就仅展示一些常用的形状，更多节点类型可查看官方文档或其他说明文档。

流程图语法 | Mermaid中文文档

节点的连接

节点与节点之间使用箭头、直线、虚线等形状进行连接，还可以附文本。各形状对应的语法如下：

​ 直线连接：A---B

​ 带箭头的连接：A-->B

​ 带文本的连接：A--自定义文本-->B 或 A-->|自定义文本|B

​ 虚线连接：A-.->B

​ 带文本的虚线连接：A-.自定义文本-.>B 或 A-.->|自定义文本|B

​ 粗线连接：A==>B （带文本形式略）

​ 多方向箭头： A<-->B Ao--oB Ax--xB

链式连接

可以在同一行中声明多个链接，如下所示：

​ A -- 文本 --> B -- 文本2 --> C

等价于：

​ A -- 文本 --> B

​ B -- 文本2 --> C

也可以在同一行中声明多个节点链接，如下所示：

​ A --> B & C --> D

等价于：

​ A --> B

​ A --> C

​ B --> D

​ C --> D 

flowchart LR
  A --> B & C --> D

链接的长度

虽然表面上没有显示，但是Mermaid流程图中是存在排列等级的，不同节点若处于同一等级将被排列在同一排（列）中。通常情况下，我们不需要关心节点之间的排列等级，一切都是自动排列的，但是你可以通过在链接定义中添加符号，手动延长某一个链接。

下面是前文流程图的示例代码，我们在节点C到E中添加了一个 - 。

1
2
3
4
5
6
graph TD
    A[开始] --> B[审批]
    B --> C{审批通过?}
    C -- 否 --> D[修改]
    D --> C
    C -- 是 ---> E[结束] //这里新增了一个‘-’
graph TD
    A[开始] --> B[审批]
    B --> C{审批通过?}
    C -- 否 --> D[修改]
    D --> C
    C -- 是 ---> E[结束]

可以看到，“结束”节点被排列到了下一层级，不再与“修改”节点齐平。

实际上，你可以继续增加 - 符号的数量，让这个链接更长，“结束”节点会不断被排列到下一个层级。