Markdown画图——Mermaid

前言

对于文档，一张形象的图片对于理解都是事半功倍的效果。对于没有画图美化经验（比如：本作者）的人来说，只关注内容，让工具自动排版，往往是省时省力的做法，Mermaid是其中一款不错的选择。

定义

Mermaid是一种基于文本的图表生成工具，使用类似 Markdown 的语法帮助开发者用代码描述图表结构。它被广泛用于绘制流程图、时序图、甘特图等。Mermaid 集成在许多文档工具中，如 Markdown 编辑器、Typora、GitBook、Docusaurus 等，也支持在网页中直接嵌入渲染。

Mermaid 的语法结构通常包裹在代码块中，通过特定的关键字 mermaid 声明。以下是常见的一些语法类型和使用示例：

语法与示例

1. 流程图 (Flowcharts)

流程图用于描述流程的走向，使用 graph 关键字定义:

代码

css 复制代码

graph LR
    A[开始] --> B{条件判断}
    B -->|是| C[执行动作]
    B -->|否| D[结束]
    C --> D

graph: 声明流程图结构。
TD: 表示图表方向 ------ Top to Down（上下方向，Direction 有多种选项）
- TD：Top Down（从上到下）
- LR：Left to Right（从右到左）
- TB：Top to Bottom（类似 TD）
- BT：Bottom to Top（从下向上）
- RL：Right to Left（从左向右）

节点、连接线和标签：

方括号 []：表示默认节点
花括号 {}：表示带边界的条件节点（条件/判断框）
圆括号 ()：表示子流程/普通节点
-->：箭头连接线，表示流程方向
|...|：连接线上描述信息（如条件判断）

效果图

graph LR A[开始] --> B{条件判断} B -->|是| C[执行动作] B -->|否| D[结束] C --> D

2. 时序图（Sequence Diagrams）

时序图描述系统的交互过程，常用于展示组件之间消息的顺序，用 sequenceDiagram 开始

代码

rust 复制代码

sequenceDiagram
    participant 用户
    participant 浏览器
    participant API
    participant 数据库
    
    用户->>浏览器: 输入网址
    浏览器->>API: 发送请求
    API->>数据库: 查询数据
    数据库-->>API: 返回结果
    API-->>浏览器: 返回响应
    浏览器-->>用户: 显示页面

participant：定义参与对象，as 可定义别名，让脚本简短
->>：实线箭头
-->>：虚线箭头
activate, deactivate：激活与取消激活组件生命线

效果图

sequenceDiagram participant 用户 participant 浏览器 participant API participant 数据库用户->>浏览器: 输入网址浏览器->>API: 发送请求 API->>数据库: 查询数据数据库-->>API: 返回结果 API-->>浏览器: 返回响应浏览器-->>用户: 显示页面

3. 甘特图（Gantt）

甘特图用于项目管理或展示时间进度，用 gantt 开始

代码

ruby 复制代码

gantt
    title 项目时间表
    dateFormat  YYYY-MM-DD
    section 引入阶段
    需求分析               :a1, 2024-01-01, 30d
    设计                   :a2, after a1, 40d
    section 开发阶段
    前端开发               :a3, 2024-02-01, 60d
    后端开发               :a4, 2024-02-15, 60d
    section 测试阶段
    单元测试               :a5, after a3, 10d
    系统测试               :a6, after a4, 20d

title: 定义标题
dateFormat: 定义时间格式
section：定义不同阶段
after: 表示基于前一个任务的时序
30d / 2w: 表示时间长度（day/week）
:a1: 节点 ID 可用于任务间依赖（子图逻辑）

效果图

gantt title 项目时间表 dateFormat YYYY-MM-DD section 引入阶段需求分析 :a1, 2024-01-01, 30d 设计 :a2, after a1, 40d section 开发阶段前端开发 :a3, 2024-02-01, 60d 后端开发 :a4, 2024-02-15, 60d section 测试阶段单元测试 :a5, after a3, 10d 系统测试 :a6, after a4, 20d

4. 类图（Class Diagrams）

用于绘制面向对象设计的类图，用 classDiagram 开始

代码

arduino 复制代码

