Mermaid 语法大全
Mermaid 是一个基于 JavaScript 的图表绘制工具,通过解析类 Markdown 的文本语法,在浏览器中实时渲染为矢量图表。本文档汇总了 Mermaid 所有常用图表类型的语法。
一、基础概念
1.1 基本结构
所有 Mermaid 图表都需要包裹在代码块中,语言标识为 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>
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)"
需要在文件最后添加 Mermaid 组件的相关代码:
Mermaid
<style is:global>
@import url('../styles/mermaid-toolbar.css');
</style>
<script>
import '../scripts/mermaid-toolbar.js';
</script>
<script is:inline>
document.addEventListener('DOMContentLoaded', function() {
var script = document.createElement('script');
script.src = 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js';
script.onload = function() {
mermaid.initialize({
startOnLoad: false,
theme: 'dark',
themeVariables: {
background: '#1a1a2e',
primaryColor: '#4a90d9',
secondaryColor: '#2d2d44',
tertiaryColor: '#1a1a2e',
primaryBorderColor: '#555',
secondaryBorderColor: '#444',
lineColor: '#888',
textColor: '#f6f2e9',
mainBkg: '#2d2d44',
nodeBorder: '#555',
clusterBkg: '#1a1a2e',
clusterBorder: '#333',
titleColor: '#f6f2e9',
edgeLabelBackground: '#2d2d44',
nodeTextColor: '#f6f2e9',
}
});
mermaid.run({ querySelector: '.mermaid' }).then(function() {
if (window.MermaidToolbar) {
window.MermaidToolbar.initToolbars();
}
});
};
document.head.appendChild(script);
});
</script> 1.2 注释
使用 %% 添加注释,注释内容不会被渲染:
Mermaid
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 基础示例
Mermaid
flowchart TD
A[开始] --> B{是否登录}
B -->|是| C[进入主页]
B -->|否| D[跳转登录页]
C --> E[结束]
D --> E
flowchart TD
A[开始] --> B{是否登录}
B -->|是| C[进入主页]
B -->|否| D[跳转登录页]
C --> E[结束]
D --> E
2.5 子图(Subgraph)
使用 subgraph 对节点进行逻辑分组:
Mermaid
flowchart TD
subgraph 用户模块
A[用户注册] --> B[用户登录]
end
subgraph 业务模块
C[浏览商品] --> D[下单支付]
end
B --> C
flowchart TD
subgraph 用户模块
A[用户注册] --> B[用户登录]
end
subgraph 业务模块
C[浏览商品] --> D[下单支付]
end
B --> C
2.6 自定义样式
使用 classDef 定义样式类,再用 class 应用:
Mermaid
flowchart LR
A[开始] --> B[处理]
classDef red fill:#f99,stroke:#333,stroke-width:2px
class A red
flowchart LR
A[开始] --> B[处理]
classDef red fill:#f99,stroke:#333,stroke-width:2px
class A red
三、时序图(Sequence Diagram)
时序图用于展示对象间的消息交互顺序。
3.1 基本语法
Mermaid
sequenceDiagram
participant 用户
participant 服务器
用户->>服务器: 发送请求
服务器-->>用户: 返回响应
sequenceDiagram
participant 用户
participant 服务器
用户->>服务器: 发送请求
服务器-->>用户: 返回响应
3.2 参与者定义
使用 participant 定义参与者,可用 as 取别名:
Mermaid
sequenceDiagram
participant U as 用户
participant S as 服务端
U->>S: 请求数据
sequenceDiagram
participant U as 用户
participant S as 服务端
U->>S: 请求数据
3.3 消息类型
| 类型 | 语法 | 说明 |
|---|---|---|
| 实线箭头 | ->> | 同步消息 |
| 虚线箭头 | -->> | 异步响应 |
| 实线无箭头 | -> | 简单消息 |
| 虚线无箭头 | --> | 简单响应 |
| 带叉箭头 | -x | 异步消息 |
| 带括号箭头 | -) | 异步消息 |
3.4 激活框
使用 + 和 - 标记激活和停用:
Mermaid
sequenceDiagram
A->>+B: 请求
B-->>-A: 响应
sequenceDiagram
A->>+B: 请求
B-->>-A: 响应
3.5 注释
Mermaid
sequenceDiagram
participant A
participant B
Note right of A: 这是注释
Note left of B: 左侧注释
Note over A,B: 跨参与者注释
sequenceDiagram
participant A
participant B
Note right of A: 这是注释
Note left of B: 左侧注释
Note over A,B: 跨参与者注释
3.6 高级结构
循环(loop) :
Mermaid
sequenceDiagram
loop 每天执行
A->>B: 检查状态
end
sequenceDiagram
loop 每天执行
A->>B: 检查状态
end
条件分支(alt/else) :
Mermaid
sequenceDiagram
alt 成功
A->>B: 继续处理
else 失败
A->>B: 重试
end
sequenceDiagram
alt 成功
A->>B: 继续处理
else 失败
A->>B: 重试
end
并行(par) :
Mermaid
sequenceDiagram
par 并行执行
A->>B: 任务1
and
A->>C: 任务2
end
sequenceDiagram
par 并行执行
A->>B: 任务1
and
A->>C: 任务2
end
四、类图(Class Diagram)
类图用于描述系统的静态结构,包括类、属性、方法及其关系。
4.1 基本语法
Mermaid
classDiagram
class Animal {
+String name
-int age
+void eat()
-void sleep()
}
classDiagram
class Animal {
+String name
-int age
+void eat()
-void sleep()
}
4.2 可见性标识
| 符号 | 含义 |
|---|---|
+ | 公有(public) |
- | 私有(private) |
# | 保护(protected) |
~ | 包内(package) |
4.3 关系类型
| 关系 | 语法 | 说明 |
|---|---|---|
| 继承 | `< | --` |
| 实现 | ..|> | 接口实现 |
| 组合 | *-- | 强拥有关系 |
| 聚合 | o-- | 弱拥有关系 |
| 关联 | --> | 普通关联 |
4.4 完整示例
Mermaid
classDiagram
Animal <|-- Dog
Animal <|-- Cat
Animal : +String name
Animal : +void move()
class Dog {
+String breed
+void bark()
}
classDiagram
Animal <|-- Dog
Animal <|-- Cat
Animal : +String name
Animal : +void move()
class Dog {
+String breed
+void bark()
}
五、状态图(State Diagram)
状态图用于描述状态机、生命周期和状态转换。
5.1 基本语法
Mermaid
stateDiagram-v2
[*] --> 待审核
待审核 --> 已通过
待审核 --> 已拒绝
已通过 --> [*]
已拒绝 --> [*]
stateDiagram-v2
[*] --> 待审核
待审核 --> 已通过
待审核 --> 已拒绝
已通过 --> [*]
已拒绝 --> [*]
5.2 带描述的状态
Mermaid
stateDiagram-v2
State1: 第一个状态
State2: 第二个状态
[*] --> State1
State1 --> State2
stateDiagram-v2
State1: 第一个状态
State2: 第二个状态
[*] --> State1
State1 --> State2
5.3 复合状态
Mermaid
stateDiagram-v2
[*] --> 运行中
state 运行中 {
[*] --> 就绪
就绪 --> 执行中
执行中 --> 就绪
}
运行中 --> [*]
stateDiagram-v2
[*] --> 运行中
state 运行中 {
[*] --> 就绪
就绪 --> 执行中
执行中 --> 就绪
}
运行中 --> [*]
5.4 分支(fork/join)
Mermaid
stateDiagram-v2
state fork <<fork>>
[*] --> fork
fork --> 状态A
fork --> 状态B
stateDiagram-v2
state fork <<fork>>
[*] --> fork
fork --> 状态A
fork --> 状态B
六、甘特图(Gantt Chart)
甘特图用于项目进度管理和时间线追踪。
6.1 基本语法
Mermaid
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
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)
饼图用于展示比例和分布。
Mermaid
pie title 编程语言使用比例
"JavaScript" : 45
"Python" : 30
"Java" : 15
"Go" : 10
pie title 编程语言使用比例
"JavaScript" : 45
"Python" : 30
"Java" : 15
"Go" : 10
使用 showData 显示具体数值:
Mermaid
pie showData
title 市场份额
"产品A" : 35.5
"产品B" : 28.3
"产品C" : 20.2
"其他" : 16.0
pie showData
title 市场份额
"产品A" : 35.5
"产品B" : 28.3
"产品C" : 20.2
"其他" : 16.0
八、实体关系图(ER Diagram)
ER 图用于数据库关系建模。
8.1 基数表示
| 语法 | 含义 |
|---|---|
| ` | |
| ` | o` |
}o | 零或多个 |
| `} | ` |
8.2 示例
Mermaid
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
}
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)
用户旅程图描述用户完成任务的具体步骤。
Mermaid
journey
title 购物体验
section 浏览商品
查看商品列表: 5: 用户
搜索商品: 4: 用户
section 下单支付
加入购物车: 4: 用户
填写地址: 3: 用户
支付成功: 5: 用户, 系统
journey
title 购物体验
section 浏览商品
查看商品列表: 5: 用户
搜索商品: 4: 用户
section 下单支付
加入购物车: 4: 用户
填写地址: 3: 用户
支付成功: 5: 用户, 系统
评分范围为 1-5,表示满意度。
十、Git 分支图(GitGraph)
Git 分支图用于可视化版本控制分支和提交历史。
10.1 基本语法
Mermaid
gitGraph
commit
commit
branch develop
checkout develop
commit
commit
checkout main
merge develop
gitGraph
commit
commit
branch develop
checkout develop
commit
commit
checkout main
merge develop
10.2 带标签的提交
Mermaid
gitGraph
commit id: "初始化"
commit id: "添加功能"
branch feature
checkout feature
commit id: "开发新功能"
checkout main
merge feature id: "合并功能"
gitGraph
commit id: "初始化"
commit id: "添加功能"
branch feature
checkout feature
commit id: "开发新功能"
checkout main
merge feature id: "合并功能"
10.3 分支操作
Mermaid
gitGraph
commit
branch dev
checkout dev
commit
branch feature
checkout feature
commit
checkout dev
merge feature
checkout main
merge dev tag: "v1.0.0"
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)
看板图用于任务板和流程阶段管理。
Mermaid
kanban
待办
需求分析
设计评审
进行中
前端开发
已完成
项目初始化
kanban
待办
需求分析
设计评审
进行中
前端开发
已完成
项目初始化
十二、象限图(Quadrant Chart)
象限图用于优先级排序和趋势分析。
Mermaid
quadrantChart
x-axis 低优先级 --> 高优先级
y-axis 低影响 --> 高影响
紧急任务: [0.8, 0.9]
日常事务: [0.3, 0.4]
战略规划: [0.6, 0.7]
琐碎杂事: [0.2, 0.2]
quadrantChart
x-axis 低优先级 --> 高优先级
y-axis 低影响 --> 高影响
紧急任务: [0.8, 0.9]
日常事务: [0.3, 0.4]
战略规划: [0.6, 0.7]
琐碎杂事: [0.2, 0.2]
十三、架构图(Architecture Diagram)
用于云基础设施和服务架构可视化。
Mermaid
architecture-beta
service api(server)[APIService]
service db(database)[Database]
service cache(database)[Cache]
api:R --< L:db
api:R --< L:cache
architecture-beta
service api(server)[APIService]
service db(database)[Database]
service cache(database)[Cache]
api:R --> L:db
api:R --> L:cache
十四、区块图(Block Diagram)
用于模块依赖和网络可视化。
Mermaid
block-beta
columns 3
a["模块A"] b["模块B"] c["模块C"]
a --< b
b --< c
block-beta
columns 3
a["模块A"] b["模块B"] c["模块C"]
a --> b
b --> c
十五、C4 模型图(C4 Diagram)
用于系统架构的 C4 模型可视化。
Mermaid
C4Context
title 系统上下文图
Person(user, "用户", "系统使用者")
System(app, "应用系统", "核心业务系统")
Rel(user, app, "使用", "HTTPS")
C4Context
title 系统上下文图
Person(user, "用户", "系统使用者")
System(app, "应用系统", "核心业务系统")
Rel(user, app, "使用", "HTTPS")
十六、通用技巧
16.1 换行
使用 <br> 实现节点内换行:
Mermaid
flowchart LR
A[第一行
第二行
第三行] --> B[结果] 16.2 特殊字符
如果节点文本包含特殊字符或关键字(如 end),使用引号包裹:
Mermaid
flowchart TD
A["包含特殊字符的文本"]
B["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 | 系统架构 |