这堂关于Mermaid核心语法的课程。在上一章，我们了解了Mermaid是什么以及在哪里使用它。现在，我们将动手学习构建图表的“语法规则”，也就是如何创建图表中的基本元素：节点（“方块”）和边（“连接线”）。本课程的所有示例都非常简短，强烈建议您打开 Mermaid 官方的在线编辑器 mermaid.live，一边学习一边亲手尝试下面的每一个小步

第一部分：Mermaid 基础入门

第2章：核心语法与通用概念

2.1 节点 (Nodes)：图表的核心元素

节点是构成流程图等图表的最基本单元。它们代表了流程中的一个步骤、一个系统组件或者一个概念。

好比说：如果你的图表是一张地图，那么节点就是地图上的“城市”。

2.1.1 节点ID 与 节点文本

在Mermaid中，一个节点有两个重要的属性：ID和文本。

第一步：理解节点ID

• 是什么？ 节点ID是你在代码中用来引用这个节点的唯一标识符，它就像是这个节点的“变量名”。ID本身不一定会显示在最终的图表中。

• 好比说：节点ID就像是每个城市的邮政编码，简短、唯一，方便邮政系统（Mermaid代码）识别。

第二步：理解节点文本

• 是什么？ 节点文本是最终显示在图表上、给用户看的文字内容。

• 好比说：节点文本就是城市在地图上标注的全名，比如“北京”或“上海”。

第三步：最简单的节点定义

如果你只写一个ID，那么这个ID同时也会被用作它的显示文本。

代码段

graph TD
    A --> B

在这个例子中，我们创建了两个节点。第一个节点的ID是A，显示的文本也是A。第二个节点的ID是B，显示的文本也是B。

第四步：将ID和文本分开（标准做法）

为了让图表更具可读性，我们通常会将简短的ID和描述性的文本分开。

语法：id[显示文本]

• id 是邮政编码，[显示文本] 是城市的全名。

我们来重写上面的例子：

代码段

graph TD
    startNode[开始处理]
    endNode[结束处理]

    startNode --> endNode

• 发生了什么？

  1. 我们定义了一个ID为startNode的节点，它显示的文字是“开始处理”。

  2. 我们定义了一个ID为endNode的节点，它显示的文字是“结束处理”。

  3. 我们使用它们的ID startNode 和 endNode 来创建连接。

• 最终渲染出来的图表上，你只会看到“开始处理”和“结束处理”这两个方块，而不会看到startNode这些ID。

2.1.2 节点文本的引用与特殊字符处理 (引号的使用)

第一步：遇到问题

如果你的节点文本中包含了Mermaid语法有特殊含义的字符，比如括号 () 或 {}，直接写可能会导致解析错误。

错误的写法:

代码段

graph TD
    A[处理数据(JSON格式)] --> B

Mermaid看到 () 可能会感到困惑，导致图表无法正确渲染。

第二步：使用双引号解决问题

为了解决这个问题，你只需要用双引号 "" 将你的文本整个包裹起来。

正确的写法:

代码段

graph TD
    A["处理数据(JSON格式)"] --> B

现在，Mermaid会把引号内的所有内容都当作纯粹的显示文本，问题就解决了。

第三步：处理引号本身

如果你想在文本中显示一个双引号怎么办？你需要使用HTML实体编码 "。

代码段

graph TD
    A["他说："你好""]

这会在图表中正确地显示出 他说："你好"。

---

2.2 边 (Links/Edges)：连接节点

如果节点是“城市”，那么边就是连接它们的“道路”。边用来表示节点之间的关系或流程的走向。

2.2.1 边的基本语法 (-->)

第一步：学习基础连接符

最基础的边由线条（一个或多个 -）和箭头（>）组成。

代码段

graph TD
    A --> B

• 解读：这行代码定义了一个从节点A指向节点B的有向连接。-- 代表线段，> 代表箭头。

