Mermaid是一个开源的、基于JavaScript的绘图库，它可以用简洁的、人类可读的文本描述和绘制流程图、序列图、甘特图、类图、实例图、状态图和部署图等不同类型的图表。Mermaid的语法简单易懂，支持针对不同类型图表的定制化设置，可以轻松绘制高质量的图表并嵌入到网页、Markdown文档和其它支持HTML的场景之中。此外，它还支持插件和编辑器的集成，使得用户可以更加高效地使用和管理Mermaid图表。Mermaid是一个接近理想状态的图表和流程图的设计工具，是众多开发者和作者的首选。

1 快速入门

1.1 支持的图表类型

• 流程图（Flowcharts）：用于表示流程或过程中的步骤。支持各种节点和连线风格。
• 序列图（Sequence Diagrams）：用于表示对象之间的交互，展示消息的发送和接收过程。
• 类图（Class Diagrams）：用于表示类及其关系，支持类的属性和方法定义。
• 状态图（State Diagrams）：用于描述系统状态及其转换，适用于复杂的状态机建模。
• 甘特图（Gantt Charts）：用于项目管理和时间规划，展示任务的开始和结束时间。
• 饼图（Pie Charts）：用于展示数据的比例关系。
• 实体关系图（Entity Relationship Diagrams，ERDs）：用于表示数据库的实体及其关系。

1.2 浏览器使用

Mermaid作为一个JavaScript库，可以在浏览器中直接引入，调用Mermaid的JavaScript API在网页中动态生成图表：

<!-- 引入mermaid库-->
<script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
<!-- 以后需要的时候再解析文本-->
<script>mermaid.initialize({startOnLoad:true});</script>

1.3 在Node.js中使用

如果需要在Node.js中使用Mermaid，可以在命令行中运行以下命令来安装：

npm install mermaid --save

安装成功后，可以使用以下代码来生成一个流程图的HTML：

const mermaid = require('mermaid');
mermaid.initialize({
    startOnLoad: true
});
const graphDefinition = 'graph TD\nA-->B';
const html = mermaid.render('graphDiv', graphDefinition);

使用上述代码，在终端中运行时会输出一个HTML文档，其中Mermaid库提供的render函数用于将文本转换为定义好的图表格式。

1.4 在Markdown中使用

Markdown中可使用如下语法绘制Mermaid图（每行结尾的分号可省略）：

graph LR
    A[开始] --> B(流程)
    B --> C{判断}
    C -->|结果1| D[结束]
    C -->|结果2| E[结束]

本站使用了WP Mermaid插件，可在任意位置输出Markdown语法的Mermaid图，只需使用短代码[mermaid]、[/mermaid]包裹即可。上述语句所对应的图如下所示：

2 流程图（Flowcharts）

流程图（Flowcharts）用于描述一个过程或系统的步骤和逻辑。它通过使用各种形状的符号和箭头来表示操作、决策和流程的方向，帮助人们直观地理解和分析复杂的流程。

【例】基本语法

graph LR;
    A[开始] --> B[接收订单]
    B --> C{订单有效?}
    C -->|是| D[处理订单]
    C -->|否| E[拒绝订单]
    D --> F[发货]
    F --> G[结束]
    E --> G

2.1 方向

方向在开头使用，声明流程图的方向：

1. TB（Top-Bottom）：从上到下【默认】
2. BT（Bottom-Top）：从下到上
3. LR（Left-Right）：从左到右
4. RL（Right-Left）：从右到左

2.2 节点

Mermaid流程图中的节点通过各种几何形状来表示流程中的不同元素，语法格式：

• 无名字的节点：直接写内容，此时节点边框为矩形，且节点内容不能有空格。
• 有名字的节点：节点名（id）后书写内容，内容左右有特定符号，节点边框由符号决定，节点内容可以有空格。

常见的节点类型及其用途：

【例】各种结点

graph LR

id1[ 矩形 ]
id2( 圆角矩形 )
id3([ 体育场形 ])
id4[[ 子程序形 ]]
id5[( 圆柱形 )]
id6(( 圆形 ))
id7{ 菱形 }
id8{{ 六边形 }}
id9[/ 平行四边形 /]
id10[\ 反向平行四边形 \]
id11[/ 梯形 \]
id12[\ 反向梯形 /]
id13> 不对称矩形 ]
id14((( 双圈节点 )))

