Mermaid语法

Fan 收录于类别软件折腾

2025-06-30 2025-07-30 约 3284 字预计阅读 15 分钟

1 Mermaid 语法详解：像写 Markdown 一样轻松绘制图表

Mermaid 是一种轻量级的、基于文本的图表绘制工具，它允许你使用类似 Markdown 的简洁语法来创建各种复杂的图表和可视化内容。由于其学习成本低、易于集成和版本控制的特性，Mermaid 在开发者社区和技术文档中广受欢迎。

本详解将带你深入了解 Mermaid 的核心语法，涵盖从基础的流程图到复杂的类图和状态图，并提供丰富的示例，助你轻松掌握这项强大的工具。

1.1 核心概念

在开始之前，我们先了解几个 Mermaid 的核心概念：

声明图表类型 (Diagram Type Declaration): 每一个 Mermaid 图表都以一个关键字开始，用以声明你想要创建的图表类型，例如 flowchart、sequenceDiagram 或 classDiagram。
节点 (Nodes): 节点是图表中的基本元素，代表一个实体、一个步骤或一个状态。你可以为节点指定不同的形状、文本和 ID。
关系 (Relationships): 关系用于连接不同的节点，表示它们之间的流转、交互或关联。Mermaid 提供了多种箭头和线条样式来表示不同的关系。
代码块 (Code Block): 在支持 Mermaid 的平台（如 GitHub, GitLab, Notion 等）上，你只需将 Mermaid 语法包裹在 ```mermaid 代码块中即可渲染出图表。

1.2 图表类型详解

Mermaid 支持多种类型的图表，以下将对其中最常用的几种进行详细解析。

1.2.1 1. 流程图 (Flowchart)

流程图是 Mermaid 中最基础也最常用的图表类型，用于表示一个过程或工作流。

基本语法:

方向: 使用 graph 或 flowchart 关键字开始，并紧跟方向声明：
- TD 或 TB: 从上到下 (Top to Bottom)
- BT: 从下到上 (Bottom to Top)
- LR: 从左到右 (Left to Right)
- RL: 从右到左 (Right to Left)
节点:
- id[文本]：矩形节点
- id(文本)：圆角矩形节点
- id((文本))：圆形节点
- id{文本}：菱形（判断）节点
- id>文本]：不对称矩形节点
连接线:
- -->: 带箭头的实线
- ---: 不带箭头的实线
- -.->: 带箭头的虚线
- -- 文本 -->: 带文本的连接线

示例:

flowchart TD
    A[开始] --> B{条件判断};
    B -->|是| C[执行操作A];
    B -->|否| D[执行操作B];
    C --> E[结束];
    D --> E;

高级用法:

子图 (Subgraph): 使用 subgraph 和 end 关键字可以将一组节点组织在一起。

flowchart TD
    subgraph "主要流程"
        A[开始] --> B{处理数据?};
    end
    subgraph "数据处理"
        B --> C[清洗数据];
        C --> D[分析数据];
    end
    D --> E[结束];

1.2.2 2. 序列图 (Sequence Diagram)

序列图（又称时序图）用于展示对象之间如何随着时间的推移进行交互。

基本语法:

参与者 (Participants): 直接写参与者名称即可创建。可以使用 participant 关键字并为其指定别名。
消息 (Messages):
- ->: 实线箭头（同步消息）
- -->: 虚线箭头（异步消息）
- ->>: 带实心箭头的实线
- -->>: 带实心箭头的虚线
- -x: 带叉的箭头（表示消息丢失或拒绝）
激活 (Activations): 使用 activate 和 deactivate 来表示参与者的活动状态。
注释 (Notes): 使用 Note right of/left of/over 来添加注释。
循环/分支 (Loops/Alternatives): 使用 loop、alt、opt 和 end 来构建复杂的交互逻辑。

示例:

sequenceDiagram
    participant Alice
    participant Bob
    Alice->>Bob: 你好，Bob！
    activate Bob
    Bob-->>Alice: 你好，Alice！
    deactivate Bob
    Note right of Alice: Alice 等待回复

    loop 健康检查
        Bob->>Bob: 检查自己的状态
    end

    alt 成功
        Bob-->>Alice: 一切正常！
    else 失败
        Bob-->>Alice: 出现了一些问题...
    end

1.2.3 3. 甘特图 (Gantt Chart)

甘特图用于项目管理，清晰地展示任务的排期和进度。

基本语法:

gantt: 声明为甘特图。
title: 设置图表标题。
dateFormat: 定义日期格式 (例如 YYYY-MM-DD)。
section: 定义任务分组。
任务定义: 任务名称 :状态, 任务ID, 开始时间, 持续时间
- 状态 (可选): done (已完成), active (进行中), crit (关键路径)。
- 开始时间: 可以是具体日期，也可以是 after 另一个任务ID。
- 持续时间: 例如 3d (3天), 2w (2周)。

示例:

gantt
    title 项目开发计划
    dateFormat  YYYY-MM-DD
    section 需求分析
    需求调研 :done, des1, 2025-08-01, 3d
    原型设计 :active, des2, after des1, 4d
    section 开发阶段
    前端开发 :crit, dev1, after des2, 10d
    后端开发 :crit, dev2, after des2, 12d
    section 测试阶段
    功能测试 : 2025-08-25, 5d

1.2.4 4. 类图 (Class Diagram)

类图是 UML (统一建模语言) 的一种，用于描述系统的静态结构，展示类、接口以及它们之间的关系。

基本语法:

classDiagram: 声明为类图。
定义类: class 类名 或直接通过关系定义。
类成员: 在类定义的花括号内或使用冒号定义。
- + 表示 public
- - 表示 private
- # 表示 protected
- ~ 表示 package/internal
- 方法() 括号表示方法，否则为属性。
- 可以使用泛型，如 List<String>。
关系 (Relationships):
- <|-- : 继承 (Inheritance)
- *-- : 组合 (Composition)
- o-- : 聚合 (Aggregation)
- --> : 关联 (Association)
- -- : 链接 (Link)
- ..> : 依赖 (Dependency)
- ..|>: 实现 (Realization)
基数 (Cardinality): 在关系的两端用引号表示，如 "1"、"0..*"。

示例:

classDiagram
    class Animal {
      +String name
      +eat()
    }
    Animal <|-- Duck
    Animal <|-- Fish
    Animal "1" --o "0..*" Food : eats
    class Duck {
      +quack()
    }
    class Fish {
      +swim()
    }
    class Food

1.2.5 5. 状态图 (State Diagram)

状态图用于描述一个对象在其生命周期内所经历的各种状态以及状态之间的转换。

基本语法:

stateDiagram-v2: 推荐使用的状态图声明。
状态 (States): 直接写状态名称。可以使用 state "描述" as 别名 的方式。
转换 (Transitions): 状态1 --> 状态2 : 转换条件。
起始和结束: [*] 代表起始或结束状态，由箭头方向决定。
复合状态 (Composite States): 使用 state 状态名 { ... } 来创建嵌套的状态。
选择 (Choice): 使用 <<choice>> 来表示一个决策点。
分支和合并 (Fork and Join): 使用 <<fork>> 和 <<join>> 来表示并发状态。

示例:

stateDiagram-v2
    [*] --> Off
    Off --> On : turn on
    On --> Off : turn off

    state On {
        [*] --> Idle
        Idle --> Running : start
        Running --> Idle : pause
    }

1.2.6 6. 实体关系图 (Entity Relationship Diagram)

ER图用于数据库设计，展示实体（表）以及它们之间的关系。

基本语法:

erDiagram: 声明为ER图。
实体 (Entities): 实体名 { 属性类型属性名 }。
关系 (Relationships): 实体A ||--o{ 实体B : 关系描述
- |o – o|: 零或一
- || – ||: 只有一
- }o – o{: 零或多
- }| – |{: 一或多
- -- 表示非识别关系 (虚线)
- — 表示识别关系 (实线)

示例:

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE-ITEM : contains
    CUSTOMER }|..|{ DELIVERY-ADDRESS : uses

    CUSTOMER {
        string name
        string email
        int customerId PK
    }
    ORDER {
        int orderId PK
        datetime orderDate
        int customerId FK
    }
    LINE-ITEM {
        int itemId PK
        int orderId FK
        string product
    }

1.3 其他图表类型

除了以上详细介绍的几种，Mermaid 还支持更多类型的图表，其语法也同样遵循简洁直观的原则：

饼图 (Pie Chart): 用于展示数据的比例分布。
用户旅程图 (User Journey): 描述用户完成特定任务所经历的步骤和情绪。
需求图 (Requirement Diagram): 可视化系统需求及其关系。
Git 图 (Git Graph): 以图形方式展示 Git 的分支和提交历史。
C4 图 (C4 Diagram): 用于软件架构的可视化，包含上下文、容器、组件和代码四个层次。

由于篇幅限制，此处不一一展开。你可以通过查阅 Mermaid 的官方文档来获取这些图表的详细语法和示例。

1.4 全局配置与主题

Mermaid 允许通过指令 (Directives) 来进行一些全局配置和主题更换。指令写在 %%{ ... }%% 中。

示例：更换主题

%%{init: {'theme': 'dark'}}%%
flowchart LR
    A[深色主题] --> B[感觉不错];

可用的主题包括 default, forest, dark, neutral 等。

1.5 转义符

在 Mermaid 中，处理“转义”问题的方式与许多传统编程语言不同。它没有一个像反斜杠 \ 那样的通用转义符。

相反，Mermaid 主要通过以下两种方式来处理包含特殊字符、空格或与语法关键字冲突的文本：

使用双引号 " 将文本包围起来
使用HTML实体编码 (Entity Codes)

1.6 主要方法：使用双引号 `"`

