在 Markdown 中玩转 UML 时序图:意外发现的 js-sequence-diagrams

一、引言

最近在书写一个项目的开发记录文档的时候,突然想要加入一个 UML 时序图。

因为我都是使用 Typora 进行 Markdown 的书写的,所以习惯性的点开了 Typora 的 Markdown 帮助文档,其引导我去了这个网址:
Draw Diagrams With Markdown

在这个网页中,共介绍了 3 种图表的 Markdown 语法,如下表:

图表类型支持来源备注
Sequencejs-sequence-diagramsUML 时序图
Flowchartflowchart.js流程图
Mermaidmermaid集成的强大的图表库,支持时序图、流程图、甘特图等等

这里,因为我的需求只是想写个 UML 的时序图,因此本篇博客的重点还是介绍书写 UML 时序图的 js-sequence-diagrams。

js-sequence-diagrams 的首页非常简洁明了,网址如下(友情提示,需要科学上网,打不开也没事,我下面进行翻译):
js-sequence-diagrams

接下来,简单翻译一下 js-sequence-diagrams 首页的内容。

二、js-sequnce-diagrams:将文本转换为 UML 时序图

样例:试着编辑下我

A->小蔡: 你好
Note right of 小蔡: 小蔡正在\n思考反应
小蔡-->A: 你好吗?
小A->小蔡: 我很好,谢谢!
小A 小蔡 你好 小蔡正在 思考反应 你好吗? 我很好,谢谢! 小A 小蔡 这是标题

简介

js-sequence-diagrams 是一个简单的用 javascript 编写的库,用来将文本转换为 UML 时序图。此项目启发于 websequencediagrams.com,并且由它提供了服务端的解决方案。我们使用 Jison 去解析文本,使用 Snap.svg 去绘制图像。

示例

title: 这是标题
A->B: 正常的线
B-->C: 虚线
C->>D: 开口箭头
D-->>A: 虚线开口箭头
A B C D 正常的线 虚线 开口箭头 虚线开口箭头 A B C D 这是标题
# 这是注释
Note left of A:A 的\n 左边记录
Note right of A:A 的\n 右边记录
Note over A:A 的上面记录
Note over A,B:AB 的上面记录
A B 在 A 的 左边记录 在 A 的 右边记录 在 A 的上面记录 在 A 和 B 的上面记录 A B 这是标题
participant C
participant B
participant A
Note right of A: 列举参与者\n 你可以修改他们的顺序
C B A 列举参与者 你可以修改他们的顺序 C B A 这是标题

语法

下面这张图展示了 js-sequence-diagrams 的语法。详细语法介绍在 点击这里查看详细语法介绍 (使用了 bison 格式介绍)。

grammer

由 Railroad Diagram Generator 生成。

用法

js-sequence-diagrams 基于 Snap.svg 和 Underscore.js(或者 lodash)。你可以手动下载这些文件,也可以使用 bower install bramp/js-sequence-diagrams。

然后在代码中包含下列 HTML 代码:

<script src="webfont.js"></script>
<script src="snap.svg-min.js"></script>
<script src="underscore-min.js"></script>
<script src="sequence-diagram-min.js"></script>

然后你现在有两个选择,你可以手动解析文本:

<div id="diagram"></div>
<script>
  var diagram = Diagram.parse("A->B: Message");
  diagram.drawSVG("diagram", {theme: 'hand'});
</script>

也可以使用 jQuery 解析文本:

<div class="diagram">A->B: Message</div>
<script>
$(".diagram").sequenceDiagram({theme: 'hand'});
</script>

更多文档位于官方 README.md(https://github.com/bramp/js-sequence-diagrams/blob/master/README.md)。

三、玩转 js-sequence-diagrams

翻译完了 js-sequence-diagrams 简单的官方首页,发现 js-sequence-diagrams 的语法是真的好简单,只需要上手敲打几行代码,即可享受其带来的便利(更加惊喜的是,CSDN 博客的 Markdown 居然也支持 js-sequence-diagrams)。

让我们看着语法图总结下要点:

1. 注释

js-sequence-diagrams 的注释是使用单井号开头的。例如:

# 这是 js-sequence-diagrams 的注释

2. 参与者

我们可以列举参与者的信息,只需要使用关键词 participant:

participant actor as a
a a 这是标题

其中,我们可以使用 as 来给参与者起个简单的别名,比如这里,我们将参与者 actor 与别名 a 关联了起来,在后面的代码中要是使用到参与者的指代的时候,即可使用 a 来指代 actor。

3. 记录

我们可以在参与者的三个地方书写记录。分别是左侧、右侧和上方,分别对应额了 left of、right of 和 over 关键词。同时,使用冒号来分隔开记录位置定义和记录的内容信息。比如如下代码:

participant actor as a
note left of a: 我在 a 的左边
note right of a: 我在 a 的右边
note over a: 我在 a 的上面
a a 我在 actor 的左边 我在 actor 的右边 我在 actor 的上面 a a 这是标题

注意,这里使用了 a 作为 actor 的别名。

另外,over 是可以跨越多个参与者的上面显示的,只需要中间使用逗号隔开,比如下列代码:

participant A
participant B
note over A, B: 我在 AB 的上面
A B 我在 A 和 B 的上面 A B 这是标题

4. 参与者的信息交互

我们使用参与者的名称或者别名来标记参与者,通过 - 标记正常连线, -- 标记虚线, > 标记正常箭头, >> 标记开口箭头,这样来定义信息的交互方向。然后使用冒号隔开信息交互方向的定义与信息交互的内容:

participant A
participant B
A->B: 这是正常线正常箭头
A-->B: 这是虚线正常箭头
A->>B: 这是正常线开口箭头
A-->>B: 这是虚线开口箭头
A B 这是正常线正常箭头 这是虚线正常箭头 这是正常线开口箭头 这是虚线开口箭头 A B 这是标题

通过上述 4 个点的总结,我们就可以很轻松的写出来一个 UML 时序图了,语法是相当简单的。由于我们只是想要在 Markdown 中使用它,所以就不用再去研究它是怎么嵌入到 Html 中使用的了(感兴趣的同学可以好好研究下,应该也不难,就是调用几个 js 库而已)。

四、总结

学习了 js-sequence-diagrams,我写下来了如下的代码:

(ÒωÓױ)->包工头: 包工头,什么时候发工资啊
Note right of 包工头: (区区一根韭菜事儿那么多)
包工头-->(ÒωÓױ): 砖头搬完了吗
(ÒωÓױ)-->包工头:...
Note right of 包工头: (呵呵)
包工头-->(ÒωÓױ): 为什么平时九点不到就下班了
(ÒωÓױ)-->包工头:...
Note right of 包工头: (哼哼)
包工头-->(ÒωÓױ): 平时0点就睡觉了,很养生嘛
(ÒωÓױ)-->包工头:...
Note right of 包工头: (嘿嘿)
包工头->(ÒωÓױ): 工作不努力还想要工资?
(ÒωÓױ) 包工头 包工头,什么时候发工资啊 (区区一根韭 菜事儿那么多) 砖头搬完了吗 额... (呵呵) 为什么平时九点不到就下班了 额... (哼哼) 平时0点就睡觉了,很养生嘛 额... (嘿嘿) 工作不努力还想要工资? (ÒωÓױ) 包工头 这是标题

是不是很好玩呢 _

一起来学习 js-sequence-diagrams 吧!

Enjoy It:)

相关推荐
©️2020 CSDN 皮肤主题: 大白 设计师:CSDN官方博客 返回首页