id1 --- id2 --- id3 --- id4 --- id5 --- id6 --- id7
id8 --- id9 --- id10 --- id11 --- id12 --- id13 --- id14

在Mermaid流程图中，节点通过连线（箭头或线）连接，表示流程的顺序和逻辑关系。节点的形状和内容可以根据流程的具体需求进行选择和设计，以清晰地展示流程的每个步骤和决策点。

2.3 连线样式

Mermaid流程图中的连线样式用于表示流程中步骤之间的关系和逻辑顺序。以下是Mermaid流程图的连线样式及其特点：

【例】各种连线及线上文字样式

graph LR
实线 --- A --> B --> |线上文字| C

粗实线 --- D ==> E ==> |线上文字| F

虚线 --- G -.-> H -.-> |线上文字| I

无箭头线 --- J --- |线上文字| K

双向箭头线 --- L <--> M <--> |线上文字| N

2.4 汇合

在Mermaid流程图中，&符号用于表示节点之间的并行关系，用于将多个节点连接到同一个后续节点，表示这些节点可以同时进行，然后在某个点汇合。

【例】使用&符号绘制汇合点

graph LR;

A[开始] --> B[步骤1];
A --> C[步骤2];
B & C --> D[汇合点];
D --> E[结束];

2.5 子图

在Mermaid中，子图（Subgraphs）用于将相关的节点和连线组织在一起，使复杂的流程图更加清晰和易于理解。子图可以自定义方向，可以嵌套，也可以相互连接。

子图基本语法：

subgraph 子图名称[子图标题]
    direction <方向>
    节点和连线定义
end

【例】子图示例

graph LR;
    subgraph 一级子图
        direction TB
        subgraph 二级子图1
            direction RL
            i1 --> f1
        end
        subgraph 二级子图2
            direction BT
            i2 --> f2
        end
    end
    A --> 一级子图 --> B
    二级子图1 --> 二级子图2

3 时序图（Sequence Diagrams）

时序图（Sequence Diagrams）是一种用于展示系统中对象之间如何交互的 UML 图。主要用于展现对象之间交互的顺序，这些交互以时间顺序排列，通常用于系统分析和设计阶段来捕捉系统的动态行为。时序图描述了参与交互的对象集合以及它们之间消息传递的时间顺序，非常直观地表示了各个组件或对象在整个流程中的作用和活动。

【例】基本语法

sequenceDiagram

Teresa ->> KINA: 发起对话
KINA -->> Teresa: 回复

Teresa -) KINA: 发起对话（不需要回复）

其中

• Teresa和KINA是参与者（participants）
• ->>表示从一个参与者发送同步消息到另一个参与者。
• -->>表示从一个参与者发送异步消息到另一个参与者。
• -)表示从一个参与者发送异步消息到另一个参与者，但不等待回应。

3.1 参与者（Participants）

参与者（Participants）可以使用participant或actor关键字定义：

• participant：一个普通的参与者
• actor：一个角色（通常是一个人）

【例】预定义参与者

sequenceDiagram
    participant Teresa
    actor KINA
    Teresa->>KINA: 发起对话
    KINA-->>Teresa: 对话回应

3.2 消息

消息（Messages）是参与者之间传递的信息，可以是同步的（->>）或异步的（-->>）。

【例】发送同步与异步消息

sequenceDiagram
    Teresa ->> KINA: 询问?
    KINA -->> Teresa: 回复

3.3 激活期（Activations）

激活期（Activations）表示参与者在一段时间内处于活跃状态，可使用activate和deactivate关键字手动控制激活期，也可使用+和-快捷表示。

【例】开始、结束参与者的激活状态

sequenceDiagram

    Teresa ->> +KINA: 询问（开始KINA的激活状态）？
    KINA -->> -Teresa: 回复（结束KINA的激活状态）

3.4 循环

循环（Loops）用于表示重复的消息传递，循环体表明里面的行为可以循环进行。可以使用loop和end关键字定义循环。

循环体基本语法：

loop 循环体名称
    各种行为
end

【例】简单循环体

sequenceDiagram
    Teresa ->> KINA: 发起对话，之后开启循环

    loop 简单循环
        Teresa ->> KINA: Teresa对KINA的动作
        KINA ->> KINA: KINA对自己的动作
        KINA ->> Teresa: KINA对Teresa的动作
        Teresa ->> Teresa: Teresa对自己的动作
    end

    KINA -->> Teresa: 结束对话!