这是最常用、也最重要的方法。当你的节点文本或标签包含以下内容时，你应该用双引号将其整个包裹起来：

空格
括号 ()、方括号 []、花括号 {}
会与语法冲突的特殊字符 (如 -, >, ; 等)
Mermaid 的保留关键字 (如 graph, end, style 等)

通过将文本放在引号中，你告诉 Mermaid：“将引号内的所有内容都当作纯文本字符串来处理，不要用你的语法规则来解析它。”

1.6.1 示例：

假设你想创建一个流程图，其中一个节点的文本是 这个节点 (包含括号)！。

错误写法 (不使用引号):

flowchart TD
    A[这是一个节点] --> B(这个节点 (包含括号)！)

上面的代码会因为括号 () 的存在而导致语法解析错误，无法正确渲染。

正确写法 (使用引号):

flowchart TD
    A[这是一个节点] --> B["这个节点 (包含括号)！"]

通过将文本 这个节点 (包含括号)！ 放入双引号中，Mermaid 就能正确地将其识别为节点的标签。

更多示例：

flowchart LR
    id1["包含特殊字符 *&^%$#@!"]
    id2["使用保留字 end"]
    id3["这是一个带空格的长标签"]

    id1 --> id2 --> id3

1.7 2. 辅助方法：HTML 实体编码

