序列图
序列图是一种交互图,展示了各个过程如何相互操作以及操作的顺序。
JHL在线编辑可以渲染序列图。
代码:
sequenceDiagram
Alice->>John: Hello John, how are you?
John-->>Alice: Great!
Alice-)John: See you later!
关于节点的说明,单词 “end” 可能会破坏图表,因为JHL在线编辑语言的脚本方式。如果无法避免,必须使用括号()、引号 “” 或方括号
{},[] 来包围单词 “end”。例如:(end)、[end]、{end}。
语法
参与者
参与者可以隐式地按照本页上第一个示例中的方式进行定义。参与者或角色按照在图表源文本中出现的顺序进行渲染。有时候您可能希望以不同于它们在第一条消息中出现的顺序显示参与者。可以通过以下方式指定参与者出现的顺序:
代码:
sequenceDiagram
participant Alice
participant Bob
Alice->>Bob: Hi Bob
Bob->>Alice: Hi Alice
角色
如果您明确希望使用角色符号而不是带有文本的矩形,可以使用如下的角色语句。
代码:
sequenceDiagram
actor Alice
actor Bob
Alice->>Bob: Hi Bob
Bob->>Alice: Hi Alice
别名
角色可以有一个方便的标识符和一个描述性标签。
代码:
sequenceDiagram
participant A as Alice
participant J as John
A->>J: Hello John, how are you?
J->>A: Great!
角色的创建与销毁(v10.3.0+)
可以通过消息创建和销毁角色。为此,在消息之前添加 create 或 destroy 指令。
创建参与者 B
A --> B: 你好
create 指令支持角色/参与者的区分和别名。消息的发送者或接收者可以被销毁,但只有接收者可以被创建。
代码:
sequenceDiagram
Alice->>Bob: Hello Bob, how are you ?
Bob->>Alice: Fine, thank you. And you?
create participant Carl
Alice->>Carl: Hi Carl!
create actor D as Donald
Carl->>D: Hi!
destroy Carl
Alice-xCarl: We are too many
destroy Bob
Bob->>Alice: I agree
分组 / 方框
角色可以分组在垂直方框中。您可以使用以下符号定义颜色(如果不指定,将为透明)和/或描述性标签:
box Aqua 组描述
… 参与者 …
end
box 无描述的组
… 参与者 …
end
box rgb(33,66,99)
… 参与者 …
end
如果您的组名称是颜色,您可以强制将颜色设置为透明:
box transparent Aqua
… 参与者 …
end
sequenceDiagram
box Purple Alice & John
participant A
participant J
end
box Another Group
participant B
participant C
end
A->>J: 你好 John,你好吗?
J->>A: 很好!
A->>B: 你好 Bob,查理好吗?
B->>C: 你好 Charly,你好吗?
消息
消息可以是实线或虚线。
[参与者][箭头][参与者]:消息文本
目前支持六种类型的箭头:
->
:无箭头实线-->
:无箭头虚线->>
:有箭头实线-->>
:有箭头虚线-x
:实线末尾带交叉--x
:虚线末尾带交叉-)
:实线末尾带开放箭头(异步)--)
:虚线末尾带开放箭头(异步)
活动
可以激活和停用参与者。激活和停用可以通过专门的声明进行:
sequenceDiagram
Alice->>John: Hello John, how are you?
activate John
John-->>Alice: Great!
deactivate John
也可以通过在消息箭头末尾添加 +/- 后缀的方式进行快捷操作:
sequenceDiagram
Alice->>+John: Hello John, how are you?
John-->>-Alice: Great!
激活可以堆叠在同一参与者上。
代码:
sequenceDiagram
Alice->>+John: Hello John, how are you?
Alice->>+John: John, can you hear me?
John-->>-Alice: Hi Alice, I can hear you!
John-->>-Alice: I feel great!
注释
可以在序列图中添加注释。使用以下格式:
sequenceDiagram
participant John
Note right of John: Text in note
还可以创建跨越两个参与者的注释。
代码:
sequenceDiagram
Alice->John: Hello John, how are you?
Note over Alice,John: A typical interaction
循环
序列图中可以表示循环。使用以下符号表示:
loop 循环文本
… 语句 …
end
示例如下:
sequenceDiagram
Alice->John: Hello John, how are you?
loop Every minute
John-->Alice: Great!
end
选择分支
序列图中可以表示不同的路径选择。使用以下符号表示:
alt 描述文本
… 语句 …
else
… 语句 …
end
或者,如果存在可选的序列(没有 else):
opt 描述文本
… 语句 …
end
示例如下:
sequenceDiagram
Alice->>Bob: Hello Bob, how are you?
alt is sick
Bob->>Alice: Not so good :(
else is well
Bob->>Alice: Feeling fresh like a daisy
end
opt Extra response
Bob->>Alice: Thanks for asking
end
并行
序列图中可以显示并行发生的动作。使用以下符号表示:
par [动作 1]
… 语句 …
and [动作 2]
… 语句 …
and [动作 N]
… 语句 …
end
示例如下:
sequenceDiagram
par Alice to Bob
Alice->>Bob: Hello guys!
and Alice to John
Alice->>John: Hello guys!
end
Bob-->>Alice: Hi Alice!
John-->>Alice: Hi Alice!
关键区域
序列图中可以显示必须根据情况自动执行的操作。使用以下符号表示:
critical [必须执行的动作]
… 语句 …
option [情况 A]
… 语句 …
option [情况 B]
… 语句 …
end
示例如下:
sequenceDiagram
critical Establish a connection to the DB
Service-->DB: connect
option Network timeout
Service-->Service: Log error
option Credentials rejected
Service-->Service: Log different error
end
也可以没有任何选项:
sequenceDiagram
critical Establish a connection to the DB
Service-->DB: connect
end
这个关键区域也可以嵌套,类似于上面看到的 par 语句。
中断
可以在流程中表示中断序列(通常用于模拟异常情况)。
使用以下符号表示:
break [发生了某事]
… 语句 …
end
示例如下:
sequenceDiagram
Consumer-->>API: Book something
API-->>BookingService: Start booking process
break when the booking process fails
API-->>Consumer: show failure
end
API-->>BillingService: Start billing process
背景突出显示
可以通过提供有色的背景矩形来突出显示流程。使用以下符号表示:
颜色使用 rgb 和 rgba 语法定义。
rect rgb(0, 255, 0)
… 内容 …
end
rect rgba(0, 0, 255, .1)
… 内容 …
end
示例如下:
sequenceDiagram
participant Alice
participant John
rect rgb(191, 223, 255)
note right of Alice: Alice calls John.
Alice->>+John: Hello John, how are you?
rect rgb(200, 150, 255)
Alice->>+John: John, can you hear me?
John-->>-Alice: Hi Alice, I can hear you!
end
John-->>-Alice: I feel great!
end
Alice ->>+ John: Did you want to go to the game tonight?
John -->>- Alice: Yeah! See you there.
注释
可以在序列图中添加注释,解析器会忽略它们。注释必须独占一行,必须以 %%(双百分号)开头。注释开始后到下一个换行符之间的所有文本都会被视为注释,包括任何图表语法。
示例如下:
sequenceDiagram
Alice->>John: Hello John, how are you?
%% this is a comment
John-->>Alice: Great!
实体代码以转义字符
可以使用下面所示的语法使用实体代码转义字符。
sequenceDiagram
A->>B: I #9829; you!
B->>A: I #9829; you #infin; times more!
给出的数字是十进制的,因此 # 可以编码为 #35;。还可以使用 HTML 字符名称。
因为分号可以用来代替换行符来定义标记,所以在消息文本中使用 #59; 来包含分号。
序列号
可以在序列图的每个箭头上附加一个序列号。在将 JHL在线编辑 添加到网站时,可以进行配置,如下所示:
<script>
mermaid.initialize({ sequence: { showSequenceNumbers: true } });
</script>
也可以在图表代码中打开它:
sequenceDiagram
autonumber
Alice->>John: Hello John, how are you?
loop Healthcheck
John->>John: Fight against hypochondria
end
Note right of John: Rational thoughts!
John-->>Alice: Great!
John->>Bob: How about you?
Bob-->>John: Jolly good!
角色菜单
角色可以有弹出菜单,包含个性化的链接到外部页面。例如,如果一个角色代表一个 Web 服务,有用的链接可能包括到服务健康仪表板的链接、包含服务代码的代码库的链接,或描述服务的维基页面的链接。
通过添加一个或多个链接行来进行配置,格式如下:
link <角色>: <链接标签> @ <链接 URL>
示例如下:
sequenceDiagram
participant Alice
participant John
link Alice: Dashboard @ https://dashboard.contoso.com/alice
link Alice: Wiki @ https://wiki.contoso.com/alice
link John: Dashboard @ https://dashboard.contoso.com/john
link John: Wiki @ https://wiki.contoso.com/john
Alice->>John: Hello John, how are you?
John-->>Alice: Great!
Alice-)John: See you later!
高级菜单语法
还有一种基于 JSON 格式的高级语法。如果您熟悉 JSON 格式,那么这也是可行的。
通过添加链接行来进行配置,格式如下:
links <角色>: <JSON 格式的链接名称链接 URL 对>
示例如下:
sequenceDiagram
participant Alice
participant John
links Alice: {"Dashboard": "https://dashboard.contoso.com/alice", "Wiki": "https://wiki.contoso.com/alice"}
links John: {"Dashboard": "https://dashboard.contoso.com/john", "Wiki": "https://wiki.contoso.com/john"}
Alice->>John: Hello John, how are you?
John-->>Alice: Great!
Alice-)John: See you later!
样式设置
序列图的样式设置是通过定义一些 CSS 类来完成的。在渲染过程中,这些类从位于 src/themes/sequence.scss 的文件中提取出来。
使用的类
类 | 描述 |
---|---|
actor | 位于图表顶部的角色框的样式。 |
text.actor | 位于图表顶部角色框内文本的样式。 |
messageLine0 | 实线消息线的样式。 |
messageLine1 | 虚线消息线的样式。 |
messageText | 位于图表顶部的角色框的样式。 |
labelBox | 循环中左侧标签的样式。 |
labelText | 循环标签中文本的样式。 |
loopText | 循环框内文本的样式。 |
loopLine | 循环框中线条的样式。 |
note | 注释框的样式。 |
noteText | 注释框中文本的样式。 |
示例样式表
body {
background: white;
}
.actor {
stroke: #ccccff;
fill: #ececff;
}
text.actor {
fill: black;
stroke: none;
font-family: Helvetica;
}
.actor-line {
stroke: grey;
}
.messageLine0 {
stroke-width: 1.5;
stroke-dasharray: '2 2';
marker-end: 'url(#arrowhead)';
stroke: black;
}
.messageLine1 {
stroke-width: 1.5;
stroke-dasharray: '2 2';
stroke: black;
}
#arrowhead {
fill: black;
}
.messageText {
fill: black;
stroke: none;
font-family: 'trebuchet ms', verdana, arial;
font-size: 14px;
}
.labelBox {
stroke: #ccccff;
fill: #ececff;
}
.labelText {
fill: black;
stroke: none;
font-family: 'trebuchet ms', verdana, arial;
}
.loopText {
fill: black;
stroke: none;
font-family: 'trebuchet ms', verdana, arial;
}
.loopLine {
stroke-width: 2;
stroke-dasharray: '2 2';
marker-end: 'url(#arrowhead)';
stroke: #ccccff;
}
.note {
stroke: #decc93;
fill: #fff5ad;
}
.noteText {
fill: black;
stroke: none;
font-family: 'trebuchet ms', verdana, arial;
font-size: 14px;
}
配置
可以调整渲染序列图的边距。
这可以通过定义 JHL在线编辑.sequenceConfig 或者通过使用带有配置的 JSON 文件的 CLI 来完成。有关如何使用 CLI 的说明详见 JHL在线编辑CLI 页面。JHL在线编辑.sequenceConfig 可以设置为具有配置参数的 JSON 字符串或相应的对象。
mermaid.sequenceConfig = {
diagramMarginX: 50,
diagramMarginY: 10,
boxTextMargin: 5,
noteMargin: 10,
messageMargin: 35,
mirrorActors: true,
};