Mermaid 图表语法与选择参考

Mermaid 用文本描述图，再由渲染器生成可视图形。每个代码块都应先声明图类型；流程图、XY 图和时序图使用不同语法，不能把一种图的字段套给另一种。

先选择图类型

要表达的关系	图类型
步骤与分支	flowchart
对象按时间交互	sequenceDiagram
类、继承与成员	classDiagram
状态和事件	stateDiagram-v2
数据实体和基数	erDiagram
计划与持续时间	gantt
比例、变化或分类	pie、xychart-beta、quadrantChart
层级、体验与提交历史	mindmap、journey、gitGraph

本文示例面向 Mermaid 11；接收方应用可能内置较旧版本。扩展节点形状需要 11.3.0+。展示前应检查网页是否实际生成图形，不能只检查 Markdown 围栏。

流程图：节点、方向与连线

flowchart LR
    A[开始] --> B{检查通过?}
    B -->|是| C[执行任务]
    B -->|否| D[修正输入]
    D -.-> B
    C ==> E[结束]

LR 左至右，TD/TB 上至下，RL 右至左，BT 下至上。普通箭头 -->、虚线 -.->、粗线 ==> 表达的是绘图样式，语义应由图例定义。~~~ 是不显示线条的布局约束。

flowchart TD
    A@{ shape: diam, label: "决定" }
    B@{ shape: rect, label: "矩形" }
    C@{ shape: cyl, label: "数据存储" }
    D@{ shape: notch-rect, label: "卡片" }
    A --> B --> C --> D

扩展形状语法仍需 flowchart 声明；shape: 后留空格有助于清晰书写，但原片段缺少图类型才是更根本的问题。Unicode 标签可放在引号内，Mermaid Markdown string 用引号内的反引号包围文字。普通菱形 A{问题} 对旧版本更容易兼容。

原稿还用透明的空节点调整分支位置。通常优先使用边标签；确需布局辅助时可定义 classDef empty fill:none,stroke:none 并将辅助节点标为 :::empty，但不要让辅助节点冒充真实业务步骤。

时序、类、状态和实体

sequenceDiagram
    participant U as 用户
    participant S as 服务
    U->>S: 提交请求
    S-->>U: 返回结果

classDiagram
    Animal <|-- Dog
    class Animal {
        +String name
        +eat()
    }
    class Dog {
        +bark()
    }

空心三角端指向父类，所以 Animal <|-- Dog 表示 Dog 继承 Animal；原文反向书写会改变含义。更完整的关系符号见 类图笔记，交互语义见 时序图笔记。

stateDiagram-v2
    [*] --> Idle
    Idle --> Running: start
    Running --> Idle: finish
    Idle --> [*]

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ ORDER_ITEM : contains
    PRODUCT ||--o{ ORDER_ITEM : appears_in

ER 图中的基数应按业务约束填写；此示例表示每个订单条目关联一个产品，而一个产品可以出现在多个条目中。

计划、比例与旅程

gantt
    title 示例计划
    dateFormat YYYY-MM-DD
    section 开发
    设计 :done, design, 2026-10-01, 2d
    实现 :active, impl, after design, 3d
    验证 :test, after impl, 2d

pie title 示例组成
    "类型A" : 30
    "类型B" : 20
    "类型C" : 50

journey
    title 发布体验
    section 准备
      撰写: 4: 作者
      校对: 3: 作者
    section 发布
      检查显示: 5: 作者

journey 数值是体验评分，不是工期。下面的 mindmap 用缩进表示层级，不必用普通 flowchart 模拟：

mindmap
  root((笔记))
    概念
    方法
      示例
      验证

XY 与四象限

---
config:
  themeVariables:
    xyChart:
      plotColorPalette: "#C97332, #174C73"
---
xychart-beta
    title "示例趋势"
    x-axis "时间" [1, 2, 3, 4, 5]
    y-axis "数值" 0 --> 6
    bar [5, 4, 3, 2, 1]
    line [1, 2, 3, 4, 5]

XY 图使用 x-axis、y-axis、line 和 bar；原稿的 xLabel、series/name/data 结构不是此语法。数据数量应与横轴对应。

quadrantChart
    title 工作项分类
    x-axis 低收益 --> 高收益
    y-axis 低投入 --> 高投入
    quadrant-1 评估资源
    quadrant-2 暂缓
    quadrant-3 小步改进
    quadrant-4 优先推进
    项目A: [0.8, 0.2]
    项目B: [0.3, 0.7]

四象限的点坐标在 0 到 1 范围内；原稿按 quadrants/items 写嵌套对象并给出 2、3 等坐标并不适用。选择坐标前应定义两个评价维度，图形本身不会证明评分客观。

Git 图与扩展

gitGraph
    commit id: "base"
    branch feature
    checkout feature
    commit id: "change"
    checkout main
    commit id: "main update"
    merge feature

图中操作只生成示意图，不会修改真实 Git 仓库。ZenUML 是另一种表达交互的扩展能力，不能把 Mermaid 时序图箭头直接视为 ZenUML 语法；需要支持该扩展的集成与对应文法，本文不把未验证扩展代码交给网页执行。

参考：Mermaid 图类型目录、流程图、类图、XY 图、四象限图。