3.5 并行（Parallel）

使用par和end关键字定义并行（Parallel）

sequenceDiagram
    participant User
    participant ServiceA
    participant ServiceB

    User ->> ServiceA: 发起请求A
    par 并行处理
        ServiceA ->> ServiceB: 请求数据B
        ServiceA ->> ServiceA: 处理本地数据A
    end
    ServiceB -->> ServiceA: 数据响应B
    ServiceA -->> User: 最终响应

3.6 注释（Notes）

注释（Notes）用于在时序图中添加说明文字，使用Note等关键字定义注释，详见下例。

【例】为3.2中的时序图添加注释

sequenceDiagram
    Teresa ->> +KINA: 询问?
    Note left of Teresa: Teresa开始询问
    Note right of KINA: KINA被激活
    KINA -->> -Teresa: 回复
    Note right of KINA: KINA退出激活
    Note left of Teresa: Teresa没有动作了

3.7 序列号（Sequence Numbers）

可以为每个消息添加序列号（Sequence Numbers），以帮助理解消息的顺序。使用autonumber关键字启用自动编号功能。

【例】声明自动编号，其中%（或%%）后内容为mermaid语句中的注释（Comments）

sequenceDiagram
    % 声明自动编号
    autonumber
    Teresa -->> KINA: Update？
    KINA -->> Teresa: Done！
    KINA -->> Yohane: Mission start？
    Yohane -->> KINA: Yes！
    Yohane -->> Teresa: Go！

3.8 角色菜单（Actor Menus）

Mermaid时序图的Actor Menus功能是一项较新的互动性增强特性，它允许在序列图中为参与者（actors）添加上下文菜单。这些菜单可以包含一系列的操作或链接，鼠标悬浮在参与者上时会显示出来。

【例】添加Actor Menus

sequenceDiagram
    autonumber
    participant Teresa
    participant KINA
    links KINA: {"Hyperplasma": "https://www.hyperplasma.top", "GitHub": "https://github.com/Akira37R"}

    Teresa -->> KINA: Do you have some sites?
    KINA -->> Teresa: Yep!
    Teresa -->> KINA: Where?
    KINA -->> Teresa: See my actor menu!

4 甘特图（Gantt Charts）

甘特图（Gantt Charts）主要用于项目管理和时间规划，通过图形化的方式展示项目的时间线，帮助团队清晰地看到每个任务的开始和结束时间，以及任务之间的依赖关系。

【例】基本语法

gantt
    dateFormat YY-MM-DD
    axisFormat %y.%m.%d
    excludes weekends
    title XXX项目开发计划

    % 定义section
    section 预研
    技术预研: done, preface1, 25-01-01, 1w
    方案预研: done, preface2, 25-01-01, 1w
    内部讨论: crit, done, preface3, after preface2, 2d

    section 研发
    前端: done, dev1, after preface3, 15d
    后端: done, dev2, after preface3, 30d
    前后端联调: active, co-dev, after b2, 7d

    section 测试
    功能测试: test1, after co-dev, 7d
    性能测试: test2, after co-dev, 14d
    打包: test3, after test2, 3d

    section 发布
    预发布: release1, after c3, 2025-03-31
    正式发布: release2, after release1, 2d
    功能上线: milestone, release3, after release2, 0d

4.1 任务格式

统一格式：<状态标记>, <任务id>, <开始时间>, <结束时间>

• 状态标记可省略
• 开始时间可以为after <其他任务的id>，表示在某任务之后开始
• 结束时间可以为持续时间长度，格式为数字 + d（天数）/w（周数）/y（年数）

4.2 状态标记

1. active：表示任务正在进行中。
2. done：表示任务已完成。
3. crit：表示任务是关键路径上的任务。
4. milestone：里程碑通常表示项目中的关键事件，使用类似任务的语法，但持续时间通常是1天。

4.3 日期格式

• dateFormat：定义日期格式，例如YYYY-MM-DD。
• axisFormat：定义坐标轴的日期格式，例如%Y-%m-%d。

4.4 排除日期

excludes属性可以排除以下几种类型的日期：

1. 具体日期：以YYYY-MM-DD格式指定的特定日期
2. 星期几：一周中的某一天，如sunday
3. 周末：使用weekends可以排除所有的周末（默认是周六和周日）。

