Mermaid 网页集成配置与渲染 API 使用指南从 CDN 安装到 mermaid.run 全流程实战【免费下载链接】mermaidGeneration of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown项目地址: https://gitcode.com/GitHub_Trending/me/mermaidMermaid 是一个基于 JavaScript、采用类 Markdown 语法渲染可定制图表流程图、时序图等的库——只要修改图表的文字描述就能让图随之重新渲染。本文聚焦 docs/config/usage.md 这一使用指南系统讲解如何把 Mermaid 安装并托管到自己的网页中如何通过mermaid.initialize配置安全级别、如何用mermaid.run、mermaid.render、mermaid.parse等核心 API 完成从「拿到图定义文本」到「把 SVG 插入页面」的完整集成并对照仓库源码给出实现层面的印证。阅读本文后你将能够用一行 npm 命令或 CDN 脚本把 Mermaid 嵌入任意网页根据业务场景正确选择securityLevel取值在 SPA 或动态页面里精确控制图表渲染的时机与范围利用mermaid.render把文本渲染结果含交互事件绑定接入自己的编辑器或内容管线。先选路线Live Editor、本地安装还是依赖部署对于绝大多数初次接触的用户使用官方提供的 Live Editor所见即所得的在线编辑器就足够了。不过当需要把图表能力内嵌到自己的站点或产品中时就需要在下面两种路线中二选一把 Mermaid 作为 npm 依赖安装到自己的前端工程中再在页面里渲染直接把浏览器版脚本含 ESM 版本托管到网页中作为前端运行时库使用。仓库还维护了一批由社区用户录制的视频教程可以按需参考 docs/ecosystem/tutorials.md 中的列表如果你是完全没有接入经验的入门读者建议先阅读 docs/intro/getting-started.md 中的新手指南它对本主题有更展开的讲解。CDN 引入与版本选择Mermaid 以 npm 包mermaid的形式发布官方推荐通过 CDN 直接引用浏览器版产物。最常用的 CDN 是 jsDelivr 上维护的 npm 包镜像托管页——在该页面右上角的下拉框中你可以自由切换想要使用的版本号如需固定版本可把 URL 中的版本号锁定为具体版本而不是用latest之类浮动标签。通过 CDN 引用时完整的浏览器 ES Module 产物地址形如CDN_URL/mermaidMERMAID_VERSION/dist/mermaid.esm.min.mjs其中CDN_URL是所选 CDN 的基础域名MERMAID_VERSION是你锁定的 Mermaid 版本号。后续示例统一用上述占位写法实际使用时请替换成你选定的 CDN 域名与版本。在网页中安装并托管 Mermaid方式一通过 npm 安装Mermaid 官方仓库使用 pnpm workspace 管理多包但作为用户你可以用任何一种主流包管理器把它安装进自己的项目。安装的环境要求是Node.js 16。# NPM npm install mermaid # Yarn yarn add mermaid # PNPM pnpm add mermaid安装完成后Mermaid 的 ESM 构建产物会出现在依赖目录下的dist/中dist/mermaid.esm.min.mjs、dist/mermaid.esm.mjs等供打包工具或直接以typemodule脚本引用。方式二直接在 Web 页面托管把 Mermaid 托管到一个 HTML 页面上是接入成本最低的用法。按官方使用指南只需要两个要素要素一用classmermaid的pre标签包住图定义。Mermaid 在页面加载完成后会遍历 DOM找到这些标签读取其中的文本并按对应语法渲染成 SVG。pre classmermaid graph LR A --- B B--C[fa:fa-ban forbidden] B--D(fa:fa-spinner); /pre要素二用script typemodule的 ESM import 引入 mermaid 脚本。script typemodule import mermaid from CDN_URL/mermaidMERMAID_VERSION/dist/mermaid.esm.min.mjs; /script按照以上两个步骤Mermaid 会在页面加载完成后自动定位到所有classmermaid的pre标签依据其中的图定义返回 SVG 形式的图表。从源码层面看这一自动行为在 packages/mermaid/src/mermaid.ts 中实现模块加载时如果环境中存在document与window会注册window.addEventListener(load, contentLoaded, false)对应源码约 L296-L301contentLoaded检查mermaid.startOnLoad与配置中的startOnLoad为真则调用mermaid.run()开始批量渲染。一份可保存运行的最小完整示例把下面的代码保存为 HTML 文件用任意现代浏览器打开即可看到效果请注意不要在 Internet Explorer 中使用。!doctype html html langen body pre classmermaid graph LR A --- B B--C[fa:fa-ban forbidden] B--D(fa:fa-spinner); /pre script typemodule import mermaid from CDN_URL/mermaidMERMAID_VERSION/dist/mermaid.esm.min.mjs; /script /body /html注意事项对没有设置id的 mermaid 标签Mermaid 会为它自动补一个id属性同一个页面可以同时加载多个 Mermaid 图表被处理过的元素会被打上data-processed标记重复执行run时会跳过已处理的元素因此同一个页面可以安全地多次触发渲染。关于第二、三点源码 packages/mermaid/src/mermaid.ts 中run/runThrowsErrors的实现给出了明确依据遍历候选节点时先检查element.getAttribute(data-processed)已处理则跳过否则设置该标记并渲染L175-L183渲染前会通过dedent(utils.entityDecode(txt))去除缩进并解码 HTML 实体再把结果.trim()后交给renderL186-L199这正是图定义可以写在带缩进、带实体字符的pre里的原因。更轻量的选择Tiny Mermaid如果只想要更小的包体积官方仓库还提供体积约为完整库一半的简化版 Mermaid位于 packages/tiny/README.md。精简版有以下能力取舍接入前请先确认你的图表类型不受影响不支持Mindmap 图不支持Architecture架构图不支持KaTeX 数学公式渲染不支持懒加载lazy loading。当你的页面只需要常规的流程图、时序图等能力且对首屏体积敏感时可以评估切换到 Tiny 版本。开启节点点击与富文本标签securityLevel 安全配置Mermaid 解析自不可信文本时默认会限制点击类交互功能。securityLevel自 8.2 版本引入用于设定「解析出的图表可被信任的程度」是防止恶意使用的一项重要安全改进。需要启用节点点击或标签 HTML 功能时必须先调整该配置。这里需要明确责任边界判断自己的用户群体是否可信是站点所有者site owner的责任官方文档明确鼓励你谨慎行使这一判断权。securityLevel参数一览参数描述类型必填取值securityLevel对解析图表的信任级别String否sandbox、strict、loose、antiscript四种取值的行为差异strict默认值文本中的 HTML 标签会被编码点击功能被禁用antiscript文本中的 HTML 标签被允许仅移除script元素点击功能被启用loose文本中的 HTML 标签被允许点击功能被启用sandbox所有渲染发生在一个被沙箱化的 iframe 中阻止任何 JavaScript 在页面上下文里运行。这会削弱图表的一些交互能力例如脚本、时序图中的弹窗、跳转到其他标签页/目标的链接等。需要注意该配置改变了 Mermaid 在 8.2 之前的默认行为升级到 8.2 之后除非显式修改securityLevel否则流程图中的标签会被当作标签文本编码展示、点击事件被禁用。另外sandbox级别仍处于 beta 阶段。如果你对图源文本的安全性负责可以把securityLevel设为你认为合适的值从而允许点击与标签。在 packages/mermaid/src/schemas/config.schema.yaml 的配置模式中securityLevel的默认值被定义为strict可枚举值为上述四种与文档表格完全一致同一 schema 中startOnLoad默认值为trueL248-L251这印证了「默认页面加载即自动渲染」。修改 securityLevel 的正确方式修改securityLevel必须通过调用mermaid.initialize完成mermaid.initialize({ securityLevel: loose, });为什么要强调「通过initialize」因为源码中有专门的secure 配置列表保护这一开关见 packages/mermaid/src/schemas/config.schema.yamlsecure数组默认包含securityLevel、startOnLoad、maxTextSize、suppressErrorRendering、maxEdges等键。位于该列表中的配置项只能通过mermaid.initialize调用修改图文本内的%%{init: {...}}%%指令无法覆盖它们——这能有效防止恶意图定义绕过站点的安全设置。不同 securityLevel 在渲染管线中的落地从渲染实现 packages/mermaid/src/mermaidAPI.ts 可以看到三种取值的具体代码路径sandbox渲染前判断config.securityLevel sandbox约 L503若为真则整个渲染发生在sandboxedIframe()创建的沙箱 iframe 中sandbox属性为空字符串以阻止脚本执行见 L424-L433最终通过putIntoIFrame()把 SVG 序列化后以data:text/html;charsetUTF-8;base64的 iframe 形式返回L367-L375。loose跳过 DOMPurify 清理isLooseSecurityLevel为真时不执行 sanitizeL626-L633。strict/antiscript等其余级别SVG 序列化结果会经过DOMPurify.sanitize其中放行了渲染流程必需的foreignobject标签与dominant-baseline属性DOMPURIFY_TAGS/DOMPURIFY_ATTRL69-L70。标签越界Labels out of bounds问题如果你通过 CSS 动态加载字体例如通过font-face引入的字体文件Mermaid 应当等待整个页面加载完成DOM 与资源、尤其是字体文件都就绪后再渲染。一个常见做法是把初始化放到 jQuery 的 ready 回调中$(document).ready(function () { mermaid.initialize(); });如果不这样做渲染出来的图表很可能出现标签超出边界labels out of bounds的问题。Mermaid 的默认集成正是通过window.load事件才开始渲染的见前文contentLoaded的注册逻辑这是为了避免字体度量尚未就绪就进行文字排版。如果页面 body 中存在其他字体它们可能被错误地用来代替 Mermaid 指定的字体。此时在样式表中显式指定 mermaid 文本区域的字体族是一个有效的规避手段pre.mermaid { font-family: trebuchet ms, verdana, arial; }使用 mermaid.run 精确控制渲染v10 起推荐mermaid.run是 v10 引入的 API也是处理复杂集成的首选方式。默认情况下当文档就绪后mermaid.run会被自动调用渲染所有带classmermaid的元素。如果你希望自己掌控调用时机可以执行await mermaid.run(config)自定义其行为执行mermaid.initialize({ startOnLoad: false })则能阻止mermaid.run在加载完成后被自动调用。run的入参对象RunOptions在 packages/mermaid/src/mermaid.ts 的类型定义中有完整描述querySelector默认.mermaidnodes用于直接传入节点集合设置了它则忽略querySelectorpostRenderCallback在每张图渲染后被回调suppressErrors为true时错误只记录到 console、不再抛出。场景一渲染所有匹配某个选择器的元素mermaid.initialize({ startOnLoad: false }); await mermaid.run({ querySelector: .someOtherClass, });场景二渲染传入的节点数组mermaid.initialize({ startOnLoad: false }); await mermaid.run({ nodes: [document.getElementById(someId), document.getElementById(anotherId)], }); await mermaid.run({ nodes: document.querySelectorAll(.yetAnotherClass), });nodes既可以是ArrayLike的普通数组也可以直接传入querySelectorAll返回的NodeList两种写法上方示例都已给出。场景三渲染全部.mermaid元素并抑制错误mermaid.initialize({ startOnLoad: false }); await mermaid.run({ suppressErrors: true, });源码层面run最终由runThrowsErrors执行若同时缺少nodes与querySelector会直接抛出Nodes and querySelector are both undefined找到的节点数会被记录到 debug 日志Found ${nodesToProcess.length} diagrams每个图都会生成mermaid-${...}形式的唯一 idid 是否稳定取决于deterministicIds与deterministicIDSeed配置L168-L199。因此在异步加载内容后再调用runMermaid 不会重复渲染已经带data-processed标记的旧节点这正是动态页面多次调用run的安全基础。调用 mermaid.init已废弃勿用于新代码mermaid.init在 v10 中被标记为废弃并将在未来的某个版本中移除请改用mermaid.run。它目前保留仅用于兼容旧代码。历史上mermaid.init默认在文档就绪时被调用查找所有带classmermaid的元素。如果你在 mermaid 加载完成之后又向页面追加了内容或需要更细粒度的控制可以自行调用init其参数是一个配置对象若干节点形式可以是单个节点a node一个类数组的节点集合array-like of nodes一个能定位到节点的 W3C 选择器W3C selector示例mermaid.init({ noteMargin: 10 }, .someOtherClass);或者不传配置对象、直接传 jQuery 选择结果mermaid.init(undefined, $(#someId .yetAnotherClass));在源码中init的实现packages/mermaid/src/mermaid.ts会先打印废弃警告然后把配置透传给initialize再根据nodes的不同形态构造RunOptions——字符串被解释为querySelector单个HTMLElement被包装成单元素数组其余按nodes传入run。可以看到它本质上已经是initialize run的封装。与 webpack 等打包工具配合Mermaid 对 webpack 提供完整支持你可以把mermaid作为依赖安装后用import mermaid from mermaid的方式在打包产物中按需引入。仓库内已包含 webpack 的可用演示示例参考目录 tests/webpack 下的工程含 tests/webpack/webpack.config.js 与示例入口其结构与公开的 mermaid-webpack-demo 一致适合作为脚手架参考。API 用法把渲染完全掌握在自己手里Mermaid API 的核心思想是把图定义文本作为字符串传给渲染函数渲染函数把图渲染出来并通过回调返回生成的 SVG 代码。在这种模式下图定义从哪里来比如取自页面某个textarea、渲染结果插入到页面哪里完全由站点开发者自己决定。下面这个例子展示了最基础的用法——它只是把渲染得到的 SVG 输出到 JavaScript 控制台script typemodule import mermaid from ./mermaid.esm.mjs; mermaid.initialize({ startOnLoad: false }); // Example of using the render function const drawDiagram async function () { element document.querySelector(#graphDiv); const graphDefinition graph TB\na--b; const { svg } await mermaid.render(graphDiv, graphDefinition); element.innerHTML svg; }; await drawDiagram(); /script值得说明的是mermaid.initialize({ startOnLoad: false })在这里是必须的它关闭自动渲染避免页面加载时contentLoaded抢先触发run从而保证只有你手动调用的渲染发生。在 packages/mermaid/src/mermaid.ts 中可以看到render的排队实现多次对render的调用会被推入内部executionQueue串行执行以保证渲染顺序确定、互不干扰。render最终委托给mermaidAPI.render其渲染主流程见 packages/mermaid/src/mermaidAPI.ts大致是预处理文本并应用指令配置 → 校验maxTextSize上限默认 50000 字符超出则替换为提示错误图→ 根据securityLevel决定常规渲染还是沙箱 iframe 渲染 →Diagram.fromText解析 → 注入主题/用户样式 → 调用具体图类型渲染器draw→ 序列化并按级别清理 SVG → 返回{ diagramType, svg, bindFunctions }。用 detectType 判断图类型给定一段文本可以用mermaid.detectType判断它属于哪一类图。示例如下script typemodule import mermaid from ./mermaid.esm.mjs; const graphDefinition sequenceDiagram Pumbaa-Timon:I ate like a pig. Timon-Pumbaa:Pumbaa, you ARE a pig.; try { const type mermaid.detectType(graphDefinition); console.log(type); // sequence } catch (error) { // UnknownDiagramError } /script绑定交互事件bindFunctions有时候生成的图还带有已定义的交互例如 tooltip 与 click 事件。使用 API 渲染时必须在图插入 DOM 之后再补绑这些事件。下面的示例代码摘自 mermaid 内部使用 API 时的处理流程演示了渲染时如何取得并调用绑定函数// Example of using the bindFunctions const drawDiagram async function () { element document.querySelector(#graphDiv); const graphDefinition graph TB\na--b; const { svg, bindFunctions } await mermaid.render(graphDiv, graphDefinition); element.innerHTML svg; // This can also be written as bindFunctions?.(element); using the ? shorthand. if (bindFunctions) { bindFunctions(element); } };完整流程分五步使用render调用生成图生成结束后render 把结果交给你的回调示例中即插入 SVG 的这段逻辑回调收到两个参数生成的 SVG 代码以及一个函数——该函数负责在 SVG被插入 DOM 之后绑定事件把 SVG 代码插入 DOM 进行展示调用绑定函数完成事件绑定。顺序之所以重要是因为点击、tooltip 这类交互需要依赖真实存在于文档中的 DOM 节点与事件委托关系。源码中render的返回值bindFunctions直接取自解析后数据库的diag.db.bindFunctionspackages/mermaid/src/mermaidAPI.ts内部依赖interactionDb.attachFunctions见 packages/mermaid/src/interactionDb.ts将点击/链接处理挂接到对应 SVG 上。与 marked 等 Markdown 渲染器集成Mermaid 官方文档本身就是这样把 Markdown 渲染成带图表的 HTML 的——用一个自定义的 marked 渲染器把以sequenceDiagram或graph开头的代码块改写成pre classmermaidconst renderer new marked.Renderer(); renderer.code function (code, language) { if (code.match(/^sequenceDiagram/) || code.match(/^graph/)) { return pre classmermaid code /pre; } else { return precode code /code/pre; } };另一个 CoffeeScript 版本还演示了如何判断语言标签为mermaid并只在首次出现时向生成的标记中注入一次 mermaid 脚本标签marked require marked module.exports (options) - hasMermaid false renderer new marked.Renderer() renderer.defaultCode renderer.code renderer.code (code, language) - if language is mermaid html if not hasMermaid hasMermaid true html script srcoptions.mermaidPath/script html pre classmermaidcode/pre else defaultCode(code, language) renderer两种做法的共同点是把图定义代码块转换为带有classmermaid的pre之后交给 mermaid 自身的自动渲染run即可无需针对每个代码块手动调用渲染函数。高级用法仅做语法校验而不渲染mermaid.parse(text, parseOptions)用于在不渲染图表的前提下校验图定义语法。传入一段文本字符串如果定义符合 mermaid 语法函数返回{ diagramType: string }如果定义非法且parseOptions.suppressErrors为true则返回false否则抛出错误parseError函数会在parse抛错时被调用当suppressErrors为true时不会被调用。你可以覆写它以应用特定的错误处理方式。从 packages/mermaid/src/mermaidAPI.ts 的实现看parse会先注册所有图类型再对文本做预处理与指令提取processAndSetConfigs然后Diagram.fromText完成真正的解析捕获到错误时若设置了suppressErrors则返回false否则原样抛出。同时外层mermaid.parsepackages/mermaid/src/mermaid.ts同样经过执行队列串行化并把错误转发给mermaid.parseError。下面的伪代码展示了「文本域内容变化 → 校验语法 → 合法才重新渲染」的典型实时校验场景mermaid.parseError function (err, hash) { displayErrorInGui(err); }; const textFieldUpdated async function () { const textStr getTextFromFormField(code); if (await mermaid.parse(textStr)) { reRender(textStr); } }; bindEventHandler(change, code, textFieldUpdated);这种模式非常适合构建「编辑器 实时预览」类产品先廉价校验语法通过再走完整的render渲染避免无效文本触发无意义的渲染开销。配置把参数传给 mermaid.initialize把所需的配置传给mermaid.initialize调用是官方推荐的首选配置方式。完整的配置对象清单见 docs/config/setup/README.mdmermaidAPI 配置文档。script typemodule import mermaid from ./mermaid.esm.mjs; let config { startOnLoad: true, htmlLabels: true, flowchart: { useMaxWidth: false } }; mermaid.initialize(config); /script示例中出现了三种典型配置startOnLoad控制页面加载后是否自动渲染htmlLabels控制流程图等图表是否使用 HTML 标签flowchart.useMaxWidth控制流程图是否按最大宽度缩放。你可以按需组合这些键。initialize的源码实现见 packages/mermaid/src/mermaidAPI.ts它会对用户配置做assignWithDepth深合并、把顶层fontFamily映射进themeVariables、依据theme选项合并对应主题变量最终经configApi.setSiteConfig写入站点级配置并据此设置日志级别——因此它应该在任何渲染/解析动作之前调用。已废弃的旧式配置写法下面的方式已经废弃仅因向后兼容而保留。它只支持两个参数且应被initialize替代mermaid.startOnLoadmermaid.htmlLabelsmermaid.startOnLoad true;在 packages/mermaid/src/mermaid.ts 的Mermaid对象上startOnLoad仍作为可直接赋值的公开属性存在默认值为truecontentLoaded正是读取它来决定是否在window.load后自动运行渲染但这种做法官方不推荐用于新项目请统一走initialize配置通道。附相关仓库资源速查使用指南原始文档docs/config/usage.md源稿位于 packages/mermaid/src/docs/config/usage.md配置API完整文档docs/config/setup/README.md配置 schema 与默认值packages/mermaid/src/schemas/config.schema.yaml页面集成模块run/render/parse/initialize/initpackages/mermaid/src/mermaid.ts渲染管线与安全清理实现packages/mermaid/src/mermaidAPI.ts新手入门指南docs/intro/getting-started.md精简版Tiny说明packages/tiny/README.md【免费下载链接】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），仅供参考