Mermaid 语法概要

概述

Mermaid 是一种基于文本的图表和图形绘制工具，允许用户使用简单的标记语言来创建复杂的图表。它广泛应用于文档、博客、维基等场景，帮助用户以可视化的方式展示信息和数据

在 Markdown 中，Mermaid 图表通过代码块的方式嵌入，语言标识为 mermaid。另外，不是所有 Markdown 编辑器都支持 Mermaid 渲染，使用某个 Markdown 编辑器之前，可以先查一下是否支持 Mermaid，如果不支持，大多应该都是通过安装插件实现的

在 Markdown 中使用 Mermaid，可以通过代码块的方式嵌入 Mermaid 语法，生成各种类型的图表，这样更便于文档的编写、维护、传播，Everything is Code!

基本语法结构

Mermaid 的基本语法结构非常简单，主要包含以下几个要素

图表类型声明

每个 Mermaid 图表都以图表类型开头，如：

graph - 流程图
sequenceDiagram - 时序图
erDiagram - 数据库ER图
gantt - 甘特图
pie - 饼图
gitGraph - Git 图

方向控制

对于流程图，可以指定方向：

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

节点定义

节点是图表中的基本元素，可以用方括号、圆括号等定义：

Mermaid 语法
图形预览

graph LR
    A[方形]
    B(圆边矩形)
    C{菱形}
    D((圆形))
    E>非对称节点]
    F([体育场形])
    G[[子程序形]]
    H[(圆柱形)]

连接线

连接线用于连接节点，支持多种样式：

Mermaid 语法
图形预览

graph TD
    A[开始] --> B[正常流程]
    A -.-> C[可选流程]
    A ==> D[重要流程]
    A --|标签|--> E[带标签连接]

连接线类型说明：

--> 实线箭头：正常流程
-.-> 虚线箭头：可选或异常流程
==> 粗箭头：重要流程
--|标签|--> 带标签的连接

常用图表示例

Mermaid 支持多种类型的图表，以下是一些常用的图表类型及其基本语法

流程图 (Flowchart)

流程图是最常用的图表类型，用于展示流程、决策和步骤

语法说明

流程图的语法结构如下：

图表声明：使用 graph 关键字开始，指定方向（TD/TB/BT/LR/RL）
节点定义：定义节点ID和形状
- A[矩形] - 矩形节点
- B(圆角矩形) - 圆角矩形
- C{菱形} - 菱形节点
- D((圆形)) - 圆形节点
连接线：使用箭头连接节点
- --> 实线箭头
- -.-> 虚线箭头
- ==> 粗箭头
- --|标签|--> 带标签的连接

基础流程图

Mermaid 语法
图形预览

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

不同节点形状

Mermaid 语法
图形预览

graph LR
    A[矩形] --> B(圆角矩形)
    B --> C{菱形}
    C --> D((圆形))
    D --> E>非对称]
    E --> F[矩形]

带标签的连接线

Mermaid 语法
图形预览

graph TD
    A[开始] -->|成功| B[下一步]
    A -->|失败| C[错误处理]
    B -->|完成| D[结束]
    C -->|重试| A

时序图 (Sequence Diagram)

时序图用于展示对象之间的交互顺序，特别适合描述系统间的调用关系

语法说明

时序图的语法结构如下：

图表声明：使用 sequenceDiagram 关键字开始
参与者定义：使用 participant 关键字定义参与者
- participant A - 定义参与者A
- participant B as 别名 - 定义参与者B并设置别名
交互定义：定义参与者之间的交互
- A->>B: 消息 - 实线箭头消息
- A-->>B: 返回消息 - 虚线箭头返回
- A->>+B: 激活 - 激活参与者
- A-->>-B: 取消激活 - 取消激活
注释：使用 Note over A,B: 注释内容 添加注释

基础时序图

Mermaid 语法
图形预览

