Mermaid 完全指南

欢迎来到Mermaid完全指南！本指南将帮助你从基础到进阶全面掌握Mermaid图表绘制技术。

文档结构

本指南按以下结构组织：

1. 基础图表

2. 数据可视化

3. 项目管理

4. 其他图表

1. Mermaid 简介

1.1 什么是 Mermaid？

• Mermaid 是一个基于 JavaScript 的图表绘制工具，使用文本描述来生成各种图表
• 支持多种图表类型：流程图、序列图、类图、状态图、甘特图、饼图等
• 无需依赖外部绘图工具，可直接嵌入到 Markdown 文档中

1.2 为什么选择 Mermaid？

• 纯文本编辑：使用简单的文本语法描述图表，易于版本控制
• 多种图表支持：满足不同场景的可视化需求
• 跨平台兼容：可在浏览器、编辑器、文档系统中使用
• 开源免费：基于 MIT 许可证
• 丰富的集成：支持 GitHub、GitLab、VS Code、Jupyter Notebook 等

1.3 Mermaid 的应用场景

• 技术文档中的架构图和流程图
• 项目管理中的甘特图和时序图
• 软件设计中的类图和状态图
• 数据分析中的饼图和柱状图
• 团队协作中的决策树和关系图

2. 快速入门

2.1 安装与配置

2.1.1 在浏览器中使用

<script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
<script>
  mermaid.initialize({
    startOnLoad: true,
    theme: 'default'
  });
</script>

2.1.2 在 Markdown 编辑器中使用

• VS Code：安装 Mermaid 扩展
• Typora：原生支持 Mermaid
• Obsidian：内置 Mermaid 支持

2.1.3 在项目中使用

# 使用 npm 安装
npm install mermaid

# 使用 yarn 安装
yarn add mermaid

2.2 第一个 Mermaid 图表

graph TD
  A[你好] --> B[Mermaid]
  B --> C[欢迎学习]
  C --> D[图表绘制]

2.3 基本语法规则

• 使用 graph 关键字定义图表类型
• 节点使用 []、()、{} 等符号定义形状
• 箭头使用 -->、==> 等符号定义
• 使用 ; 分隔多个语句（可选）
• 注释使用 %% 开头

3. 核心图表类型

3.1 流程图 (Flowchart)

3.1.1 基本语法

graph TD
  A[开始] --> B{条件判断}
  B -->|是| C[执行操作1]
  B -->|否| D[执行操作2]
  C --> E[结束]
  D --> E

3.1.2 图表方向

• TD 或 TB：从上到下
• LR：从左到右
• RL：从右到左
• BT：从下到上

3.1.3 节点形状

• [文本]：矩形
• (文本)：圆角矩形
• {文本}：菱形
• >文本]：右向旗帜
• [文本]：左向旗帜
• [(文本)]：圆柱（数据库）
• ((文本))：圆形

3.1.4 连线样式

• -->：实线箭头
• -.->：虚线箭头
• ==>：粗线箭头
• --文本-->：带文本的实线箭头
• -.文本.->：带文本的虚线箭头

3.1.5 子图表

graph TD
  A[开始] --> B[处理]
  B --> C{条件}
  subgraph 子流程
    C -->|是| D[操作1]
    C -->|否| E[操作2]
  end
  D --> F[结束]
  E --> F

3.2 序列图 (Sequence Diagram)

3.2.1 基本语法

sequenceDiagram
  participant 客户端 as Client
  participant 服务器 as Server
  客户端->>服务器: 请求数据
  服务器-->>客户端: 返回响应

3.2.2 消息类型

• ->>：实线箭头（异步）
• -->>：虚线箭头（同步）
• ->x：实线箭头带X（错误）
• --x：虚线箭头带X（错误）

3.2.3 激活状态

sequenceDiagram
  participant A
  participant B
  A->>B: 请求
  activate B
  B-->>A: 响应
  deactivate B

3.2.4 注释与延迟

