內容目錄

Mermaid 实用教程

ref: https://mermaid.js.org/config/Tutorials.html 、 www.edrawsoft.com

文中 Typora 渲染失敗的例子，在其他Render不一定失敗。

0. 简介

0.1 什么是Mermaid？

Mermaid是一种使用 JS 进行本地渲染的绘图工具，用户可以用代码方式快捷地创建图表，广泛集成于许多 Markdown 编辑器中。
项目地址：https://github.com/mermaid-js/mermaid（需要将梯子设置成全局模式才能访问）

0.2 怎么使用Mermaid？

在markdown中，使用 mermaid 标注程式语言的代码框，即可被渲染成 mermaid图形。一些集成了markdown的编辑器，会实现部分的mermaid语法，如Typora 和 StackEdit。

网页可以集成Mermaid渲染器，使用标记方式做mermaid渲染。

简单的包含 mermaid图形的html如下：








graph LR
    A --- B
    B-->C[fa:fa-ban forbidden]
    B-->D(fa:fa-spinner);

0.3 Mermaid能绘制哪些图？

mermaid 还在持续开发中，目前可以画的图表有：

graph: 基础的角色连接图。
提供角色的形状、颜色、和连线的样式与标记。可以用来表达工作的流程图。
sequenceDiagram：序列图。UML相容。
表达多个角色在一连串顺序事件发生时的交互动作。
classDiagram：类图。UML相容。
静态的表达系统中的类或实体之间的相依关系，以及类的内容描述。
stateDiagram-v2：状态图。UML相容。
画出任务状态机的状态转移图。标示着状态机的静态转换的拓扑样式。
gantt：甘特图。
安排分析一个工作内的所有任务的相依关系、需时、以及关键性，画出任务的整体时程。
pie：饼状图。
使用圆形表示每个node的数值在总和中的占比。
journey：用户旅程图。线性显示一个旅程。
可以将行程分阶段，阶段内的每个景点可以有评分和参与人。
erDiagram：实体关系图。（Typora不支持实体的属性宣告、StackEdit可以）
gitGraph：git 库分支图。（Typora、StackEdit支持不佳）
requirementDiagram：用户需求图。（Typora、StackEdit不支持）

Mermaid 是一个用于画流程图、状态图、时序图、甘特图的库，使用 JS 进行本地渲染，广泛集成于许多 Markdown 编辑器中。

之前用过 PlantUML，但是发现这个东西的实现原理是生成 UML 的图片后上传服务端，每次再从服务端读取，因此觉得不够鲁棒，隐私性也不好，因而弃用。

Mermaid 作为一个使用 JS 渲染的库，生成的不是一个“图片”，而是一段 HTML 代码，因此安全许多。

官网：https://mermaidjs.github.io/
Github 项目地址：https://github.com/knsv/mermaid

