Mermaid.js 图表完整指南
学习使用简单的文本语法创建专业图表
什么是 Mermaid.js？
Mermaid 是一款基于 JavaScript 的制图与图表工具，使用受 Markdown 启发的文本定义来动态创建和修改图表。这是一个开源项目，可让你用简单的文本描述生成图表。
无需复杂的绘图工具，只需编写类似代码的语法来描述图表，Mermaid 就会将其渲染为可视化图表。这种方式让图表易于版本控制、更新方便，非常适合文档。
Mermaid 可无缝集成到文档平台、Wiki 和 Markdown 文件中，因此深受开发者和技术写作者的喜爱。
为什么使用 Mermaid.js？
- 版本控制：图表是文本文件，因此可以与代码一起在 Git 中跟踪
- 快速更新：修改几行文本即可，无需重画整个图表
- 一致性：Mermaid 自动处理布局与样式，确保图表一致
- 无需设计工具：不需要 Visio、Lucidchart 等昂贵工具
- 文档即代码：将图表与文档放在同一仓库中
- 跨平台：可在浏览器和 Node.js 中运行，并可与多种平台集成
- 免费开源：无需许可费用，社区活跃
- 多种图表类型：支持流程图、时序图、类图等
支持的图表类型
Mermaid 支持多种图表类型，以满足不同的文档需求：
流程图
用节点和边可视化工作流、流程和决策树。
flowchart TD
A[Start] --> B{Decision}
B -->|Yes| C[Process]
B -->|No| D[Alternative]
C --> E[End]
D --> E使用场景: 流程流转、算法、决策逻辑
时序图
展示不同参与者或系统随时间的交互。
sequenceDiagram
participant User
participant API
participant DB
User->>API: Request data
API->>DB: Query
DB-->>API: Results
API-->>User: Response使用场景: API 交互、系统通信、用户流程
类图
用类、属性和关系建模面向对象系统。
classDiagram
class Animal {
+String name
+int age
+makeSound()
}
class Dog {
+bark()
}
Animal <|-- Dog使用场景: 软件架构、OOP 设计、数据库架构
状态图
表示系统或流程中的状态与转移。
stateDiagram-v2
[*] --> Idle
Idle --> Loading: Start
Loading --> Success: Complete
Loading --> Error: Fail
Success --> [*]
Error --> Idle: Retry使用场景: 状态机、生命周期管理、UI 状态
实体关系图
建模数据库结构及实体之间的关系。
erDiagram
CUSTOMER ||--o{ ORDER : places
ORDER ||--|{ LINE_ITEM : contains
CUSTOMER {
int id
string name
string email
}使用场景: 数据库设计、数据建模、系统架构
甘特图
规划并可视化项目进度和时间线。
gantt
title Project Timeline
dateFormat YYYY-MM-DD
section Phase 1
Design :a1, 2024-01-01, 30d
Development :a2, after a1, 45d使用场景: 项目规划、迭代时间线、路线图
饼图
以可视化方式展示比例数据和百分比。
pie title Distribution
"Category A" : 42
"Category B" : 30
"Category C" : 28使用场景: 调查结果、市场份额、资源分配
Git 图
可视化 Git 分支策略和提交历史。
gitGraph
commit
branch develop
checkout develop
commit
checkout main
merge develop使用场景: Git 工作流文档、分支策略
开始使用 Mermaid
1. 选择图表类型
首先确定最能表达你想展示内容的图表类型。每种图表类型都以特定关键字开头，例如 'flowchart'、'sequenceDiagram' 或 'classDiagram'。
2. 编写文本语法
使用 Mermaid 的简单语法来描述图表。语法直观，几乎像自然语言。例如，'A --> B' 会创建从 A 指向 B 的箭头。
3. 预览图表
使用我们的在线查看器或任何兼容 Mermaid 的工具实时渲染并查看你的图表。根据需要调整，直到满意为止。
4. 导出与分享
将图表导出为 SVG 或 PNG 用于演示，或与团队分享 URL。你也可以直接将 Mermaid 嵌入到 Markdown 文件中。
最佳实践
- 让图表聚焦于单一概念或工作流
- 使用能够描述真实业务逻辑的有意义标签
- 将复杂图表拆分为更小、相互关联的图表
- 使用 %% 添加注释以解释复杂部分
- 在图表中使用一致的命名约定
- 在目标环境中测试图表后再定稿
- 需要时加入方向提示（TD, LR）以控制布局
- 在流程图中使用 subgraph 对相关节点进行分组
- 样式选项适度使用，以保持可读性
- 将图表源文件与代码一起进行版本控制
常见使用场景
软件文档
在代码旁记录系统架构、API 流程和组件交互。
项目规划
使用甘特图进行迭代规划、项目时间线和资源分配。
技术提案
可视化拟议解决方案、系统设计和架构决策。
用户旅程
绘制用户流程、客户体验和交互模式。
数据库设计
建模实体关系、架构结构和数据依赖。
流程文档
记录业务流程、工作流和标准操作流程。
教育材料
为教程和技术课程创建清晰、可版本控制的图表。
API 文档
说明请求/响应流程、认证序列和端点交互。
更多资源
常见问题
关于使用 Mermaid Viewer 和创建图表的常见问题
准备好创建你的第一个图表了吗？
试试我们的免费在线 Mermaid 查看器，几分钟内开始创建专业图表。
打开 Mermaid Viewer