Mermaid 是一个强大的图表工具,用简单的文本描述生成复杂的图表。为了让初学者更好地掌握 Mermaid 的使用,这里将详细介绍 Mermaid 的基本语法、高阶语法及使用技巧,并结合实际示例逐步讲解每一个符号和字母的意义。
一、Mermaid 基本语法详解
1. 流程图 (Flowchart)
流程图是 Mermaid 中最常用的图表类型之一,用于描述流程步骤及其关系。
详细解释:
-
graph TD
:定义图表类型和方向。TD
(Top Down):表示图从上到下布局。LR
(Left to Right):从左到右。BT
(Bottom to Top):从下到上。RL
(Right to Left):从右到左。
-
A[开始]
:定义一个普通矩形节点,ID 为A
,显示内容为“开始”。[内容]
:表示这是一个矩形节点。A
:节点的唯一标识符,可以是任何字母或名称。
-
B{是否继续?}
:定义一个菱形判断节点,ID 为B
,用于条件分支。{内容}
:表示这是一个判断节点,通常用于分支选择。
-
-->
:表示节点之间的连线方向,连接两个节点。 -
|是|
:连线标签,用于标注分支路径的条件。
2. 序列图 (Sequence Diagram)
序列图用来展示对象或角色之间的交互顺序。
详细解释:
-
sequenceDiagram
:定义图表类型为序列图。 -
participant User as 用户
:定义参与者User
,并将其显示为“用户”。participant
:定义图表中的参与者(角色或对象)。User
:参与者的 ID。as 用户
:显示名称,便于阅读理解。
-
User->>System: 发送请求
:表示User
向System
发送消息,使用->>
表示消息的传递方向。 -
System-->>User: 返回响应
:表示System
向User
发送消息,-->>
表示消息传递的方向。
3. 类图 (Class Diagram)
类图用于表示类及其之间的关系,适合面向对象编程的设计。
详细解释:
-
classDiagram
:定义图表类型为类图。 -
class Animal {...}
:定义一个类Animal
,包含属性和方法。+String name
:公有属性name
,类型为String
。+int age
:公有属性age
,类型为int
。+makeSound()
:公有方法makeSound()
。
-
Animal <|-- Dog
:表示Dog
类继承Animal
类。<|--
:箭头符号,表示继承关系。
Mermaid 类图关系中的 "1"
和 "*"
解释
-
"1"
:表示“一对一”关系。- 意思是:每个对象在关联的另一端只有一个实例。例如,
Student "1" -- "1" ProgramEnrollment
表示一个学生只能有一个注册记录,而每个注册记录也只能对应一个学生。
- 意思是:每个对象在关联的另一端只有一个实例。例如,
-
"*"
:表示“一对多”关系。- 意思是:每个对象在关联的另一端可以有多个实例。例如,
Department "1" -- "*" Program
表示一个部门可以有多个课程,但一个课程只能属于一个部门。
- 意思是:每个对象在关联的另一端可以有多个实例。例如,
-
"0..1"
:表示零个或一个的关系,即对象的另一端可以没有关联或只有一个关联。 -
"1..*"
:表示至少一个到多个的关系,意思是对象的另一端必须至少有一个关联实例。
这些符号是为了方便阅读,明确表示对象之间的关联数量,并不是 Mermaid 的语法规则,而是从 UML 类图中的概念借鉴而来。
示例解释:Mermaid 类图中的 "1"
和 "*"
各个关系的详细含义:
-
Department "1" -- "*" Program
:- 含义:一个
Department
(部门)可以有多个Program
(课程),但一个课程只能由一个部门管理。
- 含义:一个
-
Department "1" -- "*" Offer
:- 含义:一个
Department
可以提供多个Offer
(项目),但每个项目只能由一个部门提供。
- 含义:一个
-
Offer "1" -- "1" Program
:- 含义:每个
Offer
对应一个Program
,反过来,每个Program
也只能有一个Offer
。
- 含义:每个
-
Program "1" -- "1" Curriculum
:- 含义:每个
Program
(课程)都有一个Curriculum
(课程表),反之亦然。
- 含义:每个
-
Curriculum "1" -- "*" Course
:- 含义:一个
Curriculum
包含多个Course
(课程),但一个课程只能属于一个课程表。
- 含义:一个
-
Student "1" -- "1" ProgramEnrollment
:- 含义:每个
Student
(学生)有一个ProgramEnrollment
(课程注册记录),而每个注册记录也只能有一个对应的学生。
- 含义:每个
-
ProgramEnrollment "1" -- "*" CourseEnrollment
:- 含义:一个
ProgramEnrollment
包含多个CourseEnrollment
(课程选课),但一个选课记录只能属于一个课程注册。
- 含义:一个
-
Student "1" -- "1" Offer
:- 含义:每个
Student
与一个Offer
相关联,反之亦然。
- 含义:每个
-
ProgramEnrollment "1" -- "1" Program
:- 含义:每个
ProgramEnrollment
对应一个Program
,同样,一个Program
只能有一个注册记录。
- 含义:每个
-
CourseEnrollment "1" -- "1" Course
:- 含义:每个
CourseEnrollment
对应一个具体的Course
(课程),反过来也是一样。
- 含义:每个
二、Mermaid 高阶语法
1. 嵌套子图 (Subgraphs)
子图用于分组和层次展示节点,常见于复杂的流程图。
解释:
subgraph 子图1
:定义一个子图,名称为“子图1”。end
:结束子图定义。- 子图之间可以相互连接,展示不同部分之间的关系。
2. 链接与点击交互 (Links and Clicks)
通过添加超链接使图表具有交互功能。
解释:
click A href "URL" "说明文字"
:为节点 A 添加一个点击链接。
三、Mermaid注释
在 Mermaid 中,你可以使用注释来提供额外的说明和文档,而这些注释不会在生成的图形中显示。Mermaid 支持几种不同类型的注释,具体取决于你使用的图类型。以下是如何在 Mermaid 中使用注释的详细说明和示例。
1. 注释在类图中的使用
在 Mermaid 类图中,注释用于提供额外的描述信息,这些信息不会在图形中显示。注释通常放在类定义之前或之后,以说明类的属性或方法。
示例:
在上面的示例中:
%% 这是一个类图的注释
是一个注释,它解释了下面的内容。- 注释放在 Mermaid 代码的
%%
符号之后,Mermaid 引擎会忽略这些注释,不会在生成的图形中显示。
2. 注释在流程图中的使用
在 Mermaid 流程图中,注释也使用 %%
符号,注释通常用于解释流程图的某些部分或提供额外的上下文信息。
示例:
在上面的示例中:
%% 这条注释说明了流程的开始
是一个注释,用于解释图中节点的流动。- 注释放在
%%
符号之后,Mermaid 引擎会忽略这些内容,不会在图形中显示。
3. 注释在甘特图中的使用
在 Mermaid 甘特图中,注释也是使用 %%
符号。注释可以用来解释项目任务的详细信息。
示例:
在上面的示例中:
%% 设计阶段的详细说明
是一个注释,用于提供额外的上下文。- 注释同样放在
%%
符号之后,不会在生成的甘特图中显示。
4. 注释在其他图类型中的使用
对于 Mermaid 支持的其他图类型,如饼图、状态图等,注释的使用方式基本相同。都是使用 %%
符号来插入注释。
总结
在 Mermaid 中,注释使用 %%
符号添加。这些注释在生成的图形中不会显示,它们仅用于在 Mermaid 源代码中添加额外的说明或文档。可以根据具体的图类型在适当的位置添加注释,以提高代码的可读性和可维护性。
三、Mermaid 使用技巧
1. 使用 Mermaid Live Editor
Mermaid Live Editor 是一个在线工具,可以实时编写和预览 Mermaid 代码。访问 Mermaid Live Editor 开始使用。
四、完整示例
以下是一个综合示例,展示流程图、子图、条件判断和交互链接的应用:
解释:
- 定义了一个名为“工作流程”的子图,展示从“开始”到“结束”的一系列步骤。
- 包含条件判断节点和不同路径的选择。
- 在执行步骤1上添加了点击链接,实现与外部资源的交互。