在markdown中，使用 `mermaid 标注语法的文字框，即可被渲染成 mermaid图形。

Mermaid 基础语法：

语法很简单，每一行定义一个参数或是描述一个图形特征。不同的图形类别会有不同特征的描述，但大致上：

第一行是图形类别。
之后的每一行就是图形中的节点或连线的描述。
连线上可以有标记，通常是连线描述后加上冒号 : ，冒号之后的文字就会标记在线上。
以 %% 开头的是mermaid 注解，不会被 mermaid 渲染。

Mermaid 图表类型：

流程图 graph / flowchart
顺序图 sequenceDiagram
类图 classDiagram
状态图 stateDiagram
实体关系图 erDiagram ==（Typora目前不能画属性, StackEdit OK）==
用户旅程图 journey
甘特图 gantt
饼状图 pie
需求图 requirementDiagram ==(Typora, StackEdit 都不支持)==
Git 图 gitGraph ==(Typora、StackEdit 目前支持不佳)==

1. 流程图 graph / flowchart

流程图是最普通的图表。内容以节点和节点间的连线表达。

流程图表有四个延展方向。
节点可以有名称和外观选择。
连线有样式、箭号、可选，还可以添加标记、延长连线。新的流程图 flowchart 类型尚在beta版本，语法不变。目前连线表达方式更多样化了。
可以有子图，将图表再分门别类表达。子图可以包含子图，还可当新的节点建立连线。
有 style和 linkstyle 可以修饰节点和线条的颜色与边框。还可用 class 将定义style，然后多个节点用同一种 class 的 style 渲染。

1.1 图表类型+方向

Mermaid 支持四种延展图表的方向，语法如下：

graph 方向描述
    图表中的其他语句...

其中“方向描述”为：
TB ：从上到下、 BT ：从下到上、LR：从左到右、 RL：从右到左。缺省值是从上到下。TB 可以用传统的 TD （top down）替代。

1.2 节点定义

<节点id>[<左边框> <节点文字> <右边框>]

节点id 为必备，左右边框和节点文字为可选，没有的话是以id为内容的矩形节点。id和边框之间不能有空格。

目前有13种节点边框样式，用下面例子展现：

flowchart LR
 id1[矩形]           %% 一般流程
 id2(圆角矩形)        %% 事件
 id3((圆形))         %% 开始
 id4([圆边矩形])      %% 开始/结束
 id5{菱形}           %% 条件判定
 id6{{六角形}}       %% 准备/数据传输
 id7>旗帜形]         %% ？
 id8[[子程序]]       %% 子程序或预定义流程
 id9[(圆柱形)]       %% 存储
 id10[/右平行四边形/] %% 数据输入/输出
 id11[\左平行四边形\] %% ？
 id12[/正梯形\]      %% ？
 id13[\倒梯形/]      %% 手动操作
 %%底下用6种连线连接节点，演示图形。（实线、粗实线、虚线）x（无箭头、有箭头）共六种连线。
  id1---id2-->id3===|线尾添加标注|id4==>id5; 
  id6-.-id7-.-id8-.线中增加标注.->id9; 
  id10 -.- id11-.-id12-..-|延长虚线, <br>并在线尾用双竖线增加标注|id13

渲染如下：

flowchart LR
 id1[矩形]           %% 一般流程
 id2(圆角矩形)        %% 事件
 id3((圆形))         %% 开始
 id4([圆边矩形])      %% 开始/结束
 id5{菱形}           %% 条件判定
 id6{{六角形}}       %% 准备/数据传输
 id7>旗帜形]         %% ？
 id8[[子程序]]       %% 子程序或预定义流程
 id9[(圆柱形)]       %% 存储
 id10[/右平行四边形/] %% 数据输入/输出
 id11[\左平行四边形\] %% ？
 id12[/正梯形\]      %% ？
 id13[\倒梯形/]      %% 手动操作
 %%底下用6种连线连接节点，演示图形。（实线、粗实线、虚线）x（无箭头、有箭头）共六种连线。
  id1---id2-->id3===|线尾添加标注|id4==>id5; 
  id6-.-id7-.-id8-.线中增加标注.->id9; 
  id10 -.- id11-.-id12-..-|延长虚线, <br>并在线尾用双竖线增加标注|id13

Note: mermaid graph 的节点形状不多，不能完全对应到传统流程图。
以下节录传统流程图的一些可能的符号供参考：(from www.edrawsoft.com )

需要注意的是，如果节点的文字中包含标点符号，需要时用双引号包裹起来。
另外如果希望在文字中使用换行，请使用
替换换行

1.3 节点间的连线

graph 的连线只有实线 ---、粗实线===、虚线-.- 三种线条。连线可以增加箭头：实线 -->、粗实线==>、虚线-.-> 。共有3x(1+1)=6种线样式。
新的 mermaid beta 使用 flowchart 取代 graph，添加两种箭头：圆点箭头--o ，和x箭头--x。三种箭头连线可以是双向箭头：<--> 、o--o 、x--x。共有3x(1+3+3)=21种线样式。
有两种方法可以在线上添加标记：
- 线后标记，在线后紧接着竖线包夹着标记，如：-->|标记|、==>|标记|、-.->|标记|。
- 线中标记，如：--标记-->、==标记==>、-.标记.->。
要拉长连线，依据实线、粗实线、虚线可增加中心符号 - 、=、 .来延长。若有线中标记，拉长符号添加在标记后。
可以在同一行中串多级的连接，或是宣告多点对多点的连接。如下例子：

flowchart 21种连线、两种标记与延长线综合范例：

flowchart LR
a --- b ===c-.-d    -...-|无箭头/<br>有箭头| e  %% 使用线尾双竖线标注，线中添加线的延长字符
e-->f==>g-.->h
e<-->f<==>g<-.->h

i --o j ==o k -.-o l   -.o箭头 /<br>x箭头...- m %% 使用线中标注，标注后添加线的延长字符
i o--o j o==o k o-.-o l
m --x n ==x o -.-x p
m x--x n x==x o x-.-x p

flowchart LR
a --- b ===c-.-d    -...-|无箭头/<br>有箭头| e  %% 使用线尾双竖线标注，线中添加线的延长字符
e-->f==>g-.->h
e<-->f<==>g<-.->h

i --o j ==o k -.-o l   -.o箭头 /<br>x箭头...- m %% 使用线中标注，标注后添加线的延长字符
i o--o j o==o k o-.-o l
m --x n ==x o -.-x p
m x--x n x==x o x-.-x p

多点对多点的连接如下例：

flowchart LR
   a --> b & c--> d & e

flowchart LR
   a --> b & c--> d & e

1.4 子图表

使用以下语法添加子图表：

subgraph 子图表名称
    子图表中的描述语句...
end

子图表可以包含子图表
连线可以跨越子图表，
子图表的id也可以当节点让其他节点连线。

子图表范例：

flowchart TB
    c1-->a2
    subgraph one
    a1-->a2
    end
    subgraph two
    b1-->b2
    end
    subgraph three
    c1-->c2
    subgraph four %%子图表中的子图表
    d1-->d2
    end
    end
    one --> two %%子图表和节点、子图表的连接
    two --> c2
    three --> two

flowchart TB
    c1-->a2
    subgraph one
    a1-->a2
    end
    subgraph two
    b1-->b2
    end
    subgraph three
    c1-->c2
    subgraph four %%子图表中的子图表
    d1-->d2
    end
    end
    one --> two %%子图表和节点、子图表的连接
    two --> c2
    three --> two

1.7 添加颜色边框样式：style/linkstyle/classDef/class

用 style 描述节点的 svg 样式。使用 , 分开各个栏位。栏位是冒号 : 分开的 名称:数值 对。
- fill:#RGB :填充色
- stroke:#RGB : 线条色
- stroke-width:2px: 线条宽度
- stroke-dasharray: 5, 5 : 虚线点的显示/遮没点宽。
- color:#RGB : 前景色。RGB 可以各是 1或2位的 16进数字。
用 linkstyle 描述连线的 svg 样式。样式语法与style同。
用 classDef 可以定义一个 svg 样式类别，之后可以有多个节点使用此样式。样式语法与style同。

如：classDef className fill:#ff0,stroke:#333,stroke-width:4px;
使用时：
- 用 class 宣告（逗号区隔多个）节点采用的图形样式类别。如：
  class id4,id5 className;
- 或直接在图中节点后用 ::: 宣告使用的 class 如：
  id3:::className --> id4
当 className 为 default 时，是缺省值。可以统一图表的缺省颜色边框样式。

综合示例：

flowchart LR
    id1(Start)<-->id2(Stop) o--o id3:::className --o id4
    id3 x-.-x id5
    classDef className fill:#ff0,stroke:#333,stroke-width:4px,stroke-dasharray:3, 3;
    style id1 fill:#f9f,stroke:#333,stroke-width:4px
    style id2 fill:#bbf,stroke:#f66,stroke-width:2px,color:#fff,stroke-dasharray: 5, 5
    class id4,id5 className;
    linkStyle 0 stroke:#333,stroke-width:2px,stroke-dasharray: 6, 6

flowchart LR
    id1(Start)<-->id2(Stop) o--o id3:::className1 --o id4
    id3 x-.-x id5
    classDef className1 fill:#ff0,stroke:#333,stroke-width:4px,stroke-dasharray:3, 3;
    style id1 fill:#f9f,stroke:#333,stroke-width:4px
    style id2 fill:#bbf,stroke:#f66,stroke-width:2px,color:#fff,stroke-dasharray: 5, 5
    class id4,id5 className1;
    linkStyle 0 stroke:#333,stroke-width:2px,stroke-dasharray: 6, 6

Note：目前 typora某些形状的外观

2. 顺序图 sequenceDiagram (UML样式)

使用以下语法开始顺序图

sequenceDiagram
    [参与者1][消息线][参与者2]:消息体
    ...

例如

sequenceDiagram
    张三->>李四: 吃了吗？
    李四->>张三: 吃了

2.1 参与者

上例中的张三、李四都是参与者，上例中的语法是最简单的，也可以明显表明参与者有哪些

sequenceDiagram
    participant 参与者 1
    participant 参与者 2
    ...
    participant 简称 as 参与者 3 #该语法可以在接下来的描述中使用简称来代替参与者 3

2.2 消息线

类型	描述
`->`	无箭头的实线
`-->`	无箭头的虚线
`->>`	有箭头的实线
`-->>`	有箭头的虚线
`-x`	末端为叉的实线（表示异步）
`--x`	末端为叉的虚线（表示异步）

autonumber : 使用此参数参数，之后会在消息线上自动加上序号。

2.3 处理中

在消息线末尾增加 + ，则消息接收者进入当前消息的“处理中”状态；
在消息线末尾增加 - ，则消息接收者离开当前消息的“处理中”状态。

或者使用以下语法直接说明某个参与者进入“处理中”状态

activate 参与者

2.4 标注

语法如下

Note 位置表述 参与者: 标注文字

其中位置表述可以为

表述	含义
right of	右侧
left of	左侧
over	在当中，可以逗号 `,` 分隔横跨多个参与者

2.5 循环

语法如下

loop 循环的条件
    循环体描述语句
end

2.6 判断

alt 条件 1 描述
    分支 1 描述语句
else 条件 2 描述 # else 分支可选
    分支 2 描述语句
else ...
    ...
end

如果遇到可选的情况，即没有 else 分支的情况，使用如下语法：

opt 条件描述
    分支描述语句
end

2.7 例子

sequenceDiagram
autonumber
    participant z as 张三
    participant l as 李四

    loop 日复一日
        z->>l: 吃了吗您呐？
        l-->>z: 吃了，您呢？
        activate z
        Note over z: 想了一下
        alt 还没吃
            z-xl: 还没呢，正准备回去吃
        else 已经吃了
            z-xl: 我也吃过了，哈哈
        end
        opt 大过年的
            l-->z: 祝您新年好啊
        end
    end

渲染效果：

sequenceDiagram
autonumber
    participant z as 张三
    participant l as 李四
    loop 日复一日
        z->>+l: 吃了吗您呐？
        l-->>-z: 吃了，您呢？
        activate z
        Note over z: 想了一下
        alt 还没吃
            z-xl: 还没呢，正准备回去吃
        else 已经吃了
            z-xl: 我也吃过了，哈哈
        end
        opt 大过年的
            l-->z: 祝您新年好啊
        end
    end

3. 类图 classDiagram (UML样式)

UML的类图用于表达系统中的类或实体之间的相依关系，以及类的内容描述，是一种静态的系统关联描述。

3.1 类与类间的关系：

使用不同样式的连线符号连接两个类的名称，表示类之间的关系。

除了UML的继承、组合、聚合、关联、依赖、实现、6大关系，还有不带箭号的实现或虚线，泛指有关系（强或弱）。

3.1.1 关系样式列举：

classDiagram
classA <|-- classB : Inheritance/继承
classC *-- classD : Composition/组合
classE o-- classF : Aggregation/聚合
classG <-- classH : Association/关联
classK <.. classL : Dependency/依赖
classM <|.. classN : Realization/实现
classI -- classJ : Link(Solid)/实线连接
classO .. classP : Link(Dashed)/虚线连接

渲染效果：

classDiagram
classA <|-- classB : Inheritance/继承
classC *-- classD : Composition/组合
classE o-- classF : Aggregation/聚合
classG <-- classH : Association/关联
classK <.. classL : Dependency/依赖
classM <|.. classN : Realization/实现
classI -- classJ : Link(Solid)/实线连接
classO .. classP : Link(Dashed)/虚线连接

连线符号几乎就是用画的很好记，可以在冒号后添加连线的说明。实线:-- ，虚线：.. ，无封底箭号：< 或· > ，封底箭号： <|，或 |> ，实心棱形 *，空心棱形：o。

3.1.2 关系前后添加注脚

注脚通常是类在相互关系上可以有多的实例数。
连线前后可用双引号 " " 包含文字以添加注脚，UML的注脚样式有：
- 0..1 Zero or one
- 1 Only 1
- 0..1 Zero or One
- 1..* One or more
- * Many
- n n {where n>1}
- 0..n zero to n {where n>1}
- 1..n one to n {where n>1}

标示注脚的类关系例子：

classDiagram
classA "1" <|-- "1..n" classB : Inheritance/继承

classDiagram
classA "1" <|-- "1..n" classB : Inheritance/继承

3.2 类的内容描述

UML 类的图形分名称、变量、方法三栏。 mermaid可以有单行或多行两种描述法。也可混用单行/多行描述法。

单行描述：以类名称开头加冒号，之后的叙述就是对一个类成员的描述。类名称前方还可以用<< >>添加类的性质标记。
多行类描述：打包的类写法是：class <name>{ [lines]... } 。名称后用大括号包着的每一行都是类的一个成员的叙述，或是类的性质标记。也可用 name : statements 来为 name 类一行一行的添加成员。

3.2.1 类的成员和成员修饰符号：

UML/mermaid 对类每行描述的修饰符号：

带小括号 ( ) 的成员是类的方法，里面包着的是方法的参数。
小括号后的文字代表方法的返回值。
用曲线号 ~ ~ 包着的描述，在UML图会显示成尖括弧 < >包着，代表前方字段的类别。
每个成员行前方可以添加可见度的修饰符：+ 公开的、- 私人的、# 受保护的、~ 被包装/内部的。

3.2.2 对类的性质标记符号：

UML可以使用特定的标记 << >> 文本来注释类，就像类的元数据一样，清楚地表明其性质。

一些常见的注释示例可能是：

<<Interface>> 表示接口类
<<abstract>> 表示抽象类
<<Service>> 表示服务类
<<enumeration>> 代表一个枚举

可以在单行类宣告的最开头添加此注释，或是在模块大括号内的第一行添加类的性质注释。

也可在类宣告后的其他地方再为类添加成员，写法是 类名称: 成员描述。

3.3 类的宣告举例

类宣告样式：

classDiagram

class Square~Shape~{
        <<interface>> 
    int id
    List~int~ position
    setPoints(List~int~ points)
    getPoints() List~int~
}
%%添加messages参数，是 string型别的 List 
Square : -List~string~ messages  
%%添加setMessages方法，参数 message 是 string型别的 List 
Square : +setMessages(List~string~ messages)
%%添加getMessages方法，返回值是 string型别的 List
Square : +getMessages() List~string~   
%%对类添加随意定的 <<test_only>> 标记
<<test_only>> Square

渲染效果：

classDiagram

class Square~Shape~{
        <<interface>> 
    int id
    List~int~ position
    setPoints(List~int~ points)
    getPoints() List~int~
}
%%添加messages参数，是 string型别的 List 
Square : -List~string~ messages  
%%添加setMessages方法，参数 message 是 string型别的 List 
Square : +setMessages(List~string~ messages)
%%添加getMessages方法，返回值是 string型别的 List
Square : +getMessages() List~string~   
%%对类添加随意定的 <<test_only>> 标记
<<test_only>> Square

4.状态图 stateDiagram (UML样式)

UML的 state diagram 是状态转换图，标示着状态机的静态转换拓扑样式。
meimaid的状态图使用了v2版本。图形宣告为：stateDiagram-v2

4.1 状态

状态图的定义有很多，为了便于记忆，个人挑选了最常用的一种写法：

stateDiagram-v2
s2 : 这是状态2

渲染效果：

stateDiagram-v2
s2 : 这是状态2

:前s2是状态的ID,效果如下：

4.2 状态转换

mermaid用–>表示两个状态间的转换，比如： s1 –> s2。你也可以用:加上描述符组成转换条件：s1 –> s2 :转换，代码为：

stateDiagram-v2
s1 --> s2: A transition

渲染效果：

stateDiagram-v2
s1 --> s2: A transition

4.3 初始和终止状态

在状态转换图中，有两个特殊的状态：初始状态和终止状态(不明白这两个知识可以补习状态机相关知识)。它们是用[*]符号和–>标识的转换。

[*] --> s1，表示初始状态到s1。
s1 --> [*]，表示s1到终止状态。
代码如下：

stateDiagram-v2
[*] --> s1
s1 --> [*]

渲染效果：

stateDiagram-v2
[*] --> s1
s1 --> [*]

4.4 组合状态

在现实生活中状态复杂多变，往往具有多维性。可能在一个状态中，又有许多状态组成一个子状态机。mermaid用来表示组合状态。
代码中，先定义出总的状态机。在在每个状态中用{}定义出每个子状态机，代码如下：

stateDiagram-v2
[*] --> First
First --> Second
First --> Third

state First {
    [*] --> fir
    fir --> [*]
}
state Second {
    [*] --> sec
    sec --> [*]
}
state Third {
    [*] --> thi
    thi --> [*]
}

渲染效果：

stateDiagram-v2
[*] --> First
First --> Second
First --> Third

state First {
    [*] --> fir
    fir --> [*]
}
state Second {
    [*] --> sec
    sec --> [*]
}
state Third {
    [*] --> thi
    thi --> [*]
}

4.5 分支和连接

对于遇到分支条件或者组合条件的状态机，mermaid定义了关键字 <<fork>> 和 <<join>> 。下面例子中展示了这两个关键字的用法，先定义 <<fork>> 和 <<join>> 的状态，再进行引用定义。代码如下：

stateDiagram-v2
state fork_state <<fork>>
  [*] --> fork_state
  fork_state --> State2
  fork_state --> State3

  state join_state <<join>>
  State2 --> join_state
  State3 --> join_state
  join_state --> State4
  State4 --> [*]

渲染效果：

stateDiagram-v2
state fork_state <<fork>>
  [*] --> fork_state
  fork_state --> State2
  fork_state --> State3

  state join_state <<join>>
  State2 --> join_state
  State3 --> join_state
  join_state --> State4
  State4 --> [*]

4.6 标记

对于一些复杂状态，我们通常需要在图上进行简单说明标记。mermaid 使用了note和end note包括一个说明的起始。同时，它还用right of和left of表明标记说明的位置在状态的左边还是右边。示例代码如下：

stateDiagram-v2
    State1: The state with a note
    note right of State1
        标记重要信息
        notes.
    end note
    State1 --> State2
    note left of State2 : 在状态左边标记

渲染效果：

stateDiagram-v2
    State1: The state with a note
    note right of State1
        标记重要信息
        notes.
    end note
    State1 --> State2
    note left of State2 : 在状态左边标记

4.7 并发

对于UML中经常出现的并发状态，可以用–对组合状态中的子状态进行区分，就变成并行状态。代码示例如下：

stateDiagram-v2
    [*] --> Active %% from start to active state...

    state Active {
        [*] --> NumLockOff
        NumLockOff --> NumLockOn : EvNumLockPressed
        NumLockOn --> NumLockOff : EvNumLockPressed
        --
        [*] --> CapsLockOff
        CapsLockOff --> CapsLockOn : EvCapsLockPressed
        CapsLockOn --> CapsLockOff : EvCapsLockPressed
        --
        [*] --> ScrollLockOff
        ScrollLockOff --> ScrollLockOn : EvCapsLockPressed
        ScrollLockOn --> ScrollLockOff : EvCapsLockPressed
    }

渲染效果：

stateDiagram-v2
    [*] --> Active %% from start to active state...

    state Active {
        [*] --> NumLockOff
        NumLockOff --> NumLockOn : EvNumLockPressed
        NumLockOn --> NumLockOff : EvNumLockPressed
        --
        [*] --> CapsLockOff
        CapsLockOff --> CapsLockOn : EvCapsLockPressed
        CapsLockOn --> CapsLockOff : EvCapsLockPressed
        --
        [*] --> ScrollLockOff
        ScrollLockOff --> ScrollLockOn : EvCapsLockPressed
        ScrollLockOn --> ScrollLockOff : EvCapsLockPressed
    }

4.8 注释

注释是代码块中必不可少的，mermaid仅支持单行注释，注释符号为%%。

5 实体关系图 erDiagram（Typora目前不能画属性, StackEdit OK）

Typora的实体关系图目前添加实体属性时会渲染错误。暂时不要在 Typora 使用实体属性。

Entity Relationship Diagram，实体-关系模型（或 ER 模型）描述了特定知识领域中的相关事物。基本 ER 模型由实体类型（对感兴趣的事物进行分类）组成，并指定实体（这些实体类型的实例）之间可以存在的关系。维基百科。

请注意，ER 建模的从业者几乎总是将实体类型简称为实体。例如，CUSTOMER实体类型将简称为CUSTOMER实体。这太常见了，不建议做任何其他事情，但从技术上讲，实体是实体类型的抽象实例，这就是 ER 图所显示的 – 抽象实例，以及它们之间的关系。这就是为什么实体总是使用单数名词命名的原因。

mermaid可以渲染ER图

5.1 实体间的关系对应

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE-ITEM : contains
    CUSTOMER }|..|{ DELIVERY-ADDRESS : uses

效果：

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE-ITEM : contains
    CUSTOMER }|..|{ DELIVERY-ADDRESS : uses

实体名称通常大写，尽管对此没有公认的标准，mermaid中也不需要。

实体之间的关系由带有表示基数的结束标记的线表示。mermaid使用最流行的鱼尾纹符号。鱼尾纹直观地传达了它所连接的实体的许多实例的可能性。

5.1.1 关系语法

<first-entity> [<relationship> <second-entity> : <relationship-label>]

relationship每个语句的部分可以分解为三个子组件：

第一个实体相对于第二个实体的基数，
该关系是否赋予“子”实体身份
第二个实体相对于第一个实体的基数

实体在关系上的语法如下：

值（左）	价值（右）	意义
`\|o`	`o\|`	零或一
`\|\|`	`\|\|`	正好一个
`}o`	`o{`	零个或多个（无上限）
`}\|`	`\|{`	一项或多项（无上限）

5.2 添加实体属性（Typora失败，StackEdit可以）

ER 图可用于各种目的，从无实现细节的抽象模型到关系数据库表的物理模型。在 ER 图上包含属性定义以帮助理解实体的目的和含义是很有用的。这些不一定是详尽无遗的；通常一小部分属性就足够了。Mermaid 允许根据它们的类型和名称进行定义。

erDiagram
    CUSTOMER ||--o{ ORDER : places
    CUSTOMER {
        string name
        string custNumber
        string sector
    }
    ORDER ||--|{ LINE-ITEM : contains
    ORDER {
        int orderNumber
        string deliveryAddress
    }
    LINE-ITEM {
        string productCode
        int quantity
        float pricePerUnit
    }

效果：

Typora渲染错误：

erDiagram
    CUSTOMER ||--o{ ORDER : places
    CUSTOMER {
        string name
        string custNumber
        string sector
    }
    ORDER ||--|{ LINE-ITEM : contains
    ORDER {
        int orderNumber
        string deliveryAddress
    }
    LINE-ITEM {
        string productCode
        int quantity
        float pricePerUnit
    }

应该像这样：

属性呈现在实体框内：

erDiagram
    CAR ||--o{ NAMED-DRIVER : allows
    CAR {
        string registrationNumber
        string make
        string model
    }
    PERSON ||--o{ NAMED-DRIVER : is
    PERSON {
        string firstName
        string lastName
        int age
    }

Typora渲染错误：

erDiagram
    CAR ||--o{ NAMED-DRIVER : allows
    CAR {
        string registrationNumber
        string make
        string model
    }
    PERSON ||--o{ NAMED-DRIVER : is
    PERSON {
        string firstName
        string lastName
        int age
    }

应该是像这样：

属性的 type 和 name 值必须以字母开头，可以包含数字，连字符或下划线。除此之外，没有任何限制，也没有隐式的有效数据类型集。

其他事情

如果您希望关系标签超过一个单词，则必须在短语周围使用双引号
如果您根本不想要关系上的标签，则必须使用空的双引号字符串

5.3 造型Styling

5.3.1 配置选项

对于简单的颜色定制：

名称	用作
`fill`	填充实体或属性的背景颜色
`stroke`	描绘实体或属性的边框颜色，关系的线条颜色

5.3.2 使用的类

以下 CSS 类选择器可用于更丰富的样式：

选择器	描述
`.er.attributeBoxEven`	包含偶数行属性的框
`.er.attributeBoxOdd`	包含奇数行属性的框
`.er.entityBox`	代表实体的框
`.er.entityLabel`	实体的标签
`.er.relationshipLabel`	关系的标签
`.er.relationshipLabelBox`	关系标签周围的框
`.er.relationshipLine`	表示实体之间关系的线

6. 用户旅程图 journey

用户旅程高度详细地描述了不同用户在系统、应用程序或网站中完成特定任务所采取的具体步骤。此技术显示当前（原样）用户工作流程，并揭示未来工作流程的改进领域。

Mermaid 可以渲染用户旅程图：

6.1 语法

从 journey 关键字展开的 mermaid 程式框
然后使用title关键字及其在字符串中的值，为旅程图赋予标题。（这是可选的）
使用 section 将旅程行程分段
旅程行程

<行程名称> : <评价1～5分> : <逗号区隔的参与人员列表>

6.2 范例

journey
    title My working day
    section Go to work
      Make tea: 5: Me
      Go upstairs: 3: Me
      Do work: 1: Me, Cat
    section Go home
      Go downstairs: 5: Me
      Sit down: 5: Me

渲染如下：

journey
    title My working day
    section Go to work
      Make tea: 5: Me
      Go upstairs: 3: Me
      Do work: 1: Me, Cat
    section Go home
      Go downstairs: 5: Me
      Sit down: 5: Me

7. 甘特图 gantt

甘特图是一种条形图，用于说明项目进度和完成任何项目所需的时间。

甘特图说明项目的终端元素和摘要元素的开始日期和完成日期之间的天数。

甘特图用来图示化各个任务的状态、相依关系、关键性，可视化的安排调整整个工作的流程与时长。

7.1 图型宣告

gantt

7.2 任务语句样式：

<显示名称> :[关键任务, ] [状态 , ] [ 标记名 , ] <[after 标记名1 [标记名2 [...]] ,] ｜ [起始时间,]> <时长｜结束时间>

显示名称：显示在甘特图上的任务名称
关键任务: 可选标示 crit。任务会被标示红框。若未标示任务状态（未进行），任务颜色会用深红警示。
状态：可选项，可以是 done（完成，灰色）、active（进行中，浅蓝色）。无状态表示未进行（深蓝色）。
标记名：当会是其他任务的依赖任务时，定义标记名，让其他任务能参考到。
依赖列表：由 after 关键字开始的，以空白为间隔的标记名列表。代表这些任务完成后才能被执行。
起始时间：任务最早可能开始的时间。
时长：任务需时。数字+单位的字串。单位可以是h(时）、d (日)、 w (周)。
结束时间：任务固定的完成时间。

显示名称和 <时长｜结束时间>是必备的栏位，其他可选。

未指定依赖列表与起始时间的任务，以上一个宣告的任务为依赖任务。

7.3 其他语句样式：

dateFormat

dateFormat YYYY-MM-DD：时间轴上的时间标记样式为。。。。

title XXX

甘特图的显示名称

excludes

以空白间隔的不排班日列表。可以是 weekends, YYYY-MM-DD, 或是 sunday, monday,…等。
不接受weekday。

section

定义区段名。任务以section分群、分底色显示。

7.4 各种语法演示

gantt
    dateFormat  YYYY-MM-DD
    title       Adding GANTT diagram functionality to mermaid
    excludes    weekends
    %% (`excludes` accepts specific dates in YYYY-MM-DD format, days of the week ("sunday") or "weekends", but not the word "weekdays".)

    section A section
    Completed task            :done,    des1, 2014-01-06,2014-01-08
    Active task               :active,  des2, 2014-01-09, 3d
    Future task               :         des3, after des2, 5d
    Future task2              :         des4, after des3, 5d

    section Critical tasks
    Completed task in the critical line :crit, done, 2014-01-06,24h
    Implement parser and jison          :crit, done, after des1, 2d
    Create tests for parser             :crit, active, 3d
    Future task in critical line        :crit, 5d
    Create tests for renderer           :2d
    Add to mermaid                      :1d

    section Documentation
    Describe gantt syntax               :active, a1, after des1, 3d
    Add gantt diagram to demo page      :after a1  , 20h
    Add another diagram to demo page    :doc1, after a1  , 48h

    section Last section
    Describe gantt syntax               :after doc1, 3d
    Add gantt diagram to demo page      :20h
    Add another diagram to demo page    :48h

渲染样式如下：

gantt
    dateFormat  YYYY-MM-DD
    title       Adding GANTT diagram functionality to mermaid
    excludes    weekends monday
    %% (`excludes` accepts specific dates in YYYY-MM-DD format, days of the week ("sunday") or "weekends", but not the word "weekdays".)

    section A section
    Completed task            :done,    des1, 2014-01-06,2014-01-08
    Active task               :active,  des2, 2014-01-09, 3d
    Future task               :         des3, after des2, 5d
    Future task2              :         des4, after des3, 5d

    section Critical tasks
    Completed task in the critical line :crit, done, 2014-01-06,24h
    Implement parser and jison          :crit, done, after des1, 2d
    Create tests for parser             :crit, active, 3d
    Future task in critical line        :crit, 5d
    Create tests for renderer           :2d
    Add to mermaid                      :1d

    section Documentation
    Describe gantt syntax               :active, a1, after des1, 3d
    Add gantt diagram to demo page      :after a1  , 20h
    Add another diagram to demo page    :doc1, after a1  , 48h

    section Last section
    Describe gantt syntax               :after doc1, 3d
    Add gantt diagram to demo page      :20h
    Add another diagram to demo page    :48h

8. 饼状图 pie

8.1 语法

从pie关键字开始图表
然后使用title关键字及其在字符串中的值，为饼图赋予标题。（这是可选的）
数据部分
- 在" "内写上分区名。
- 分区名后使用:作为分隔符
- 分隔符后写上数值，最多支持2位小数——数据会以总数的百分比的形式展示在饼图中。

8.2 实例

pie
    title 为什么总是宅在家里？
    "喜欢宅" : 15
    "天气太热或太冷" : 20
    "穷" : 500

效果：

pie
    title 为什么总是宅在家里？
    "喜欢宅" : 15
    "天气太热或太冷" : 20
    "穷" : 500

9. 需求图 requirementDiagram (Typora, StackEdit 都不支持)

需求图提供了需求及其相互之间和其他文档化元素之间的联系的可视化。建模规范遵循 SysML v1.6 定义的规范。

渲染要求很简单。

    requirementDiagram

    requirement test_req {
    id: 1
    text: the test text.
    risk: high
    verifymethod: test
    }

    element test_entity {
    type: simulation
    }

    test_entity - satisfies -> test_req

Typora渲染错误：

requirementDiagram

    requirement test_req {
    id: 1
    text: the test text.
    risk: high
    verifymethod: test
    }

    element test_entity {
    type: simulation
    }

    test_entity - satisfies -> test_req

应该是像这样：

语法

需求图包含三种类型的组件：需求、元素和关系。

定义每个的语法定义如下。用尖括号表示的词，例如<word>，是列举的关键字，在表格中详细说明了选项。user_defined_...用于任何需要用户输入的地方。

关于用户文本的重要说明：所有输入都可以用引号括起来，也可以不括起来。例如，两者Id: "here is an example"和Id: here is an example都有效。但是，用户必须小心未引用的输入。如果检测到另一个关键字，解析器将失败。

要求

需求定义包含需求类型、名称、id、文本、风险和验证方法。语法如下：

<type> user_defined_name {
    id: user_defined_id
    text: user_defined text
    risk: <risk>
    verifymethod: <method>
}

Type, risk, 和 method 都在 SysML 中列举定义。

关键字	选项
type 类型	需求、功能需求、接口需求、性能需求、物理需求、设计约束
risk 风险	低、中、高
verifymethod 验证方法	分析、检验、测试、演示

元素

元素定义包含元素名称、类型和文档引用。这三个都是用户定义的。元素功能旨在轻量级，但允许将需求连接到其他文档的部分。

element user_defined_name {
    type: user_defined_type
    docref: user_defined_ref
}

关系

关系由源节点、目标节点和关系类型组成。

每个都遵循的定义格式

{name of source} - <type> -> {name of destination}

要么

{name of destination} <- <type> - {name of source}

“源名称”和“目标名称”应该是在别处定义的需求或元素节点的名称。

关系类型可以是包含、复制、派生、满足、验证、细化或跟踪之一。

每个关系都在图中进行了标记。

10. Git 图 gitGraph (Typora、StackEdit 目前支持不佳)

Typora 目前的节点标签位置不正确，暂时没有标签名称的信息。

或需要对应本地git才能得到版次信息，不是只有节点图形

gitGraph:
options
{
    "nodeSpacing": 150,
    "nodeRadius": 10
}
end
commit
branch newbranch
checkout newbranch
commit
commit
checkout master
commit
commit
merge newbranch

Typora渲染如下：（目前渲染有问题）

gitGraph:
options
{
    "nodeSpacing": 100,
    "nodeRadius": 10
}
end
commit
branch newbranch
checkout newbranch
commit
commit
checkout master
commit
commit
merge newbranch

应该表现的样式：

Git 图

HTML Table

詳見：https://www.w3school.com.cn/tags/tag_table.asp

<table border="2">
  <tr>
    <th>Month</th>
    <th>Savings</th>

  </tr>
  <tr>
    <td>January</td>
    <td>$100</td>
  </tr>
</table>

Month	Savings
January	$100

Html 可以不完整：結束標籤 </tr> 、</th>、</td> 標籤可以省略。

Month	Savings
January	$100

可选的属性

屬性在 tag中添加，如 <tr bgcolor=#FFFF00> 會讓整條 row底色都是黃色。

属性	值	描述
align	left center right	不赞成使用。请使用样式代替。规定表格相对周围元素的对齐方式。
bgcolor	rgb(x,x,x) #xxxxxx colorname	不赞成使用。请使用样式代替。规定表格的背景颜色。
border	pixels	规定表格边框的宽度。
cellpadding	pixels%	规定单元边沿与其内容之间的空白。
cellspacing	pixels%	规定单元格之间的空白。
frame	void above below hsides lhs rhs vsides box border	规定外侧边框的哪个部分是可见的。
rules	none groups rows cols all	规定内侧边框的哪个部分是可见的。
summary	text	规定表格的摘要。
width	% pixels	规定表格的宽度。

Mermaid 实用教程

Mermaid 实用教程

0. 简介

0.1 什么是Mermaid？

0.2 怎么使用Mermaid？

0.3 Mermaid能绘制哪些图？

Mermaid 基础语法：

Mermaid 图表类型：

1. 流程图 graph / flowchart

1.1 图表类型+方向

1.2 节点定义

1.3 节点间的连线

1.4 子图表

1.7 添加颜色边框样式：style/linkstyle/classDef/class

2. 顺序图 sequenceDiagram (UML样式)

2.1 参与者

2.2 消息线

2.3 处理中

2.4 标注

2.5 循环

2.6 判断

2.7 例子

3. 类图 classDiagram (UML样式)

3.1 类与类间的关系：

3.1.1 关系样式列举：

3.1.2 关系前后添加注脚

3.2 类的内容描述

3.2.1 类的成员和成员修饰符号：

3.2.2 对类的性质标记符号：

3.3 类的宣告举例

4.状态图 stateDiagram (UML样式)

4.1 状态

4.2 状态转换

4.3 初始和终止状态

4.4 组合状态

4.5 分支和连接

4.6 标记

4.7 并发

4.8 注释

5 实体关系图 erDiagram（Typora目前不能画属性, StackEdit OK）

5.1 实体间的关系对应

5.1.1 关系语法

5.2 添加实体属性（Typora失败，StackEdit可以）

其他事情

5.3 造型Styling

5.3.1 配置选项

5.3.2 使用的类

6. 用户旅程图 journey

6.1 语法

6.2 范例

7. 甘特图 gantt

7.1 图型宣告

7.2 任务语句样式：

7.3 其他语句样式：

dateFormat

title XXX

excludes

section

7.4 各种语法演示

8. 饼状图 pie

8.1 语法

8.2 实例

9. 需求图 requirementDiagram (Typora, StackEdit 都不支持)

语法

要求

元素

关系

10. Git 图 gitGraph (Typora、StackEdit 目前支持不佳)

HTML Table

可选的属性

作者

留言

撰寫回覆或留言 取消回覆

撰寫回覆或留言取消回覆