sequenceDiagram
  participant A
  participant B
  A->>B: 请求
  Note over A,B: 处理中...
  B-->>A: 响应
  Note right of A: 完成

3.3 类图 (Class Diagram)

3.3.1 基本语法

classDiagram
  class Animal {
    +name: string
    +age: int
    +eat(): void
    +sleep(): void
  }

3.3.2 继承关系

classDiagram
  class Animal {
    +name: string
    +eat(): void
  }
  
  class Dog {
    +bark(): void
  }
  
  Animal <|-- Dog

3.3.3 关联关系

• <|--：继承
• *--：组合
• o--：聚合
• -->：关联
• ..>：依赖

3.4 状态图 (State Diagram)

3.4.1 基本语法

stateDiagram-v2
  [*] --> 空闲
  空闲 --> 运行: 开始
  运行 --> 暂停: 暂停
  暂停 --> 运行: 继续
  运行 --> 结束: 完成
  暂停 --> 结束: 终止
  结束 --> [*]

3.4.2 复合状态

stateDiagram-v2
  [*] --> 未登录
  未登录 --> 登录中: 输入凭证
  登录中 --> 已登录: 验证成功
  登录中 --> 未登录: 验证失败
  
  state 已登录 {
    [*] --> 首页
    首页 --> 个人中心
    个人中心 --> 设置
    设置 --> 首页
  }
  
  已登录 --> 未登录: 退出

3.5 甘特图 (Gantt Chart)

3.5.1 基本语法

gantt
  title 项目进度计划
  dateFormat  YYYY-MM-DD
  section 设计
  需求分析          :a1, 2023-01-01, 10d
  系统设计          :after a1, 15d
  section 开发
  前端开发          :2023-01-20, 20d
  后端开发          :2023-01-25, 25d
  section 测试
  单元测试          :2023-02-15, 10d
  集成测试          :after 单元测试, 10d

3.5.2 时间格式

• YYYY-MM-DD：年-月-日
• YYYY-MM-DD HH:mm：带时间
• 相对时间：after a1, 10d

3.6 饼图 (Pie Chart)

3.6.1 基本语法

pie
  title 水果销售比例
  "苹果" : 45
  "香蕉" : 30
  "橙子" : 25

3.6.2 高级配置

• 支持百分比显示
• 可自定义颜色
• 支持图例

4. 进阶功能

4.1 主题定制

4.1.1 内置主题

• default：默认主题
• dark：深色主题
• forest：森林主题
• neutral：中性主题

4.1.2 自定义主题

mermaid.initialize({
  theme: 'base',
  themeVariables: {
    primaryColor: '#BB2528',
    primaryTextColor: '#fff',
    primaryBorderColor: '#7C0A02',
    lineColor: '#F8B229',
    secondaryColor: '#006100',
    tertiaryColor: '#FFF'
  }
});

4.2 交互功能

4.2.1 点击事件

graph TD
  A[点击我] --> B[结果]
  click A "alert('你点击了A')"
  click B "alert('你点击了B')"

4.2.2 链接跳转

graph TD
  A[GitHub] --> B[Mermaid]
  click A "https://github.com" "访问GitHub"
  click B "https://mermaid.js.org" "访问Mermaid官网"

4.3 图表导出

4.3.1 导出为图片

• 使用浏览器右键保存
• 使用 Mermaid CLI：mmdc -i input.mmd -o output.png

4.3.2 导出为 SVG

const svg = mermaid.render('graph', graphDefinition);

4.3.3 导出为 PDF

• 先导出为 SVG，再转换为 PDF
• 使用 Mermaid CLI：mmdc -i input.mmd -o output.pdf

4.4 高级语法

4.4.1 变量与常量

graph LR
  %% 定义常量
  %%{init: { "flowchart": { "curve": "monotoneX" } } }%%
  A --> B
  B --> C

4.4.2 条件渲染

graph TD
  A --> B
  %%{ if: ${condition} }%%
  B --> C
  %%{ endif }%%
  B --> D

