00317 Mermaid语法的入门教程

前言

Mermaid语法的入门教程。

官方文档：https://mermaid.js.org

在线调试：https://mermaid.live

Operating System: Ubuntu 22.04.4 LTS

参考文档

入门教程

Mermaid 简介

Mermaid 是一种基于文本的图表生成工具，支持流程图、序列图、甘特图、类图等。通过简单的语法即可生成可视化图表，兼容 Markdown 和多种文档工具。

基础语法规则

1. 声明图表类型：首行用 graph/sequenceDiagram 等关键词声明图表类型
2. 缩进与换行：一般用 2 空格或 4 空格缩进表示层级关系
3. 特殊符号：使用 -->、---、==> 等符号表示连接线

常用图表语法

流程图（Flowchart）

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

语法说明：

• graph TD 声明从上到下的流程图
• A[文本] 方框节点
• B{文本} 菱形条件节点
• --> 箭头连接线
• |文本| 在连接线上添加说明

序列图（Sequence Diagram）

sequenceDiagram
  Alice->>Bob: 你好吗？
  Bob-->>Alice: 我很好！
  Note right of Bob: 这是备注

语法说明：

• ->> 实线箭头
• -->> 虚线箭头
• Note [位置] of [对象]: 文本 添加备注

甘特图（Gantt Chart）

gantt
  title 项目计划
  dateFormat YYYY-MM-DD
  section 阶段A
  任务1 :a1, 2023-08-01, 7d
  任务2 :after a1, 3d
  section 阶段B
  任务3 :2023-08-11, 5d

语法说明：

• dateFormat 定义日期格式
• section 划分阶段
• :id, start, duration 定义任务

类图（Class Diagram）

classDiagram
  Animal <|-- Duck
  Animal <|-- Fish
  Animal: +String name
  Animal: +eat()
  class Duck{
    +swim()
  }

语法说明：

• <|-- 表示继承关系
• + 表示 public 属性/方法
• - 表示 private 属性/方法

实用技巧

1. 自定义样式：

graph LR
  A:::special --> B
  classDef special fill:#f96,stroke:#333

2. 注释：用 %% 添加注释

graph LR
  %% 这是一条注释
  A --> B

3. 多行文本：使用 """

graph LR
  A["""第一行
  第二行"""]

学习建议

1. 使用在线编辑器实时预览（如 Mermaid Live Editor）
2. 从简单图表开始，逐步增加复杂度
3. 参考官方文档：https://mermaid.js.org/

复杂流程图进阶

子图（Subgraphs）

用于将流程图中的部分节点分组：

graph TD
  A[开始] --> B{决策}
  subgraph 模块1 [处理模块]
    B --> C[操作A]
    C --> D[操作B]
  end
  D --> E[结束]

方向控制

通过 direction 控制子图方向：

graph LR
  subgraph 垂直排列
    direction TB
    A --> B
  end
  subgraph 水平排列
    direction LR
    C --> D
  end

自定义样式与主题

高级样式定义

通过 CSS 类实现精细控制：

graph LR
  A:::redBox --> B:::blueBox
  classDef redBox fill:#ff9999,stroke:#ff3333,stroke-width:2px
  classDef blueBox fill:#99ccff,stroke:#0066cc,radius:10px

交互性与动态行为

添加点击事件

graph LR
  A["点我跳转"] --> B
  click A "https://example.com" _blank

提示框（Tooltip）

graph LR
  A["悬停查看提示"] --> B
  click A call tooltip("这是提示内容")

复杂序列图技巧

并行处理

使用 par 块表示并行操作：

sequenceDiagram
  par 并行任务
    Alice ->> Bob: 消息1
  and
    Alice ->> Charlie: 消息2
  end

循环与条件判断

sequenceDiagram
  loop 每天
    Alice->>Bob: 发送日报
  end
  alt 数据正常
    Bob-->>Alice: 确认接收
  else 数据异常
    Bob-->>Alice: 请求重发
  end

高级甘特图配置

任务依赖关系

gantt
  dateFormat YYYY-MM-DD
  task1 :a, 2023-08-01, 7d
  task2 :b, after a, 3d
  task3 :c, after b, 5d

里程碑标记

gantt
  milestone :milestone1, 2023-08-10, 0d

类图高级关系

组合与聚合

classDiagram
  class 汽车 {
    +引擎 engine
  }
  汽车 *-- 引擎 : 组合
  汽车 o-- 轮胎 : 聚合

接口实现

classDiagram
  class 飞行器 {
    <<interface>>
    +fly()
  }
  飞机 ..|> 飞行器 : 实现

状态图（State Diagram）

stateDiagram-v2
  [*] --> 待机
  待机 --> 运行中: 启动命令
  运行中 --> 暂停: 暂停命令
  暂停 --> 运行中: 恢复命令
  运行中 --> 待机: 停止命令

用户旅程图（User Journey）

journey
  title 购物流程
  section 浏览商品
    用户: 5: 查看商品详情
    系统: 3: 加载图片
  section 下单支付
    用户: 2: 填写地址
    系统: 4: 生成订单

错误处理与调试

1. 常见错误：

   • 缺少结束符号（如 end）
   • 缩进不一致
   • 特殊符号未转义（如引号需用 #quot;）

2. 调试工具：

   • 使用 Mermaid Live Editor 实时验证
   • 开启开发者模式查看错误日志

---

进阶实践建议

1. 代码复用：

   • 将常用图形定义为代码片段
   • 使用 %% 注释标记重要部分

2. 性能优化：

   • 避免超深层级嵌套
   • 复杂图表拆分为多个子图

3. 文档集成：

   • 在 VS Code 安装 Mermaid 插件（Markdown Preview Enhanced）
   • 与 GitBook/Obsidian 等工具结合使用

调用 Mermaid API（需要网络）

使用官方提供的在线 API 生成图片

import requests
import base64

def save_mermaid_api(code, output="output.png"):
    graphbytes = code.encode("utf8")
    base64_bytes = base64.b64encode(graphbytes)
    base64_str = base64_bytes.decode("ascii")
    
    url = f"https://mermaid.ink/img/{base64_str}"
    
    response = requests.get(url)
    if response.status_code == 200:
        with open(output, "wb") as f:
            f.write(response.content)
        print("图片已保存")
    else:
        print("生成失败")

# 使用示例
save_mermaid_api("""
pie title Pets
  "Dogs" : 50
  "Cats" : 30
  "Birds" : 20
""", "pie_chart.png")

结语

第三百一十七篇博文写完，开心！！！！

今天，也是充满希望的一天。