16.6 KB366 lines
Blame
1<p align="center">
2<img src="https://raw.githubusercontent.com/mermaid-js/mermaid/develop/docs/public/favicon.svg" height="150">
3</p>
4<h1 align="center">
5Mermaid
6</h1>
7<p align="center">
8通过解析类 Markdown 的文本语法来实现图表的创建和动态修改。
9<p>
10<p align="center">
11 <a href="https://www.npmjs.com/package/mermaid"><img src="https://img.shields.io/npm/v/mermaid?color=ff3670&label="></a>
12<p>
13
14<p align="center">
15<a href="https://mermaid.live/"><b>实时编辑器!</b></a>
16</p>
17<p align="center">
18 <a href="https://mermaid.js.org">📖 文档</a> | <a href="https://mermaid.js.org/intro/">🚀 入门</a> | <a href="https://www.jsdelivr.com/package/npm/mermaid">🌐 CDN</a> | <a href="https://discord.gg/sKeNQX4Wtj" title="Discord invite">🙌 加入我们</a>
19</p>
20<p align="center">
21<a href="./README.md">English</a>
22</p>
23
24<p align="center">
25尝试未来版本的实时编辑器预览: <a href="https://develop.git.mermaid.live/" title="尝试来自develop分支的mermaid版本。">Develop</a> | <a href="https://next.git.mermaid.live/" title="尝试来自next分支的mermaid版本。">Next</a>
26</p>
27
28<br>
29<br>
30
31[![NPM](https://img.shields.io/npm/v/mermaid)](https://www.npmjs.com/package/mermaid)
32[![Build CI Status](https://github.com/mermaid-js/mermaid/actions/workflows/build.yml/badge.svg)](https://github.com/mermaid-js/mermaid/actions/workflows/build.yml)
33[![npm minified gzipped bundle size](https://img.shields.io/bundlephobia/minzip/mermaid)](https://bundlephobia.com/package/mermaid)
34[![Coverage Status](https://codecov.io/github/mermaid-js/mermaid/branch/develop/graph/badge.svg)](https://app.codecov.io/github/mermaid-js/mermaid/tree/develop)
35[![CDN Status](https://img.shields.io/jsdelivr/npm/hm/mermaid)](https://www.jsdelivr.com/package/npm/mermaid)
36[![NPM Downloads](https://img.shields.io/npm/dm/mermaid)](https://www.npmjs.com/package/mermaid)
37[![Join our Discord!](https://img.shields.io/static/v1?message=join%20chat&color=9cf&logo=discord&label=discord)](https://discord.gg/sKeNQX4Wtj)
38[![Twitter Follow](https://img.shields.io/badge/Social-mermaidjs__-blue?style=social&logo=X)](https://twitter.com/mermaidjs_)
39
40<img src="./img/header.png" alt="" />
41
42:trophy: **Mermaid 被提名并获得了 [JS Open Source Awards (2019)](https://osawards.com/javascript/2019) 的 "The most exciting use of technology" 奖项!!!**
43
44**感谢所有参与进来提交 PR，解答疑问的人们! 🙏**
45
46<a href="https://mermaid.js.org/landing/"><img src="https://github.com/mermaid-js/mermaid/blob/master/docs/intro/img/book-banner-post-release.jpg" alt='Banner for "The Official Guide to Mermaid.js" book'></a>
47
48## 关于 Mermaid
49
50<!-- <Main description> -->
51
52Mermaid 是一个基于 JavaScript 的图表绘制工具，通过解析类 Markdown 的文本语法来实现图表的创建和动态修改。Mermaid 诞生的主要目的是让文档的更新能够及时跟上开发进度。
53
54> Doc-Rot 是 Mermaid 致力于解决的一个难题。
55
56绘图和编写文档花费了开发者宝贵的开发时间，而且随着业务的变更，它很快就会过期。 但是如果缺少了图表或文档，对于生产力和团队新人的业务学习都会产生巨大的阻碍。 <br/>
57Mermaid 通过允许用户创建便于修改的图表来解决这一难题，它也可以作为生产脚本（或其他代码）的一部分。<br/>
58<br/>
59Mermaid 甚至能让非程序员也能通过 [Mermaid Live Editor](https://mermaid.live/) 轻松创建详细的图表。<br/>
60你可以访问 [教程](https://mermaid.js.org/ecosystem/tutorials.html) 来查看 Live Editor 的视频教程，也可以查看 [Mermaid 的集成和使用](https://mermaid.js.org/ecosystem/integrations-community.html) 这个清单来检查你的文档工具是否已经集成了 Mermaid 支持。
61
62如果想要查看关于 Mermaid 更详细的介绍及基础使用方式，可以查看 [入门指引](https://mermaid.js.org/intro/getting-started.html), [用法](https://mermaid.js.org/config/usage.html) 和 [教程](https://mermaid.js.org/ecosystem/tutorials.html).
63
64<!-- </Main description> -->
65
66## 示例
67
68**下面是一些可以使用 Mermaid 创建的图表示例。点击 [语法](https://mermaid.js.org/intro/syntax-reference.html) 查看详情。**
69
70<table>
71<!-- <Flowchart> -->
72
73### 流程图 [<a href="https://mermaid.js.org/syntax/flowchart.html">文档</a> - <a href="https://mermaid.live/edit#base64:eyJjb2RlIjoiZ3JhcGggVERcbiAgICBBW0hhcmRdIC0tPnxUZXh0fCBCKFJvdW5kKVxuICAgIEIgLS0-IEN7RGVjaXNpb259XG4gICAgQyAtLT58T25lfCBEW1Jlc3VsdCAxXVxuICAgIEMgLS0-fFR3b3wgRVtSZXN1bHQgMl0iLCJtZXJtYWlkIjp7InRoZW1lIjoiZGVmYXVsdCJ9fQ">live editor</a>]
74
75```
76flowchart LR
77A[Hard] -->|Text| B(Round)
78B --> C{Decision}
79C -->|One| D[Result 1]
80C -->|Two| E[Result 2]
81```
82
83```mermaid
84flowchart LR
85A[Hard] -->|Text| B(Round)
86B --> C{Decision}
87C -->|One| D[Result 1]
88C -->|Two| E[Result 2]
89```
90
91### 时序图 [<a href="https://mermaid.js.org/syntax/sequenceDiagram.html">文档</a> - <a href="https://mermaid.live/edit#base64:eyJjb2RlIjoic2VxdWVuY2VEaWFncmFtXG5BbGljZS0-PkpvaG46IEhlbGxvIEpvaG4sIGhvdyBhcmUgeW91P1xubG9vcCBIZWFsdGhjaGVja1xuICAgIEpvaG4tPj5Kb2huOiBGaWdodCBhZ2FpbnN0IGh5cG9jaG9uZHJpYVxuZW5kXG5Ob3RlIHJpZ2h0IG9mIEpvaG46IFJhdGlvbmFsIHRob3VnaHRzIVxuSm9obi0tPj5BbGljZTogR3JlYXQhXG5Kb2huLT4-Qm9iOiBIb3cgYWJvdXQgeW91P1xuQm9iLS0-PkpvaG46IEpvbGx5IGdvb2QhIiwibWVybWFpZCI6eyJ0aGVtZSI6ImRlZmF1bHQifX0">live editor</a>]
92
93```
94sequenceDiagram
95Alice->>John: Hello John, how are you?
96loop HealthCheck
97 John->>John: Fight against hypochondria
98end
99Note right of John: Rational thoughts!
100John-->>Alice: Great!
101John->>Bob: How about you?
102Bob-->>John: Jolly good!
103```
104
105```mermaid
106sequenceDiagram
107Alice->>John: Hello John, how are you?
108loop HealthCheck
109 John->>John: Fight against hypochondria
110end
111Note right of John: Rational thoughts!
112John-->>Alice: Great!
113John->>Bob: How about you?
114Bob-->>John: Jolly good!
115```
116
117### 甘特图 [<a href="https://mermaid.js.org/syntax/gantt.html">文档</a> - <a href="https://mermaid.live/edit#base64:eyJjb2RlIjoiZ2FudHRcbnNlY3Rpb24gU2VjdGlvblxuQ29tcGxldGVkIDpkb25lLCAgICBkZXMxLCAyMDE0LTAxLTA2LDIwMTQtMDEtMDhcbkFjdGl2ZSAgICAgICAgOmFjdGl2ZSwgIGRlczIsIDIwMTQtMDEtMDcsIDNkXG5QYXJhbGxlbCAxICAgOiAgICAgICAgIGRlczMsIGFmdGVyIGRlczEsIDFkXG5QYXJhbGxlbCAyICAgOiAgICAgICAgIGRlczQsIGFmdGVyIGRlczEsIDFkXG5QYXJhbGxlbCAzICAgOiAgICAgICAgIGRlczUsIGFmdGVyIGRlczMsIDFkXG5QYXJhbGxlbCA0ICAgOiAgICAgICAgIGRlczYsIGFmdGVyIGRlczQsIDFkIiwibWVybWFpZCI6eyJ0aGVtZSI6ImRlZmF1bHQifX0">live editor</a>]
118
119```
120gantt
121 section Section
122 Completed :done, des1, 2014-01-06,2014-01-08
123 Active :active, des2, 2014-01-07, 3d
124 Parallel 1 : des3, after des1, 1d
125 Parallel 2 : des4, after des1, 1d
126 Parallel 3 : des5, after des3, 1d
127 Parallel 4 : des6, after des4, 1d
128```
129
130```mermaid
131gantt
132 section Section
133 Completed :done, des1, 2014-01-06,2014-01-08
134 Active :active, des2, 2014-01-07, 3d
135 Parallel 1 : des3, after des1, 1d
136 Parallel 2 : des4, after des1, 1d
137 Parallel 3 : des5, after des3, 1d
138 Parallel 4 : des6, after des4, 1d
139```
140
141### 类图 [<a href="https://mermaid.js.org/syntax/classDiagram.html">文档</a> - <a href="https://mermaid.live/edit#base64:eyJjb2RlIjoiY2xhc3NEaWFncmFtXG5DbGFzczAxIDx8LS0gQXZlcnlMb25nQ2xhc3MgOiBDb29sXG48PGludGVyZmFjZT4-IENsYXNzMDFcbkNsYXNzMDkgLS0-IEMyIDogV2hlcmUgYW0gaT9cbkNsYXNzMDkgLS0qIEMzXG5DbGFzczA5IC0tfD4gQ2xhc3MwN1xuQ2xhc3MwNyA6IGVxdWFscygpXG5DbGFzczA3IDogT2JqZWN0W10gZWxlbWVudERhdGFcbkNsYXNzMDEgOiBzaXplKClcbkNsYXNzMDEgOiBpbnQgY2hpbXBcbkNsYXNzMDEgOiBpbnQgZ29yaWxsYVxuY2xhc3MgQ2xhc3MxMCB7XG4gID4-c2VydmljZT4-XG4gIGludCBpZFxuICBzaXplKClcbn0iLCJtZXJtYWlkIjp7InRoZW1lIjoiZGVmYXVsdCJ9fQ">live editor</a>]
142
143```
144classDiagram
145Class01 <|-- AveryLongClass : Cool
146<<Interface>> Class01
147Class09 --> C2 : Where am I?
148Class09 --* C3
149Class09 --|> Class07
150Class07 : equals()
151Class07 : Object[] elementData
152Class01 : size()
153Class01 : int chimp
154Class01 : int gorilla
155class Class10 {
156 <<service>>
157 int id
158 size()
159}
160```
161
162```mermaid
163classDiagram
164Class01 <|-- AveryLongClass : Cool
165<<Interface>> Class01
166Class09 --> C2 : Where am I?
167Class09 --* C3
168Class09 --|> Class07
169Class07 : equals()
170Class07 : Object[] elementData
171Class01 : size()
172Class01 : int chimp
173Class01 : int gorilla
174class Class10 {
175 <<service>>
176 int id
177 size()
178}
179```
180
181### 状态图 [<a href="https://mermaid.js.org/syntax/stateDiagram.html">docs</a> - <a href="https://mermaid.live/edit#pako:eNpdkLsOwjAMRX-l8ojahTEDCzB26kgYrMYtkfJAqVMJVf13QiIKqqfr44d8vUDvFYGAiZHponEMaJv5KF2V4na4V01zqjrWxhSUZYapuEetn7UbCy16P_5HzwGnR6FZfpdCDZaCRa3SWcunQQI_yJIEkaSiAaNhCdKtqRUj--7lehAcItUQn-pnBMSAZtroVWn2YYOU07b4z29Y37gJVYk">live editor</a>]
182
183```
184stateDiagram-v2
185[*] --> Still
186Still --> [*]
187Still --> Moving
188Moving --> Still
189Moving --> Crash
190Crash --> [*]
191```
192
193```mermaid
194stateDiagram-v2
195[*] --> Still
196Still --> [*]
197Still --> Moving
198Moving --> Still
199Moving --> Crash
200Crash --> [*]
201```
202
203### 饼图 [<a href="https://mermaid.js.org/syntax/pie.html">文档</a> - <a href="https://mermaid.live/edit#base64:eyJjb2RlIjoicGllXG5cIkRvZ3NcIiA6IDQyLjk2XG5cIkNhdHNcIiA6IDUwLjA1XG5cIlJhdHNcIiA6IDEwLjAxIiwibWVybWFpZCI6eyJ0aGVtZSI6ImRlZmF1bHQifX0">live editor</a>]
204
205```
206pie
207"Dogs" : 386
208"Cats" : 85
209"Rats" : 15
210```
211
212```mermaid
213pie
214"Dogs" : 386
215"Cats" : 85
216"Rats" : 15
217```
218
219### Git 图 [实验特性 - <a href="https://mermaid.live/edit#base64:eyJjb2RlIjoiZ2l0R3JhcGg6XG5vcHRpb25zXG57XG4gICAgXCJub2RlU3BhY2luZ1wiOiAxNTAsXG4gICAgXCJub2RlUmFkaXVzXCI6IDEwXG59XG5lbmRcbmNvbW1pdFxuYnJhbmNoIG5ld2JyYW5jaFxuY2hlY2tvdXQgbmV3YnJhbmNoXG5jb21taXRcbmNvbW1pdFxuY2hlY2tvdXQgbWFzdGVyXG5jb21taXRcbmNvbW1pdFxubWVyZ2UgbmV3YnJhbmNoXG4iLCJtZXJtYWlkIjp7InRoZW1lIjoiZGVmYXVsdCJ9fQ">live editor</a>]
220
221### 用户体验旅程图 [<a href="https://mermaid.js.org/syntax/userJourney.html">文档</a> - <a href="https://mermaid.live/edit#pako:eNpljzEPgkAMhf9K05nFGJdbJXFiYmVpuKIncDVHL4QQ_ruHaILaqXnf63vpjLVYRoMAd4nB81R5SKNOO4ZiglFC6_wVLL3JwLU68XARUHnhTQcoqGVQJgMnAwV_5GSMj0HJhcHAcU_y7d7AYVUzOJP-ddyk3ydZGf0n66uldPqCPxWYYc-hJ2fTj_OqVqg3Tplo0mq5odhphZVfkpWiSjn5Go2GyBnGhyXl3NE1UI-moW7g5QkSoF5m">live editor</a>]
222
223```
224 journey
225 title My working day
226 section Go to work
227 Make tea: 5: Me
228 Go upstairs: 3: Me
229 Do work: 1: Me, Cat
230 section Go home
231 Go downstairs: 5: Me
232 Sit down: 3: Me
233```
234
235```mermaid
236 journey
237 title My working day
238 section Go to work
239 Make tea: 5: Me
240 Go upstairs: 3: Me
241 Do work: 1: Me, Cat
242 section Go home
243 Go downstairs: 5: Me
244 Sit down: 3: Me
245```
246
247### C4 图 [<a href="https://mermaid.js.org/syntax/c4.html">文档</a>]
248
249```
250C4Context
251title System Context diagram for Internet Banking System
252
253Person(customerA, "Banking Customer A", "A customer of the bank, with personal bank accounts.")
254Person(customerB, "Banking Customer B")
255Person_Ext(customerC, "Banking Customer C")
256System(SystemAA, "Internet Banking System", "Allows customers to view information about their bank accounts, and make payments.")
257
258Person(customerD, "Banking Customer D", "A customer of the bank, <br/> with personal bank accounts.")
259
260Enterprise_Boundary(b1, "BankBoundary") {
261
262 SystemDb_Ext(SystemE, "Mainframe Banking System", "Stores all of the core banking information about customers, accounts, transactions, etc.")
263
264 System_Boundary(b2, "BankBoundary2") {
265 System(SystemA, "Banking System A")
266 System(SystemB, "Banking System B", "A system of the bank, with personal bank accounts.")
267 }
268
269 System_Ext(SystemC, "E-mail system", "The internal Microsoft Exchange e-mail system.")
270 SystemDb(SystemD, "Banking System D Database", "A system of the bank, with personal bank accounts.")
271
272 Boundary(b3, "BankBoundary3", "boundary") {
273 SystemQueue(SystemF, "Banking System F Queue", "A system of the bank, with personal bank accounts.")
274 SystemQueue_Ext(SystemG, "Banking System G Queue", "A system of the bank, with personal bank accounts.")
275 }
276}
277
278BiRel(customerA, SystemAA, "Uses")
279BiRel(SystemAA, SystemE, "Uses")
280Rel(SystemAA, SystemC, "Sends e-mails", "SMTP")
281Rel(SystemC, customerA, "Sends e-mails to")
282```
283
284```mermaid
285C4Context
286title System Context diagram for Internet Banking System
287
288Person(customerA, "Banking Customer A", "A customer of the bank, with personal bank accounts.")
289Person(customerB, "Banking Customer B")
290Person_Ext(customerC, "Banking Customer C")
291System(SystemAA, "Internet Banking System", "Allows customers to view information about their bank accounts, and make payments.")
292
293Person(customerD, "Banking Customer D", "A customer of the bank, <br/> with personal bank accounts.")
294
295Enterprise_Boundary(b1, "BankBoundary") {
296
297 SystemDb_Ext(SystemE, "Mainframe Banking System", "Stores all of the core banking information about customers, accounts, transactions, etc.")
298
299 System_Boundary(b2, "BankBoundary2") {
300 System(SystemA, "Banking System A")
301 System(SystemB, "Banking System B", "A system of the bank, with personal bank accounts.")
302 }
303
304 System_Ext(SystemC, "E-mail system", "The internal Microsoft Exchange e-mail system.")
305 SystemDb(SystemD, "Banking System D Database", "A system of the bank, with personal bank accounts.")
306
307 Boundary(b3, "BankBoundary3", "boundary") {
308 SystemQueue(SystemF, "Banking System F Queue", "A system of the bank, with personal bank accounts.")
309 SystemQueue_Ext(SystemG, "Banking System G Queue", "A system of the bank, with personal bank accounts.")
310 }
311}
312
313BiRel(customerA, SystemAA, "Uses")
314BiRel(SystemAA, SystemE, "Uses")
315Rel(SystemAA, SystemC, "Sends e-mails", "SMTP")
316Rel(SystemC, customerA, "Sends e-mails to")
317```
318
319## 发布
320
321对于有权限的同学来说，你可以通过以下步骤来完成发布操作：
322
323更新 `package.json` 中的版本号，然后执行如下命令：
324
325```sh
326npm publish
327```
328
329以上的命令会将文件打包到 `dist` 目录并发布至 <https://www.npmjs.com>.
330
331## 相关项目
332
333- [Command Line Interface](https://github.com/mermaid-js/mermaid-cli)
334- [Live Editor](https://github.com/mermaid-js/mermaid-live-editor)
335- [HTTP Server](https://github.com/TomWright/mermaid-server)
336
337## 贡献者 [![Good first issue](https://img.shields.io/github/labels/mermaid-js/mermaid/Good%20first%20issue%21)](https://github.com/mermaid-js/mermaid/issues?q=is%3Aissue+is%3Aopen+label%3A%22Good+first+issue%21%22) [![Contributors](https://img.shields.io/github/contributors/mermaid-js/mermaid)](https://github.com/mermaid-js/mermaid/graphs/contributors) [![Commits](https://img.shields.io/github/commit-activity/m/mermaid-js/mermaid)](https://github.com/mermaid-js/mermaid/graphs/contributors)
338
339Mermaid 是一个不断发展中的社区，并且还在接收新的贡献者。有很多不同的方式可以参与进来，而且我们还在寻找额外的帮助。如果你想知道如何开始贡献，请查看 [这个 issue](https://github.com/mermaid-js/mermaid/issues/866)。
340
341关于如何贡献的详细信息可以在 [贡献指南](https://mermaid.js.org/community/contributing.html) 中找到。
342
343## 安全
344
345对于公开网站来说，从互联网上的用户处检索文本、存储供后续在浏览器中展示的内容可能是不安全的，理由是用户的内容可能嵌入一些数据加载完成之后就会运行的恶意脚本，这些对于 Mermaid 来说毫无疑问是一个风险，尤其是 mermaid 图表还包含了许多在 html 中使用的字符，这意味着我们难以使用常规的手段来过滤不安全代码，因为这些常规手段会造成图表损坏。我们仍然在努力对获取到的代码进行安全过滤并不断完善我们的程序，但很难保证没有漏洞。
346
347作为拥有外部用户的网站的额外安全级别，我们很高兴推出一个新的安全级别，其中的图表在沙盒 iframe 中渲染，防止代码中的 javascript 被执行，这是在安全性方面迈出的一大步。
348
349_很不幸的是，鱼与熊掌不可兼得，在这个场景下它意味着在可能的恶意代码被阻止时，也会损失部分交互能力_。
350
351## 报告漏洞
352
353如果想要报告漏洞，请发送邮件到 security@mermaid.live, 并附上问题的描述、复现问题的步骤、受影响的版本，以及解决问题的方案（如果有的话）。
354
355## 鸣谢
356
357来自 Knut Sveidqvist:
358
359> _特别感谢 [d3](https://d3js.org/) 和 [dagre-d3](https://github.com/cpettitt/dagre-d3) 这两个优秀的项目，它们提供了图形布局和绘图工具库！_ > _同样感谢 [js-sequence-diagram](https://bramp.github.io/js-sequence-diagrams) 提供了时序图语法的使用。 感谢 Jessica Peter 提供了甘特图渲染的灵感。_ > _感谢 [Tyler Long](https://github.com/tylerlong) 从 2017 年四月开始成为了项目的合作者。_
360>
361> _感谢越来越多的 [贡献者们](https://github.com/mermaid-js/mermaid/graphs/contributors)，没有你们，就没有这个项目的今天！_
362
363---
364
365_Mermaid 是由 Knut Sveidqvist 创建，它为了更简单的文档编写而生。_
366