之前的产品工作文档大多借助于微软大礼包,一直用着倒觉得挺舒服,对Markdown这个工具也只停留在知道的层面。两个月前换了家公司,项目团队小伙伴都是用着自己顺手的系统,mac、win、linux等,使用微软大礼包写文档,在信息流转上,就暴露出了问题,尤其是流程图。在团队大佬的提点下,开始学着用Markdown的mermaid来做流程图。

什么是Mermaid?

Mermaid是一个用于画流程图、状态图、时序图、甘特图的库,广泛集成于许多 Markdown 编辑器中。相比于VisioOmniGraffle等画流程图来说,非常轻便,与开发的信息交流平滑。由于Mermaid 集成在Markdown中,在版本迭代流程变更情况下,不需要反复去其他软件导出再更新到需求文档中,节省大量维护的时间成本。

Mermaid流程图示例

别的不多说,先上个Mermaid流程图的示例

graph LR
start((开始)) --> wakeUp[起床]
wakeUp --> timeToWork{是否到出门上班的时间点了?}
timeToWork -->|yes| setout[出门]
setout --> work[开始工作]
work --> stop((结束))
timeToWork -->|no| goOnSleep[继续睡觉]
goOnSleep --> stop

Mermaid图形必须包裹在 ```mermaid 与 ``` 之间,流程图代码示例

1
2
3
4
5
6
7
8
graph LR
start((开始)) --> wakeUp[起床]
wakeUp --> timeToWork{是否到出门上班的时间点了?}
timeToWork -->|yes| setout[出门]
setout --> work[开始工作]
work --> stop((结束))
timeToWork -->|no| goOnSleep[继续睡觉]
goOnSleep --> stop

Flowchat语法

Mermaid的Flowchat流程图是节点连线的形式形成流程图。

类型声明

流程图用Graph 关键词来声明,后面必须接上方向说明字段,如:

graph TB graph BT 分别表示从上到下和从下到上

graph LR graph RL 分别表示从左到右和从右到左

graph TDgraph TB 效果一致,表示从上到下

节点

节点概念

节点是流程图中的文本块,可以用 id 或者 id[desc] 来表示。如果 id 表示节点,节点文字为 ID;如果id[desc] 表示节点,节点文字为 DESC,如下图所示

1
2
id1
id2[desc]
graph TB
id1
id2[desc]

节点形状

节点可以不同符号组合包裹描述词来表示不同的节点形状,如:

id(desc) 圆角矩形、id((desc)) 圆形、id[desc] 矩形、id{desc} 菱形、id>desc] 右向旗帜。

graph TD
id1
id2(圆角矩形)
id3((圆形))
id4[矩形]
id5{菱形}
id6>右向旗帜形]

如果描述中存在标点符号,需要用" " 包裹起来;

Fontawesome支持

节点中可以引入font awesome 增加 ICON 作为描述,添加语法:fa:#icon class name#

fontawesome 地址:Fontawesome中文网

id1(fa:fa-twitter)id2((fa:fa-flask)) id3{fa:fa-step-forward} 示例如下图

graph TD
    id1[fa:fa-twitter 推特图标]
    id2((fa:fa-flask))
    id3{fa:fa-step-forward}

节点点击事件

流程图可以给节点绑定点击时间和js触发事件(js触发事件到现在始终还是不清楚如何使用);

点击事件绑定语法为:click nodeId “URL” ;

JS触发事件语法为:click nodeId callback Function ;

流程图示例如下图:点击B节点,新窗口打开设置好的页面;

graph LR;
    A-->B[B:新窗口打开当前页面]
    click B "../learn-mermaid"

实现代码如下:

1
2
A-->B[新窗口打开当前页面]
click B "../learn-mermaid"

连线

连线概念

连线是在流程图中,将两个节点连接起来的线。连线可以添加方向、备注等信息,增加流程图的可读性。连线的基础语法为:id1 --> id2,表示细实现从id1待箭头指向id2,如图

graph LR
id1 --> id2

连线类型

id1 --> id2 有箭头细实线、id3 --- id4 无箭头细实线、id5 -.-> id6 有箭头细虚线 、id7 -.- id8 无箭头细虚线、id9 ==> id10 有箭头粗实线、id11 === id12 无箭头粗实线,连线示例如下图:

graph TD
id1 --> id2
id3 --- id4
id5 -.-> id6
id7 -.- id8
id9 ==> id10
id11 === id12

连线备注

添加连线备注的方法有两种:连线之间添加,id1 -.我是备注.-> id2 ; 连线尾部添加,id3 -->|我是备注|id4。备注示例如下图:

graph TD
id1 -.我是备注.-> id2
id3 -->|我是备注|id4

子图

子图概念

子图是流程图中的部分流程的合集整理,可以多个子图进行嵌套。子图的实现方法是将需要作为一个合集的节点包裹在subgraph #子图名称 ... end 中,如下

1
2
3
4
5
subgraph 子图名称
id1
id2
...
end

子图展示

一个完整的子图,子图1和子图2被子图4包裹住,子图3在子图4旁边,如下图所示:

graph TB
    c1-->a2
    subgraph 4
    subgraph 1
    a1-->a2
    end
    subgraph 2
    b1-->b2
    end
    end
    subgraph 3
    c1-->c2
    end

样式

虽然Mermaid在主题中提供了系统的样式,但我们在实际使用中,为了区别个别节点或者连线,需要对节点和连线的样式做自定义操作。

节点样式

可以对节点的线框、线型、背景色、文字颜色等进行自定义,节点样式的语法为style id style1,style2,style3,...

连线样式

连线不像节点存在id,无法通过具体id来定位。Mermaid通过给连线标序号来替代id,来定位连线。第一条连线定位为linkStyle 0 ,第二条连线定位为linkStyle 1 以此类推。连线样式的语法为linkStyle 1 style1,style2,style3,...

样式示例

graph LR
    id1(Start)-->id2(Stop)
    style id1 fill:#f9f,stroke:#333,stroke-width:4px
    style id2 fill:#ccf,stroke:#f66,stroke-width:2px,stroke-dasharray: 5, 5
    linkStyle 0 stroke:green,stroke-width:2px,stroke-dasharray: 5, 5

样式表

fill: #333 //背景色

stroke: #333 //边框颜色

stroke-width: 2px //边框宽度

stroke-dasharray: 5, 5 //线框断点

总结

Mermaid是个非常优秀的流程图工具,不挑设备,文件修改流转方便,再加上可以集成到markdown中,编辑、发布简单,初用之后,就已成为我今后写产品需求文档的第一选择。等有时间了,再把Mermaid的 时序图甘特图认真学习下。