前言

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

定义

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

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

#技术分享语法与示例

TypeScript 1. 流程图 (Flowcharts)

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

代码

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

C 2. 时序图（Sequence Diagrams）

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

代码

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 开始

代码

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

C 4. 类图（Class Diagrams）

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

代码

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 开始

代码

stateDiagram
    [*]
    未启动
    运行中
    已完成

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

效果图

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

复杂声明以及图示

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 开始

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

常用保留符号及注意事项

| 符号 | 用途 | 说明 | | ---

| --> | 箭头流向 | 流程图中最常见连接线表达方式 | | <--> | 双向箭头 | 表示两个节点/状态可以双向跳转 | | => | 粗节点线 | 用于某些流程图表示重要流程，如高亮分支 | | ---

| : | 节点标注 或 时间定义 | :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

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