对于一些非常特殊的字符，尤其是双引号 " 本身，或者你希望在文本中强制插入某些符号时，可以使用类似 HTML 的实体编码。

实体编码的格式通常是 &# + 数字 + ;。

1.7.1 示例：在节点中显示双引号

如果你想让节点的文本包含双引号，例如 A节点说："Hello"，你可以这样做：

flowchart TD
    A["A节点说："Hello""]

在这里，" 是双引号 " 的实体编码。

你也可以使用命名实体，如 "：

flowchart TD
    A["A节点说："Hello""]

1.7.2 常用实体编码：

字符	命名实体	数字编码
`"`	`"`	`"`
`'`	`'`	`'`
`&`	`&`	`&`
`<`	`<`	`<`
`>`	`>`	`>`
`#`	-	`#`

示例：显示 # 号

flowchart LR
    A["显示井号：#"] --> B["或者这样：#hash;"]

目录

目录

Mermaid语法

1 Mermaid 语法详解：像写 Markdown 一样轻松绘制图表

1.1 核心概念

1.2 图表类型详解

1.2.1 1. 流程图 (Flowchart)

1.2.2 2. 序列图 (Sequence Diagram)

1.2.3 3. 甘特图 (Gantt Chart)

1.2.4 4. 类图 (Class Diagram)

1.2.5 5. 状态图 (State Diagram)

1.2.6 6. 实体关系图 (Entity Relationship Diagram)

1.3 其他图表类型

1.4 全局配置与主题

1.5 转义符

1.6 主要方法：使用双引号 `"`

1.6.1 示例：

1.7 2. 辅助方法：HTML 实体编码

1.7.1 示例：在节点中显示双引号

1.7.2 常用实体编码：

目录

Mermaid语法

1 Mermaid 语法详解：像写 Markdown 一样轻松绘制图表

1.1 核心概念

1.2 图表类型详解

1.2.1 1. 流程图 (Flowchart)

1.2.2 2. 序列图 (Sequence Diagram)

1.2.3 3. 甘特图 (Gantt Chart)

1.2.4 4. 类图 (Class Diagram)

1.2.5 5. 状态图 (State Diagram)

1.2.6 6. 实体关系图 (Entity Relationship Diagram)

1.3 其他图表类型

1.4 全局配置与主题

1.5 转义符

1.6 主要方法：使用双引号 "

1.6.1 示例：

1.7 2. 辅助方法：HTML 实体编码

1.7.1 示例：在节点中显示双引号

1.7.2 常用实体编码：

1.6 主要方法：使用双引号 `"`