classDiagram
    class Student {
        -String name
        +public method()
    }
 
    class School {
        -String address
    }
 
    Student --> "0..*" School : belongs to

class: 声明类以及其内部属性
{} ：中的内容是类结构（+ 公有，- 私有，~ 受保护）
--> ：表示类之间的关联关系
0..* ：在箭头两边添加基数（如 0..*）表示类之间的关联数量

效果图

classDiagram class Student { -String name +public method() } class School { -String address } Student --> "0..*" School : belongs to

5. 状态图 (State Diagrams)

状态图用于表达系统状态及其转换情况，用 stateDiagram 开始

代码

lua 复制代码

stateDiagram
    [*] --> 未启动
    未启动 --> 运行中: 开始
    运行中 --> 已完成: 完成
    已完成 --> [*]: 系统结束

[*] 代表初始状态或结束状态。
--> 表示状态转换的箭头。
: 注释：标注操作或消息触发条件。

效果图

stateDiagram [*] --> 未启动未启动 --> 运行中: 开始运行中 --> 已完成: 完成已完成 --> [*]: 系统结束

复杂声明以及图示

rust 复制代码

stateDiagram
    state If_Success {
        [*] --> Ok
        Ok --> [*]
    }

    state If_Failed {
        [*] --> Error
        Error --> [*]
    }

    Start --> If_Success: 正确输入
    Start --> If_Failed: 错误输入

stateDiagram state If_Success { [*] --> Ok Ok --> [*] } state If_Failed { [*] --> Error Error --> [*] } Start --> If_Success: 正确输入 Start --> If_Failed: 错误输入

state ... {}：构建子状态组

6. Git 图（Git Graph）

用于表达版本控制中 Git 分支的拓扑结构，以 gitGraph 开始

sql 复制代码

gitGraph
    commit id: "init"
    commit
    branch dev
    commit
    commit
    checkout main
    merge dev

gitGraph：定义为 Git 图。
commit：表示一次提交。
id: 给提交打上唯一标识符（任意字符串）
branch：新建分支。
checkout：切换到该分支。
merge：将分支合并。

效果图

gitGraph commit id: "init" commit branch dev commit commit checkout main merge dev

常用保留符号及注意事项

符号	用途	说明
`-->`	箭头流向	流程图中最常见连接线表达方式
`<-->`	双向箭头	表示两个节点/状态可以双向跳转
`=>`	粗节点线	用于某些流程图表示重要流程，如高亮分支
`---`	普通横线连接	`A --- B` 只连接两节点但未定义流向（不推荐常规路径）
`:`	节点标注或时间定义	`:a1` 用于节点命名，如：A[a] :a1
`	`	分段条件/分支标签
`%%`	注释符	`%% 这是一个注释`
`"`	文本域引用	`"标签名称"` 更可靠地匹配中文或含空格内容
`{}`	类图或状态图的组内容	类图属性分组，状态嵌套都会使用
`[]`	表示流程图中的节点（非条件）	示例：`A[流程] --> B`
`{}`	流程图中的节点（判断类）	示例：`B{判断}`
`()`	子图内容定义（较少见）	特殊类型节点，例如模块调用、自定义节点
`as`	给参与方起别名	例如：`participant P as Prometheus`
`classDef`	定义类样式	用于定义图中节点的显示风格
`class`	将类样式赋给某个节点	例如：`class A custom-class`
`subgraph`	定义子图区域	流程图中划分子结构的语法
`[ID]`	定义节点 ID（不是显示名）	成功节点：`A[成功] :success_node`
`since`	类图中变更标记日期	在 UML 类图表示属性从什么版本/日期开始存在

数字、时间、单位标记

符号	示例	说明
`30d`	`a1, 2024-01-01, 30d`	表示持续 30 天
`2w`	`a2... 2w`	表示持续两周
`dateFormat`	`YYYY-MM-DD`	甘特图表示时间的标准格式
`section`	甘特图中的阶段划分	用于分段工程项目，例如"研发阶段 / 测试阶段"

尾声

Mermaid 可以让开发者专注于图表内容和逻辑，而不必关注外在的形象，熟悉语法之后画一张图还是挺方便的。

参考来源：Qwen: Qwen3 235B A22B

一家之言，如有谬误，欢迎指正！