2.2.2 不同类型的箭头 (---, ==>, -.->, <-->)

Mermaid提供了多种样式来表达不同的关系。

第一步：无方向的边 ---

代码段

graph TD
    A --- B

这表示A和B之间有关联，但没有明确的方向。

第二步：粗实线边 ==>

代码段

graph TD
    A ==> B

这通常用来强调一条主要的或重要的路径。

第三步：虚线边 -.->

代码段

graph TD
    A -.-> B

这通常用来表示一条次要的、建议性的或异步的流程。

第四步：双向边 <-->

代码段

graph TD
    A <--> B

这表示A和B之间存在双向的关系。

2.2.3 边的链式定义 (A --> B --> C)

第一步：观察传统写法

要创建一个从A到B，再从B到C的流程，你可以这样写：

代码段

graph TD
    A --> B
    B --> C

第二步：使用链式写法简化

对于这种线性的流程，Mermaid允许你把它们写在同一行，代码更简洁。

代码段

graph TD
    A --> B --> C

这两种写法产生的图表是完全一样的。你甚至可以在一条链中使用不同的边样式：

代码段

graph TD
    A --> B --- C -.-> D

---

2.3 为边添加文本

通常我们需要在边上添加文字，来说明这个流程的条件或名称。

2.3.1 语法：A-- text -->B 或 A-->|text|B

第一步：学习第一种语法（推荐）

在边的 -- 中间插入文本。

代码段

graph TD
    A[用户提交请求] -- 请求合法 --> B[处理请求]
    A -- 请求不合法 --> C[返回错误]

这种写法非常直观。

第二步：学习第二种语法

使用管道符 | 将文本包裹起来。

代码段

graph TD
    A -->|成功| B[进入下一步]
    A -->|失败| C[结束]

第三步：如何选择？

两种语法功能完全一样，你可以根据个人喜好选择。当你的边样式比较复杂时，比如虚线，第二种|text|的写法可能会让代码看起来更整洁一些。

代码段

graph TD
    A -.->|这是一个虚线流程| B

---

2.4 添加注释

2.4.1 语法 (%%) 及其作用

第一步：理解注释的作用

注释是写给你自己或团队其他成员看的笔记。Mermaid渲染引擎会完全忽略注释，它们不会在最终的图表上显示任何内容。

第二步：学习注释语法

使用两个百分号 %% 来开始一行注释。

代码段

graph TD
    %% 这是一个注释，它不会被显示出来。
    %% 下面是流程的开始节点
    Start[开始] --> Process[处理中]
    Process --> End[结束] %% 也可以把注释写在代码行的末尾

第三步：注释的妙用

除了写说明，你还可以用注释来临时禁用一段代码，这在调试复杂图表时非常有用。

代码段

graph TD
    A --> B
    %% B --> C  (暂时不想显示B到C的连接)
    B --> D

---

2.5 关键字与转义

2.5.1 处理包含 Mermaid 关键字的文本 ("end")

第一步：遇到问题

Mermaid有一些保留的关键字，比如 end, subgraph 等，它们有特殊的语法含义。如果你想让一个节点的显示文本就是这些关键字，可能会出问题。

错误的写法:

代码段

graph TD
    A --> end

Mermaid可能会把 end 误解为结束一个代码块的关键字，导致图表渲染失败。

第二步：使用双引号解决

这个问题和2.1.2中处理特殊字符的问题一样，我们再次使用双引号 "" 来解决。

正确的写法:

代码段

graph TD
    A --> "end"

用双引号把关键字包裹起来，Mermaid就会把它当作纯粹的文本来显示。

第三步：结合ID使用的最佳实践

更稳妥的做法是，给这个节点一个独立的ID，然后将带引号的文本作为它的显示文本。

代码段

graph TD
    A[开始] --> end_node["end"]

这样，你的代码既清晰（使用了有意义的ID end_node），又安全（显示文本被引号保护）。