进阶 mermaid.ai 2026-11-12 20:48:10 · 21 阅读

第13章 编写图表语法

编写图表语法

Mermaid 语法本质上是一种有固定结构的纯文本。掌握基本规则后,你无需借助 AI 面板就能构建和编辑任何图表——而且当图表需要修改时,你也能准确知道该改哪里。

本指南深入讲解流程图(flowchart)语法。其他图表类型遵循同样的原理,OSS 文档中有每种类型的完整语法参考。浏览 OSS 语法文档 →

语法的工作原理

每个图表都以一条类型声明开头,告诉 Mermaid 要渲染哪种图表:

flowchart LR sequenceDiagram erDiagram mindmap gantt

接下来的内容定义图表的具体内容——节点、连线、标签、样式和分组。在编辑器中输入时,图表会实时渲染。

流程图方向

对于流程图,方向紧跟在类型声明之后:

方向 | 代码 | 适用场景 从左到右 | LR | 流程、工作流、时间线 从上到下 | TD 或 TB | 层级结构、组织架构图、决策树 从下到上 | BT | 反向层级 从右到左 | RL | 较少用——特定布局需求

方向对可读性的影响比多数人想象的大。同一个图表,流向不同,可能清晰也可能混乱。如果布局看起来不对,先试着改方向,再考虑调整其他内容。

节点

节点是流程图的基本构件。形状本身带有含义——请有意识地使用。

语法 | 形状 | 适用场景 A[Label] | 矩形 | 默认——步骤、操作、任务 A(Label) | 圆角矩形 | 更柔和的步骤,起点和终点 A{Label} | 菱形 | 有分支路径的判断 A((Label)) | 圆形 | 事件、端点、循环连接点 A[/Label/] | 平行四边形 | 输入或输出 A[(Label)] | 圆柱体 | 数据库、数据存储 A[[Label]] | 子程序 | 子流程或引用的流程 A>Label] | 非对称形 | 标记、标签

节点 ID 和标签是分开的。ID 用于在连线中引用节点,标签则是图表中实际显示的文字。只需定义一次标签,其余地方用 ID 引用即可:

flowchart LR A[Content brief] --> B[Draft] B --> C{Ready for review?} C -->|Yes| D[Send to reviewer] C -->|No| B D --> E[Published]

提示:不要把全小写的 end 用作节点 ID 或标签——它是保留字,会导致解析器报错。请改用 End、END 或其他完全不同的词。

连线

连线的类型同样带有含义,请根据要表达的内容选择合适的类型。

语法 | 渲染效果 | 适用场景 —> | 箭头 | 默认的方向性流程 --- | 直线 | 无方向的关联关系 -.-> | 虚线箭头 | 可选、异步或条件路径 ==> | 粗箭头 | 主干或关键路径 —o | 圆端 | 聚合或“零对多”关系 —x | 叉端 | 终止或阻断步骤 <—> | 双向箭头 | 双向关系

提示:如果连线标签以字母 o 或 x 开头,请在前面加一个空格或将其大写。-->|ok| 会被解析成圆端连线——请改用 -->| ok| 或 -->|Ok|。

子图

使用 subgraph 可以把相关节点归入一个带标题的区域。适合展示流程中的各个阶段、按系统或团队分组,或把某个子流程从主流程中隔离出来。

flowchart LR subgraph Intake A[Request received] --> B{Complete?} B -->|No| C[Request more info] end

subgraph Review D[Assign reviewer] --> E{Approved?} E -->|Yes| F[Publish] E -->|No| G[Return to author] end

B -->|Yes| D

子图可以通过其 ID 与外部节点建立连接。子图内部的方向也可以独立于父图表单独设置。

代码片段

编辑器中的片段面板内置了常用模式的现成代码块——当你知道想要的形状但记不清具体语法时,这是很方便的捷径。点击左侧面板的 Code snippets 浏览片段,点击任意片段即可插入编辑器。

使用图表文档面板

编辑时,点击左侧面板的 Diagram documentation,即可在新标签页中打开当前图表类型的完整语法参考——同时不会丢失编辑器中的位置。在处理不太熟悉的图表类型或需要查询某个具体属性时非常有用。

常见问题

图表没有渲染。说明某处存在语法错误。Mermaid 会高亮导致问题的那一行——检查括号是否匹配、箭头是否遗漏、节点 ID 是否一致。你也可以打开 Mermaid AI 面板,点击 Fix with AI,让它自动识别并修复问题。

包含特殊字符的标签渲染异常。请把标签用引号包裹:A["Label with (parentheses) and, commas"]。这适用于逗号、分号以及任何可能被 Mermaid 当作语法解析的字符。

子图连线不生效。请确认你引用的是正确的节点 ID,而不是子图的标签。子图内的节点仍然通过各自的 ID 来引用。

“end”这个词破坏了我的图表。把它大写:End 或 END。小写的 end 是保留字。

接下来做什么?

跳过语法,直接描述你想要的效果 | 用 AI 生成图表 → 点击操作代替手写 | 使用可视化编辑器 → 定义颜色、样式和主题 | 创建自定义样式 →

评论 (0)