5 饼图（Pie Charts）

饼图（Pie Charts）是一种用于展示数据比例关系的图表，通过将圆饼分割成几个扇区来显示每一部分的大小与整体的比例关系。

基本语法：

pie
    [title] [titlevalue]
    "[datakey1]" : [dataValue1]
    "[datakey2]" : [dataValue2]
    "[datakey3]" : [dataValue3]

• title：为饼图添加标题，显示在饼图的上方或中心。【可选】
• 键值对：各扇区的标签和数值，其中数值只支持int和float，并最多支持两位的小数。Mermaid会自动计算总和并按比例分配各个扇区的大小。

【例】开销占比饼图示例

pie
    title Hyperplasma 2035年1月开销占比
    "技术开销" : 2500000
    "娱乐开销" : 1300000
    "其他开销" : 480000

6 用户旅行图（User Journey diagram）

用户旅行图（User Journey diagram）是一种用于描述用户在系统、应用程序或网站中完成特定任务所采取的步骤的图表。

【例】基本语法

journey
    title 在线购物网站使用旅程
    section 浏览商品
      登录网站 : 4 : 用户
      浏览商品分类 : 5 : 用户
      查看商品详情 : 4 : 用户
    section 加入购物车
      选择商品规格 : 5 : 用户
      点击加入购物车 : 5 : 用户
    section 结算支付
      点击去结算 : 2 : 用户
      选择收货地址 : 5 : 用户
      选择支付方式并支付 : 3 : 用户
    section 查看订单
      查看订单详情 : 4 : 用户
      确认收货 : 5 : 用户

主要由标题、阶段和任务组成，具体如下：

1. 标题：使用title关键字后跟图表的标题。
2. 阶段（Section）：使用section关键字定义用户旅行的不同阶段或部分，每个阶段代表用户完成任务的一个主要环节。
3. 任务（Task）：在每个阶段下，使用任务名称 : 评分 : 参与者的格式来描述具体的任务。
   • 任务名称：用户执行的操作或步骤
   • 评分：一个0到5之间的数字，用于表示该任务的满意度或重要性等
   • 参与者：执行该任务的用户或角色，多个参与者用逗号分隔。

7 类图（Class Diagrams）

类图（Class Diagrams）是面向对象建模中用于描述系统结构的核心工具。

【例】基本语法

classDiagram
    Class01 <|-- Hyplus : Cool
    Class09 --> C2 : Where am I?
    Class09 --* C3
    Class09 --|> Class07
    Class07 : equals()
    Class07 : Object[] elementData
    Class01 : size()
    Class01 : int hyplusValue
    Class01 : int status
    class Class10 {
      int id
      size()
    }

7.1 类成员

定义方式参考各编程语言。

属性：

1. +：公共属性（public）
2. -：私有属性（private）
3. #：保护属性（protected）
4. ~：包内属性（default）
5. $：静态属性（static）

方法：定义方式与属性类似，但需要在方法名后加上参数列表和返回类型。

7.2 泛型

泛型类型使用~包裹表示。

【例】定义含泛型的类

classDiagram
    class Square~Shape~ {
        int id
        List~int~ position
        setPoints(List~int~ points)
        getPoints() List~int~
    }

7.3 关系

类图中可以定义多种关系，包括泛化（继承，IS-A）、实现、关联、依赖、聚合和组合：

1. 泛化：父类 <|-- 子类（或--|>）
2. 实现：实现类 <|.. 接口（或..|>）
3. 关联：类A -- 类B
4. 依赖：类A ..> 类B（被依赖）（或<..）
5. 聚合：整体类 o-- 部分类（或--o）
6. 组合：整体类 *-- 部分类（或--*）

【例】各种关系

classDiagram
    Animal <|-- Dog
    Animal <|.. IDomestic
    Site -- Server
    KINA ..> Hyplus
    汽车 o-- 轮胎
    公司 *-- 部门

7.4 特殊标记

可以使用特殊标记来表示接口、抽象类等：

1. 接口：<<interface>>
2. 抽象类：<<abstract>>

【例】标记接口和抽象类

classDiagram
    class ICourse {
        +String name
        +select() Boolean
    }
    <<interface>> ICourse
    class Animal {
        <<abstract>>
        +String name
        +eat(food: string): void
    }

本站Mermaid插件暂不支持标记