Mermaid 中文导读：从文本语法到图表渲染的核心 API、安全级别与发布流程

Mermaid 中文导读从文本语法到图表渲染的核心 API、安全级别与发布流程【免费下载链接】mermaidGeneration of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown项目地址: https://gitcode.com/GitHub_Trending/me/mermaid本文基于 Mermaid 仓库的官方中文 READMEREADME.zh-CN.md整理系统讲解 Mermaid 的核心理念用类 Markdown 文本语法绘制图表以对抗 Doc-Rot、八类典型图表的完整语法示例、securityLevel安全过滤机制的源码实现证据以及版本发布流程。读完后你可以直接复制文中的语法示例进行图表创作并从源码层面理解 Mermaid 如何对不可信文本做安全处理。一、Mermaid 是什么解决 Doc-Rot 的文本绘图方案Mermaid 是一个基于 JavaScript 的图表绘制工具通过解析类 Markdown 的文本语法来实现图表的创建和动态修改。它诞生的主要目的是让文档的更新能够及时跟上开发进度——README 将这一问题称为Doc-Rot文档腐化Doc-Rot 是 Mermaid 致力于解决的一个难题。绘图和编写文档花费了开发者宝贵的时间而且随着业务变更它很快就会过期但如果缺少图表或文档对生产力和团队新人的业务学习都会造成巨大阻碍。Mermaid 的解决思路是图表以纯文本形式提交在代码库中修改成本极低可以随代码一起评审和演进图表可以作为生产脚本或其他代码的一部分来生成和渲染非程序员也能通过 Mermaid Live Editor在线编辑器轻松创建详细图表。README 同时指出可以查阅 入门指引、用法文档 与 教程 了解更详细的基础使用方式。Mermaid 还曾获得 JS Open Source Awards (2019) 的 The most exciting use of technology 奖项README 原文记载。二、支持的图表类型与完整语法示例README 的“示例”章节展示了 Mermaid 可创建的多类图表每类均配有可直接运行的语法代码。以下完整继承这些示例并在各小节标注仓库中对应的语法文档路径以便深入查阅。2.1 流程图Flowchart语法文档见 docs/syntax/flowchart.md要点说明flowchart LR声明图方向为从左到右LR也可用 TB/RL 等A[Hard]中方括号定义矩形节点B(Round)圆括号定义圆角节点C{Decision}花括号定义决策菱形--|Text|中管道符内为边上的标签文本。2.2 时序图Sequence Diagram语法文档见 docs/syntax/sequenceDiagram.md要点说明-为实线箭头同步消息--为虚线箭头返回消息loop ... end表示循环片段Note right of John: ...在参与者右侧添加注释。2.3 甘特图Gantt语法文档见 docs/syntax/gantt.md要点说明section划分任务分组:done, des1, 2014-01-06,2014-01-08依次为状态done 表示已完成、任务 id、起止日期after des1, 1d表示前置任务依赖与相对时长适合表达并行任务链。2.4 类图Class Diagram语法文档见 docs/syntax/classDiagram.md要点说明|--表示泛化继承关系--*表示聚合--|表示实现/依赖变体Interface与service是 UML 构造型标注Class : member单行书写与class Name { ... }块状书写均可声明成员。2.5 状态图State Diagram语法文档见 docs/syntax/stateDiagram.md要点说明[*]是起始/终止伪状态箭头描述状态迁移路径。2.6 饼图Pie语法文档见 docs/syntax/pie.md引号内为扇区标签冒号后为数值比例由渲染时自动计算。2.7 用户体验旅程图User Journey语法文档见 docs/syntax/userJourney.md要点说明title为图标题section划分阶段每个任务行的格式为任务名: 满意度评分: 参与人评分通常使用 1–5 分制。2.8 C4 图架构上下文图语法文档见 docs/syntax/c4.md。C4 图用统一语法描述 Person、System、SystemDb、SystemQueue 等元素及其边界Boundary要点说明元素构造函数形如Person(id, label, description)_Ext后缀表示外部Enterprise Boundary 之外实体Enterprise_Boundary、System_Boundary、Boundary支持嵌套分组Rel与BiRel声明单向/双向关系可选携带协议等附加说明如 SMTP。2.9 Git 图实验特性README 将 Git 图标注为实验特性用于以文本方式绘制分支与合并历史。仓库中 Git 图的端到端测试素材位于 e2e/diagrams/gitgraph/ 目录可作为真实语法的补充参考。三、核心 APIinitialize、run 与 renderREADME 将“如何调用”的细节指向官方用法文档仓库内的实现可以印证其核心调用链。从源码结构看主 API 定义在 packages/mermaid/src/mermaid.tsinitialize(config)该文件 L222 附近传入全局配置对象主题、securityLevel 等render(id, text, container)L409 附近将一段图表定义文本渲染为 SVG返回{ svg, bindFunctions }是脚本化生成图表的入口run()遍历页面中符合查询选择器默认.mermaid的节点并逐个渲染对应startOnLoad开关——从mermaid.ts的默认导出对象可以看到startOnLoad: trueL472 附近是默认值即引入 Mermaid 后页面加载时自动渲染早期的init(config)已标记为废弃官方建议改用initializerun的组合。配置项的类型定义集中在 packages/mermaid/src/config.type.ts例如securityLevel的类型签名为/** * Level of trust for parsed diagram */ securityLevel?: strict | loose | antiscript | sandbox;这说明安全级别是全局配置的一部分在initialize时即可生效。四、安全机制securityLevel 与沙盒 iframeREADME 的“安全”章节指出一个现实风险公开网站从用户处获取文本并在浏览器中展示时恶意内容可能嵌入脚本而 Mermaid 图表本身就包含大量 HTML 字符常规过滤手段容易损坏图表因此项目一直在持续完善安全过滤。对拥有外部用户的网站官方推出了沙盒sandbox级别图表在沙盒 iframe 中渲染阻止其中的 JavaScript 被执行——“很不幸的是鱼与熊掌不可兼得在这个场景下它意味着在可能的恶意代码被阻止时也会损失部分交互能力”。仓库源码印证了这一机制的分层实现文本净化层。在 packages/mermaid/src/diagrams/common/common.ts 中removeScript基于 DOMPurify 移除 script 标签而sanitizeMore则根据config.securityLevel分档处理const level config.securityLevel; if (level antiscript || level strict || level sandbox) { text removeScript(text); // 严格净化移除脚本标签 } else if (level ! loose) { text breakToPlaceholder(text); text text.replace(//g, lt;).replace(//g, gt;); text text.replace(//g, equals;); text placeholderToBreak(text); // 转义 HTML 特殊字符 }从源码结构看loose级别保留最多 HTML 能力strict/antiscript/sandbox都会进入 DOMPurify 净化路径sandbox在此基础上再叠加 iframe 隔离。端到端验证层。仓库 e2e/platform/ 目录下提供了不同安全级别的行为验证页面click_security_strict.html、click_security_loose.html、click_security_sandbox.html用于分别验证各模式下交互与脚本行为。选型建议基于 README 与上述源码事实内容完全可信自有文档站可用loose保留完整交互内容来自半可信用户推荐strict或antiscript内容来自任意外部用户且网站面向公众使用sandbox接受交互能力受限换取隔离保障。报告漏洞README 说明如需报告漏洞请发送邮件至 securitymermaid.live并附上问题描述、复现步骤、受影响版本以及如有解决方案。五、版本与发布流程README 的“发布”章节描述了维护者的发布步骤npm publish即先更新package.json中的版本号再执行npm publish该命令会将文件打包到dist目录并发布至 npm。结合 packages/mermaid/package.json 可以核实发布产物的具体形态当前仓库版本为11.17.0模块入口为./dist/mermaid.core.mjsmodule字段类型声明为./dist/mermaid.d.ts因此消费方通过import mermaid from mermaid获得的正是发布时打包进dist的产物prepublishOnly脚本为pnpm docs:verify-version说明发布前会自动校验文档中的版本号与 package.json 一致避免文档与实际版本脱节——这正好呼应了项目对抗 Doc-Rot 的初衷依赖项中包含d3、mermaid-js/parserworkspace 内的 Langium 解析器包等从 packages/parser/ 目录可以看到新一代语法解析器基于 Langium 实现各图表类型flowchart、sequence、class 等的语法规范文件位于 packages/parser/src/。对于使用者而言版本能力与兼容性应以实际引入的 npm 版本为准仓库 docs/ 目录提供了完整的配置项文档如 docs/config/configuration.md、docs/config/theming.md可作为升级配置时的对照依据。六、生态、相关项目与致谢README 列出的相关项目此处按仓库要求不附外部链接仅说明其定位Command Line Interfacemermaid-cli将 Mermaid 图表渲染为图片的命令行工具适合 CI 场景Live Editormermaid-live-editor在线实时编辑器非程序员的主要创作入口HTTP Servermermaid-server以 HTTP 服务形式提供图表渲染。致谢部分引自 Knut Sveidqvist 的原文特别感谢了 d3 与 dagre-d3 两个图形布局/绘图库、js-sequence-diagram 的时序图语法、Jessica Peter 提供的甘特图渲染灵感以及自 2017 年四月起参与项目的 Tyler Long 和全体贡献者。项目末尾的落款点明了其定位Mermaid 是由 Knut Sveidqvist 创建它为了更简单的文档编写而生。小结Mermaid 用“类 Markdown 文本 浏览器端渲染”的方式解决图表文档腐化问题覆盖流程图、时序图、甘特图、类图、状态图、饼图、旅程图、C4 架构图等类型语法示例均可直接复制运行调用侧围绕initialize/run/render三个 API 展开startOnLoad默认为 true页面加载即自动渲染securityLevel提供strict/loose/antiscript/sandbox四档信任级别源码中对应 DOMPurify 净化与 iframe 沙盒两条防线并在 e2e 目录中有针对性验证发布流程为更新版本号后执行npm publish产出dist/mermaid.core.mjs发布前有文档版本号一致性校验。【免费下载链接】mermaidGeneration of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown项目地址: https://gitcode.com/GitHub_Trending/me/mermaid创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考