第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 生成图表 → 点击操作代替手写 | 使用可视化编辑器 → 定义颜色、样式和主题 | 创建自定义样式 →