sequenceDiagram
    participant 用户
    participant 前端
    participant 后端
    participant 数据库
    
    用户->>前端: 登录请求
    前端->>后端: 验证用户信息
    后端->>数据库: 查询用户数据
    数据库-->>后端: 返回用户信息
    后端-->>前端: 返回登录结果
    前端-->>用户: 显示登录状态

带激活和注释的时序图

Mermaid 语法
图形预览

sequenceDiagram
    participant A as 客户端
    participant B as 服务器
    
    A->>+B: 发送请求
    Note over B: 处理请求
    B-->>-A: 返回响应
    Note over A,B: 请求完成

数据库ER图 (Entity Relationship Diagram)

数据库 ER 图用于展示数据库表之间的关系，包括一对一、一对多、多对多等关系

语法说明

数据库 ER 图的语法结构如下：

图表声明：使用 erDiagram 关键字开始
实体定义：定义实体（表）及其字段
- 实体名 { : 开始实体定义
- 字段类型字段名约束 "注释" : 定义字段
- } : 结束实体定义
- p[Person]: 定义实体并设置别名
**关系定义 **：定义实体之间的关系
- 实体A ||--o{ 实体B : "关系描述" : 一对多关系
- 实体A }|--|| 实体B : "关系描述" : 一对一关系
- 通过中间表实现多对多关系
- 关系连接符说明
  - 一对一: ||--||
  - 一对多: ||--o{
  - 多对一: }o--||
  - 多对多（不使用中间表）: }o--o{
- 键类型
  - 主键: PK
  - 外键: FK
  - 唯一键: UK
- 连接线样式
  - 实线: --，表示识别性关系，用于表示强实体
  - 虚线: ..，表示非识别性关系，用于表示弱实体
方向
- 默认为从上到下，从左到右
- 可以在开头通过 direction 关键字改变方向，可选值
  - TB : 从上到下
  - LR : 从左到右
  - BT : 从下到上
  - RL : 从右到左

基础ER图

Mermaid 语法
图形预览

erDiagram
    school_class {
        int id PK "班级ID，主键"
        varchar(50) name "班级名称"
        varchar(20) grade "年级"
        datetime created_at "创建时间"
    }
    
    teacher {
        int id PK "老师ID，主键"
        varchar(50) name "姓名"
        varchar(20) subject "科目"
        datetime created_at "创建时间"
    }
    
    student {
        int id PK "学生ID，主键"
        varchar(50) name "姓名"
        int age "年龄"
        int class_id FK "班级ID，外键"
        datetime created_at "创建时间"
    }
    
    school_class ||--o{ student : 班级包含学生
    teacher ||--o{ school_class : 老师管理班级

复杂关系ER图

Mermaid 语法
图形预览

erDiagram
    school_class {
        int id PK "班级ID，主键"
        varchar(50) name "班级名称"
        varchar(20) grade "年级"
        int teacher_id FK "班主任ID，外键"
        datetime created_at "创建时间"
    }
    
    teacher {
        int id PK "老师ID，主键"
        varchar(50) name "姓名"
        varchar(20) subject "科目"
        varchar(20) title "职称"
        datetime created_at "创建时间"
    }
    
    student {
        int id PK "学生ID，主键"
        varchar(50) name "姓名"
        int age "年龄"
        int class_id FK "班级ID，外键"
        datetime created_at "创建时间"
    }
    
    course {
        int id PK "课程ID，主键"
        varchar(50) name "课程名称"
        int credits "学分"
        varchar(255) description "课程描述"
        datetime created_at "创建时间"
    }
    
    enrollment {
        int id PK "选课ID，主键"
        int student_id FK "学生ID，外键"
        int course_id FK "课程ID，外键"
        int score "成绩"
        datetime created_at "选课时间"
    }
    
    school_class }|--|| teacher : 班级有班主任
    school_class ||--o{ student : 班级包含学生
    student ||--o{ enrollment : 学生选择课程
    course ||--o{ enrollment : 课程被学生选择

连接线样式举例

识别或非识别关系用于区分一个实体没有另一个实体是否能独立存在，举例：

一家为人们驾驶汽车提供保险的公司可能需要在 NAMED-DRIVER 上存储数据。在建模时，我们可能首先观察到 CAR 可以由许多 PERSON 实例驱动，而 PERSON 可以驱动许多 CAR - 两个实体都可以独立存在，因此这是一种非识别关系，我们可以在 Mermaid 中将其指定为 PERSON }|..|{ CAR : "driver" 请注意关系中间的两个点，这将导致在两个实体之间绘制虚线。但是，当这种多对多关系解析为两个一对多关系时，我们观察到如果没有 PERSON 和 CAR，NAMED-DRIVER 就不可能存在 - 关系变得具有识别性，并使用连字符指定，连字符转换为实线

Mermaid 语法
图形预览

erDiagram
    direction LR
    PERSON {
        int id PK "人员ID，主键"
        varchar(50) name "姓名"
    }
    
    CAR {
        int id PK "汽车ID，主键"
        varchar(50) model "车型"
    }
    
    NAMED-DRIVER {
        int id PK "驾驶员ID，主键"
        int person_id FK "人员ID，外键"
        int car_id FK "汽车ID，外键"
    }
    
    PERSON ||..o{ CAR : driver
    PERSON }o..o{ NAMED-DRIVER : is
    CAR ||--o{ NAMED-DRIVER : is

甘特图 (Gantt Chart)

甘特图用于展示项目进度和时间安排，非常适合项目管理

语法说明

甘特图的语法结构如下：

图表声明：使用 gantt 关键字开始
标题设置：使用 title 关键字设置图表标题
日期格式：使用 dateFormat 设置日期格式（如 YYYY-MM-DD）
阶段分组：使用 section 关键字定义阶段
任务定义：定义任务及其状态和时间
- 任务名称 : 状态, 任务ID, 开始时间, 结束时间
- 状态：done（已完成）、active（进行中）、空（未开始）

甘特图示例

Mermaid 语法
图形预览

gantt
    title 项目开发计划
    dateFormat  YYYY-MM-DD
    section 需求分析
    需求调研           :done,    des1, 2024-01-01, 2024-01-07
    需求文档编写       :done,    des2, 2024-01-08, 2024-01-14
    section 设计阶段
    系统设计           :active,  des3, 2024-01-15, 2024-01-21
    数据库设计         :         des4, 2024-01-22, 2024-01-28
    section 开发阶段
    前端开发           :         des5, 2024-01-29, 2024-02-11
    后端开发           :         des6, 2024-02-12, 2024-02-25

饼图 (Pie Chart)

饼图用于展示数据的比例分布，语法简单直观

语法说明

饼图的语法结构如下：

图表声明：使用 pie 关键字开始图表
标题设置：使用 title 关键字设置图表标题（可选）
数据定义：
- 在双引号 " " 内写上分区名称
- 分区名后使用冒号 : 作为分隔符
- 分隔符后写上数值，最多支持2位小数
- 数据会自动以百分比形式展示

基础饼图

Mermaid 语法
图形预览

pie title 编程语言使用比例
    "JavaScript" : 35
    "Python" : 25
    "Java" : 20
    "Go" : 10
    "其他" : 10

百分比饼图

Mermaid 语法
图形预览

pie title 项目时间分配
    "开发" : 50
    "测试" : 20
    "文档" : 15
    "会议" : 10
    "其他" : 5

Git图 (GitGraph)

Git 图用于展示 Git 分支和提交历史，非常适合版本控制文档

语法说明

Git 图的语法结构如下：

图表声明：使用 gitGraph 关键字开始
提交定义：使用 commit 关键字定义提交
- commit id: "提交信息" - 定义提交
分支操作：
- branch 分支名 - 创建分支
- checkout 分支名 - 切换分支
合并操作：使用 merge 关键字合并分支
- merge 分支名 id: "合并信息"

基础Git图

Mermaid 语法
图形预览

gitGraph
    commit id: "初始提交"
    branch develop
    checkout develop
    commit id: "开发功能A"
    commit id: "开发功能B"
    checkout main
    merge develop id: "合并develop"
    commit id: "发布v1.0"

复杂分支图

Mermaid 语法
图形预览

gitGraph
    commit id: "项目开始"
    branch feature/login
    checkout feature/login
    commit id: "登录页面"
    commit id: "登录逻辑"
    checkout main
    commit id: "基础框架"
    branch feature/register
    checkout feature/register
    commit id: "注册功能"
    checkout main
    merge feature/login id: "合并登录"
    merge feature/register id: "合并注册"
    commit id: "v1.0发布"

样式和一些技巧

主题配置

Mermaid 支持多种主题，可以通过配置来改变图表的外观：

Mermaid 语法
图形预览

%%{init: {'theme':'dark'}}%%
graph TD
    A[开始] --> B[结束]

节点样式

可以为节点添加自定义样式：

Mermaid 语法
图形预览

graph TD
    A[开始] --> B[处理中]
    B --> C[结束]
    
    classDef startNode fill:#e1f5fe,stroke:#01579b,stroke-width:2px
    classDef processNode fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
    classDef endNode fill:#e8f5e8,stroke:#1b5e20,stroke-width:2px
    
    class A startNode
    class B processNode
    class C endNode

子图分组

对于复杂图表，可以使用子图进行分组，提高可读性：

Mermaid 语法
图形预览

graph TD
    subgraph "用户模块"
        A[用户登录] --> B[用户注册]
        B --> C[用户管理]
    end
    
    subgraph "订单模块"
        D[创建订单] --> E[订单支付]
        E --> F[订单完成]
    end
    
    subgraph "商品模块"
        G[商品浏览] --> H[商品搜索]
        H --> I[商品详情]
    end
    
    A --> D
    D --> G

注释功能

在 Mermaid 图表中添加注释非常简单，在行首加入 %% 即可：

Mermaid 语法
图形预览

graph TD
    %% 这是注释
    A[开始] --> B[结束]

最佳实践

保持简洁：避免过于复杂的图表，保持清晰易读
使用有意义的标签：节点和连接线的标签应该清晰表达含义
合理使用颜色：通过颜色区分不同类型的节点或状态
适当分组：对于复杂图表，使用子图进行分组
测试渲染：使用 Mermaid Live Editor 测试图表效果

总结

Mermaid 提供了多种图表语法支持，但复杂图的语法也较复杂，应综合考虑画图成本进行选择。在实际使用中，建议结合具体需求选择合适的图表类型，并遵循最佳实践来创建清晰、美观的图表

概述​

基本语法结构​

图表类型声明​

方向控制​

节点定义​

连接线​

常用图表示例​

流程图 (Flowchart)​

语法说明​

基础流程图​

不同节点形状​

带标签的连接线​

时序图 (Sequence Diagram)​

语法说明​

基础时序图​

带激活和注释的时序图​

数据库ER图 (Entity Relationship Diagram)​

语法说明​

基础ER图​

复杂关系ER图​

连接线样式举例​

甘特图 (Gantt Chart)​

语法说明​

甘特图示例​

饼图 (Pie Chart)​

语法说明​

基础饼图​

百分比饼图​

Git图 (GitGraph)​

语法说明​

基础Git图​

复杂分支图​

样式和一些技巧​

主题配置​

节点样式​

子图分组​

注释功能​

最佳实践​

总结​

概述

基本语法结构

图表类型声明

方向控制

节点定义

连接线

常用图表示例

流程图 (Flowchart)

语法说明

基础流程图

不同节点形状

带标签的连接线

时序图 (Sequence Diagram)

语法说明

基础时序图

带激活和注释的时序图

数据库ER图 (Entity Relationship Diagram)

语法说明

基础ER图

复杂关系ER图

连接线样式举例

甘特图 (Gantt Chart)

语法说明

甘特图示例

饼图 (Pie Chart)

语法说明

基础饼图

百分比饼图

Git图 (GitGraph)

语法说明

基础Git图

复杂分支图

样式和一些技巧

主题配置

节点样式

子图分组

注释功能

最佳实践

总结