Mermaid 语法大全
Mermaid 是一个基于 JavaScript 的图表绘制工具,通过解析类 Markdown 的文本语法,在浏览器中实时渲染为矢量图表。本文档汇总了 Mermaid 所有常用图表类型的语法。
一、基础概念
1.1 基本结构
所有 Mermaid 图表都需要包裹在代码块中,语言标识为 mermaid:
<div class="mermaid-wrapper"><div class="mermaid">
gitGraph LR:
checkout main
commit id: "Downtown" tag: "Line 1"
commit id: "Central Park"
branch "Line 2 (Blue)"
commit id: "East Station"
commit id: "Science Museum"
checkout main
commit id: "City Hall (Transfer)" tag: "🔀 Line 1 & 2"
merge "Line 2 (Blue)"
commit id: "Financial District"
branch "Line 3 (Green)"
commit id: "West Village"
commit id: "Airport Terminal"
checkout main
commit id: "Sports Arena"
merge "Line 3 (Green)"
commit id: "Northern Gateway"
branch "Line 4 (Orange)"
commit id: "University"
checkout main
commit id: "Central Station" tag: "Terminal"
merge "Line 4 (Orange)"
</div></div> 需要在文件最后添加 Mermaid 组件的相关代码:
<div class="mermaid-wrapper">
<div class="mermaid">
graph TD
A --> B
</div>
</div> Mermaid 渲染已全站启用(BaseLayout 全局加载 mermaid-init.js):任何页面书写上述结构即可,无需任何初始化脚本 — 首次加载与客户端导航进入页面时都会自动渲染并挂载工具栏。如需自定义主题,可在页面中预先设置全局配置:
<script is:inline>
window.MERMAID_CONFIG = { theme: 'forest' };
</script> 1.2 注释
使用 %% 添加注释,注释内容不会被渲染:
graph TD
A[开始] --> B{判断} %% 这是一条注释
B -->|是| C[执行] 二、流程图(Flowchart)
流程图是最常用的图表类型,用于描述流程、算法和决策逻辑。
2.1 方向设置
| 方向 | 语法 | 说明 |
|---|---|---|
| 从上到下 | TD 或 TB | 最常用 |
| 从左到右 | LR | 适合步骤较多的流程 |
| 从右到左 | RL | 较少用 |
| 从下到上 | BT | 较少用 |
2.2 节点形状
| 形状 | 语法 | 说明 |
|---|---|---|
| 矩形 | A[文本] | 普通步骤 |
| 圆角矩形 | A(文本) | 开始/结束 |
| 圆形 | A((文本)) | 开始/结束 |
| 菱形 | A{文本} | 判断条件 |
| 六边形 | A{{文本}} | 准备/预备 |
| 平行四边形 | A[/文本/] | 输入/输出 |
| 圆柱形 | A[(文本)] | 数据库 |
2.3 连线类型
| 连线 | 语法 | 说明 |
|---|---|---|
| 带箭头 | --> | 实线箭头 |
| 带文字 | `--> | 文字 |
| 无箭头 | --- | 实线无箭头 |
| 粗箭头 | ==> | 粗线箭头 |
| 虚线箭头 | -.-> | 点线箭头 |
| 带文字虚线 | `-.-> | 文字 |
2.4 基础示例
flowchart TD
A[开始] --> B{是否登录}
B -->|是| C[进入主页]
B -->|否| D[跳转登录页]
C --> E[结束]
D --> E 2.5 子图(Subgraph)
使用 subgraph 对节点进行逻辑分组:
flowchart TD
subgraph 用户模块
A[用户注册] --> B[用户登录]
end
subgraph 业务模块
C[浏览商品] --> D[下单支付]
end
B --> C 2.6 自定义样式
使用 classDef 定义样式类,再用 class 应用:
flowchart LR
A[开始] --> B[处理]
classDef red fill:#f99,stroke:#333,stroke-width:2px
class A red 三、时序图(Sequence Diagram)
时序图用于展示对象间的消息交互顺序。
3.1 基本语法
sequenceDiagram
participant 用户
participant 服务器
用户->>服务器: 发送请求
服务器-->>用户: 返回响应 3.2 参与者定义
使用 participant 定义参与者,可用 as 取别名:
sequenceDiagram
participant U as 用户
participant S as 服务端
U->>S: 请求数据 3.3 消息类型
| 类型 | 语法 | 说明 |
|---|---|---|
| 实线箭头 | ->> | 同步消息 |
| 虚线箭头 | -->> | 异步响应 |
| 实线无箭头 | -> | 简单消息 |
| 虚线无箭头 | --> | 简单响应 |
| 带叉箭头 | -x | 异步消息 |
| 带括号箭头 | -) | 异步消息 |
3.4 激活框
使用 + 和 - 标记激活和停用:
sequenceDiagram
A->>+B: 请求
B-->>-A: 响应 3.5 注释
sequenceDiagram
participant A
participant B
Note right of A: 这是注释
Note left of B: 左侧注释
Note over A,B: 跨参与者注释 3.6 高级结构
循环(loop) :
sequenceDiagram
loop 每天执行
A->>B: 检查状态
end 条件分支(alt/else) :
sequenceDiagram
alt 成功
A->>B: 继续处理
else 失败
A->>B: 重试
end 并行(par) :
sequenceDiagram
par 并行执行
A->>B: 任务1
and
A->>C: 任务2
end 四、类图(Class Diagram)
类图用于描述系统的静态结构,包括类、属性、方法及其关系。
4.1 基本语法
classDiagram
class Animal {
+String name
-int age
+void eat()
-void sleep()
} 4.2 可见性标识
| 符号 | 含义 |
|---|---|
+ | 公有(public) |
- | 私有(private) |
# | 保护(protected) |
~ | 包内(package) |
4.3 关系类型
| 关系 | 语法 | 说明 |
|---|---|---|
| 继承 | `< | --` |
| 实现 | ..|> | 接口实现 |
| 组合 | *-- | 强拥有关系 |
| 聚合 | o-- | 弱拥有关系 |
| 关联 | --> | 普通关联 |
4.4 完整示例
classDiagram
Animal <|-- Dog
Animal <|-- Cat
Animal : +String name
Animal : +void move()
class Dog {
+String breed
+void bark()
} 五、状态图(State Diagram)
状态图用于描述状态机、生命周期和状态转换。
5.1 基本语法
stateDiagram-v2
[*] --> 待审核
待审核 --> 已通过
待审核 --> 已拒绝
已通过 --> [*]
已拒绝 --> [*] 5.2 带描述的状态
stateDiagram-v2
State1: 第一个状态
State2: 第二个状态
[*] --> State1
State1 --> State2 5.3 复合状态
stateDiagram-v2
[*] --> 运行中
state 运行中 {
[*] --> 就绪
就绪 --> 执行中
执行中 --> 就绪
}
运行中 --> [*] 5.4 分支(fork/join)
stateDiagram-v2
state fork <<fork>>
[*] --> fork
fork --> 状态A
fork --> 状态B 六、甘特图(Gantt Chart)
甘特图用于项目进度管理和时间线追踪。
6.1 基本语法
gantt
title 项目开发计划
dateFormat YYYY-MM-DD
section 需求阶段
需求分析 :done, a1, 2024-01-01, 7d
需求评审 :active, a2, after a1, 3d
section 开发阶段
前端开发 :a3, after a2, 14d
后端开发 :a4, after a2, 21d
section 测试阶段
集成测试 :a5, after a3, 7d 6.2 任务状态
| 状态 | 说明 |
|---|---|
done | 已完成 |
active | 进行中 |
crit | 关键路径 |
milestone | 里程碑 |
七、饼图(Pie Chart)
饼图用于展示比例和分布。
pie title 编程语言使用比例
"JavaScript" : 45
"Python" : 30
"Java" : 15
"Go" : 10 使用 showData 显示具体数值:
pie showData
title 市场份额
"产品A" : 35.5
"产品B" : 28.3
"产品C" : 20.2
"其他" : 16.0 八、实体关系图(ER Diagram)
ER 图用于数据库关系建模。
8.1 基数表示
| 语法 | 含义 |
|---|---|
| ` | |
| ` | o` |
}o | 零或多个 |
| `} | ` |
8.2 示例
erDiagram
CUSTOMER ||--o{ ORDER : 下单
ORDER ||--|{ LINE_ITEM : 包含
PRODUCT ||--o{ LINE_ITEM : 属于
CUSTOMER {
int id PK
string name
string email
}
ORDER {
int id PK
int customer_id FK
date created_at
} 九、用户旅程图(User Journey)
用户旅程图描述用户完成任务的具体步骤。
journey
title 购物体验
section 浏览商品
查看商品列表: 5: 用户
搜索商品: 4: 用户
section 下单支付
加入购物车: 4: 用户
填写地址: 3: 用户
支付成功: 5: 用户, 系统 评分范围为 1-5,表示满意度。
十、Git 分支图(GitGraph)
Git 分支图用于可视化版本控制分支和提交历史。
10.1 基本语法
gitGraph
commit
commit
branch develop
checkout develop
commit
commit
checkout main
merge develop 10.2 带标签的提交
gitGraph
commit id: "初始化"
commit id: "添加功能"
branch feature
checkout feature
commit id: "开发新功能"
checkout main
merge feature id: "合并功能" 10.3 分支操作
gitGraph
commit
branch dev
checkout dev
commit
branch feature
checkout feature
commit
checkout dev
merge feature
checkout main
merge dev tag: "v1.0.0" 十一、看板图(Kanban)
看板图用于任务板和流程阶段管理。
kanban
待办
需求分析
设计评审
进行中
前端开发
已完成
项目初始化 十二、象限图(Quadrant Chart)
象限图用于优先级排序和趋势分析。
quadrantChart
x-axis 低优先级 --> 高优先级
y-axis 低影响 --> 高影响
紧急任务: [0.8, 0.9]
日常事务: [0.3, 0.4]
战略规划: [0.6, 0.7]
琐碎杂事: [0.2, 0.2] 十三、架构图(Architecture Diagram)
用于云基础设施和服务架构可视化。
architecture-beta
service api(server)[APIService]
service db(database)[Database]
service cache(database)[Cache]
api:R --< L:db
api:R --< L:cache 十四、区块图(Block Diagram)
用于模块依赖和网络可视化。
block-beta
columns 3
a["模块A"] b["模块B"] c["模块C"]
a --< b
b --< c 十五、C4 模型图(C4 Diagram)
用于系统架构的 C4 模型可视化。
C4Context
title 系统上下文图
Person(user, "用户", "系统使用者")
System(app, "应用系统", "核心业务系统")
Rel(user, app, "使用", "HTTPS") 十六、通用技巧
16.1 换行
使用 <br> 实现节点内换行:
flowchart LR
A[第一行
第二行
第三行] --> B[结果] 16.2 特殊字符
如果节点文本包含特殊字符或关键字(如 end),使用引号包裹:
flowchart TD
A["包含特殊字符的文本"]
B["end 关键字"] 16.3 在线调试
推荐使用 Mermaid Live Editor 进行在线调试和预览。
附录:图表类型速查表
| 图表类型 | 关键字 | 用途 |
|---|---|---|
| 流程图 | flowchart / graph | 流程逻辑、决策树 |
| 时序图 | sequenceDiagram | 消息交互顺序 |
| 类图 | classDiagram | 面向对象结构 |
| 状态图 | stateDiagram-v2 | 状态机、生命周期 |
| 甘特图 | gantt | 项目进度管理 |
| 饼图 | pie | 比例分布 |
| ER 图 | erDiagram | 数据库关系 |
| 用户旅程图 | journey | 用户体验流程 |
| Git 分支图 | gitGraph | 版本控制可视化 |
| 看板图 | kanban | 任务管理 |
| 象限图 | quadrantChart | 优先级分析 |
| 架构图 | architecture-beta | 云基础设施 |
| 区块图 | block-beta | 模块依赖 |
| C4 模型图 | C4Context | 系统架构 |