Mermaid 绘图指南（一）- Mermaid图表绘制语法详解与实战示例

Mermaid 绘图指南（一）- Mermaid图表绘制语法详解与实战示例

Author	Date	Version	Note
Tao Wang	2025-04-24	V1.0	Release the document.

一、工具概述

1.1 工具简介

Mermaid是一款基于JavaScript的开源图表绘制工具，采用类Markdown语法，可将文本代码自动转换为视觉化图表。它特别适合工程项目、技术文档和系统模型化描述。其核心优势包括：

• 纯文本编辑：支持版本控制与协作开发
• 跨平台兼容：主流Markdown编辑器原生/插件支持
• 多图类型支持：涵盖流程图、时序图、甘特图等常见图表类型

项目仓库：GitHub官方地址

1.2 快速入门

使用Mermaid前，可根据需求选择独立部署或相关编辑器插件，为绘制代码提供观图支持。

方案类型	实现方式	推荐工具
独立渲染方案	本地部署Mermaid解析库	Node.js项目集成
编辑器集成方案	使用支持Mermaid的Markdown编辑器	Typora、VS Code、Obsidian

1.3 图表类型支持

Mermaid支持多种常用的类型图表，合适各类项目场景使用。

图表类型	语法关键字	典型应用场景
流程图	graph/flowchart	程序逻辑流程
序列图	sequenceDiagram	系统交互时序
甘特图	gantt	项目进度管理
类图	classDiagram	面向对象设计
状态图	stateDiagram	系统状态转换
饼状图	pie	数据占比分析
用户旅程图	journey	用户体验流程

1.4 实战案例：明代皇族谱系

以「明太祖」为根，组织其各子孙继承关系，体现谱系规模和传承联系。

```mermaid
graph TD
    A((明太祖 朱元璋))

    A --> B((朱标))
    B --> C((建文帝 朱允炆))

    A --> D((朱樉))
    A --> E((朱棡))
    A --> F((永乐帝 朱棣))
    F --> G((洪熙帝 朱高炽))
    G --> H((宣德帝 朱瞻基))
    H --> I((正统帝 朱祁镇))
    I --> J((英宗复辟))

    F --> K((汉王 朱高煦))
    F --> L((赵王 朱高燧))

    B --> M((周王 朱橚))
    D --> N((秦王 朱樉子孙))
    E --> O((晋王 朱棡子孙))
```

二、饼状图开发规范

饼状图用于描述数据分布或统计结果的类比图，一般用于相同类目的占比分析。

2.1 语法结构

```mermaid
pie
    title 图表标题（可选）
    "分类标签" : 数值（支持两位小数）
```

参数说明表

参数项	数据类型	是否必填	示例
title	字符串	否	title 年度销售占比
分类标签	字符串	是	“电子产品”
数值	浮点数	是	42.96

2.2 开发示例

通过简单语法展示用户用途分析结果，方便在报表或统计中直观进行对比。

```mermaid
pie
title 用户行为分析
"社交需求" : 38.2
"知识获取" : 27.4
"娱乐消遣" : 19.1
"其他" : 15.3
```

2.3 调试工具推荐

• 官方在线编辑器
• VSCode Mermaid Preview插件
• Markdown Navigator（IntelliJ插件）

三、流程图高级应用

3.1 基础语法树

基本流程图通过节点和条件判断，描述一个逻辑流程过程，适用于程序规划和故障模型描述。

```mermaid
flowchart TD
A[起始节点] --> B{条件判断}
B -->|满足条件| C[执行操作]
C --> D[结束流程]
B -->|不满足| E[异常处理]
```

3.2 方向控制指令

通过配置流程方向，可以实现上下、左右各种缩放布局需求。

指令语法	流向说明	应用场景
graph TB/TD	从上至下	标准流程图
graph BT	从下至上	逆向流程展示
graph LR	从左至右	横向流程布局
graph RL	从右至左	阿拉伯语系布局

3.3 节点样式库

提供多样形式节点描述，适用于区分功能、逻辑类型、特殊进程等场景。

```mermaid
graph LR
A[标准矩形]
B(圆角矩形)
C((圆形节点))
D{条件判断}
E[[子程序]]
F[/斜体标签/]
G[\反斜标签\]
```

3.4 连接线样式表

可轻松描述先后关系，形成精细缩放效果。

语法	线型说明	渲染效果
–>	实线箭头	▬▬▬▶
—	实线无箭头	▬▬▬
==>	粗实线箭头	▬▬▬▶（加粗）
-.-	虚线无箭头	- - -
-.->	虚线箭头	- - - ▶
o–o	空心圆连接	○──○
x–x	交叉线连接	×──×

3.5 复合流程图示例

通过subgraph实现模块化分区，适合对复杂系统进行功能分析。

```mermaid
flowchart TB
    subgraph 认证模块
        A[用户登录] --> B{验证通过?}
        B -->|是| C[授予权限]
        B -->|否| D[记录日志]
    end

    subgraph 业务模块
        C --> E[数据查询]
        E --> F[结果展示]
    end

    认证模块 --> 业务模块
```

四、进阶技巧

4.1 注释规范

通过%%进行注释，方便文档和同步输出的管理。

```mermaid
graph LR
%% 用户登录流程
Start[开始] --> Input[输入凭证]
Input --> Validate{验证}
Validate -->|成功| Session[建立会话]
Validate -->|失败| Error[显示错误]
```

4.2 多线连接优化

支持使用&快速表达多条路径连接，简化代码写法。

```mermaid
graph TD
A --> B & C
B --> D
C --> E
D & E --> F
```

4.3 版本兼容建议

为保障效果正确呈现，建议使用最新稳定版本，对旧版本则符合兼容性开发规范。

功能特性	最低版本要求	替代方案
六边形节点	8.5+	使用标准矩形+注释
子图支持	9.0+	使用独立流程图
自动布局优化	10.0+	手动调整节点间距