4.4.3 循环结构

graph TD
  A --> B{条件}
  B -->|是| C[执行]
  C --> B
  B -->|否| D[结束]

5. 最佳实践

5.1 图表设计原则

• 简洁明了：避免过于复杂的图表
• 层次分明：使用子图表组织复杂逻辑
• 颜色一致：遵循统一的配色方案
• 标签清晰：使用简洁易懂的标签
• 尺寸适中：确保图表在各种设备上都能清晰显示

5.2 性能优化

• 避免绘制包含数千个节点的大型图表
• 使用子图表和模块分割复杂图表
• 合理使用动画效果
• 考虑使用异步加载

5.3 版本兼容

• 指定 Mermaid 版本以确保兼容性
• 测试在不同环境中的显示效果
• 关注官方更新和废弃特性

6. 集成与扩展

6.1 与 Markdown 集成

• GitHub/GitLab README 文件
• Jekyll/Hugo 静态网站
• VuePress/Docusaurus 文档系统

6.2 与开发工具集成

• VS Code：Mermaid 扩展
• IntelliJ IDEA：Mermaid 支持插件
• Visual Studio：Mermaid 编辑器扩展

6.3 与框架集成

• React：react-mermaid2
• Vue：vue-mermaid-string
• Angular：ngx-mermaid

6.4 使用 Mermaid CLI

# 安装 CLI
npm install -g @mermaid-js/mermaid-cli

# 转换为图片
mmdc -i input.mmd -o output.png

# 转换为 PDF
mmdc -i input.mmd -o output.pdf

# 转换为 SVG
mmdc -i input.mmd -o output.svg

7. 常见问题与解决方案

7.1 图表不显示

• 检查 Mermaid 库是否正确加载
• 检查语法是否正确
• 查看浏览器控制台是否有错误

7.2 图表样式问题

• 检查主题设置
• 检查自定义 CSS 是否冲突
• 尝试使用不同的主题

7.3 复杂图表性能问题

• 分割为多个小图表
• 减少节点数量
• 禁用动画效果

7.4 兼容性问题

• 指定具体的 Mermaid 版本
• 检查浏览器兼容性
• 考虑使用降级方案

8. 资源与学习材料

8.1 官方资源

• Mermaid 官方文档
• Mermaid GitHub 仓库
• Mermaid 示例库

8.2 教程与博客

• Mermaid 入门指南
• Mermaid 高级用法
• Mermaid 集成教程

8.3 社区资源

• Stack Overflow 标签：mermaid.js
• Reddit 社区：/r/mermaidjs
• Discord 服务器：Mermaid 社区

8.4 工具与编辑器

• Mermaid Live Editor
• Mermaid Chart
• Draw.io (支持 Mermaid 导入导出)

9. 实践项目

9.1 项目 1：绘制系统架构图

• 需求：绘制一个简单的 Web 应用架构图
• 涉及：流程图、子图表、自定义样式

9.2 项目 2：编写用户旅程图

• 需求：描述用户注册流程
• 涉及：序列图、激活状态、注释

9.3 项目 3：创建项目计划

• 需求：制定一个软件开发项目计划
• 涉及：甘特图、时间线、任务依赖

9.4 项目 4：设计类图

• 需求：为一个简单的待办事项应用设计类图
• 涉及：类图、继承、关联关系

10. 总结与下一步

10.1 学习总结

• 掌握了 Mermaid 的基本语法和核心图表类型
• 了解了进阶功能和最佳实践
• 学会了与其他工具和框架的集成

10.2 下一步学习建议

• 深入学习特定图表类型的高级用法
• 探索 Mermaid 的 API 和扩展机制
• 参与 Mermaid 社区贡献
• 在实际项目中应用 Mermaid

注意：本学习大纲基于 Mermaid 10.x 版本，随着版本更新，部分功能可能会有所变化。建议参考官方文档获取最新信息。