Mermaid 网页集成与运行时 API 详解：从 `＜pre class=“mermaid“＞` 到 `mermaid.run` / `render` / `parse` 的完整实战指南

Mermaid 网页集成与运行时 API 详解从pre classmermaid到mermaid.run/render/parse的完整实战指南【免费下载链接】mermaidGeneration of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown项目地址: https://gitcode.com/GitHub_Trending/me/mermaid本文基于 Mermaid 官方文档 Usage 展开系统讲解如何把 Mermaid 集成到网页中CDN / npm 两种引入方式、pre.mermaid自动渲染机制、securityLevel安全级别的取舍、v10 引入的mermaid.run编程接口以及render/detectType/parse等 API 的用法。读完并对照源码后你将能够独立完成在任意 HTML 页面中渲染多张图表、为动态生成的图表绑定点击与提示事件、在不渲染的前提下校验语法以及按需裁剪包体积。一、Mermaid 是什么从哪里获取Mermaid 是一个 JavaScript 工具使用类 Markdown 的文本语法渲染可自定义的图表、图形与可视化内容。图表描述graph definition可以随描述文本的修改而重新渲染/修改这正是图表即文本的工作方式。获取方式主要有两条路径CDN文档指向 jsDelivr 的 npm 包页面可通过页面右上角的下拉框切换不同版本。CDN 方式无需构建工具适合快速验证。npm 依赖要求Node 16支持三种包管理器# NPM npm install mermaid # Yarn yarn add mermaid # PNPM pnpm add mermaid版本提示文档示例中的 CDN 地址使用的是mermaid11版本段如dist/mermaid.esm.min.mjs而当前仓库根目录 package.json 声明的版本号为 10.2.4。落地时请按照你实际安装的目标版本选择对应的 CDN 版本号。对大多数用户而言直接用浏览器端的 Live Editormermaid.live已经足够需要嵌入自有产品时再走下面的网页集成与 API 路线。官方还整理了 Live Editor 的视频教程见 docs/ecosystem/tutorials.md。二、在网页中集成 Mermaid两个要素即可文档指出把 Mermaid 集成到网页只需要两个要素图定义放在带classmermaid的pre标签内mermaid JS 脚本以 ESM 方式通过script标签引入。pre classmermaid graph LR A --- B B--C[fa:fa-ban forbidden] B--D(fa:fa-spinner); /prescript typemodule import mermaid from https://cdn.jsdelivr.net/npm/mermaid11/dist/mermaid.esm.min.mjs; /script按照上述方式页面加载完成后Mermaid 会自动找到所有classmermaid的pre标签解析其中的图定义并以 SVG 形式替换内容。这一行为在源码中有直接对应packages/mermaid/src/mermaid.ts 中contentLoaded函数检查startOnLoad配置后调用mermaid.run()而脚本通过window.addEventListener(load, contentLoaded, false)挂载在window.load事件上——这与文档中默认集成使用window.load事件启动渲染的说明完全一致。最小完整示例以下是一个可直接保存为 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 https://cdn.jsdelivr.net/npm/mermaid11/dist/mermaid.esm.min.mjs; /script /body /html从源码看自动渲染的细节阅读 runThrowsErrors 可以确认文档未展开的几个实现细节幂等处理每个被渲染的元素会被打上data-processedtrue属性已处理的元素再次遇到时直接跳过element.getAttribute(data-processed)检查。因此run可以被重复触发而不会重复渲染。自动 ID文档提到没有id的 mermaid 标签也会被补上id源码中对应const id \mermaid-${idGenerator.next()}并支持deterministicIds/deterministicIDSeed 控制确定性编号。文本预处理取element.innerHTML后经过dedent去缩进、HTML 实体解码、br归一化再做图定义检测与渲染。三、Tiny Mermaid约一半体积的裁剪版官方提供一个体积约为完整库一半的 tiny 版本其功能裁剪记录在 packages/tiny/README.md项目说明不支持的图类型Mindmap Diagram、Architecture Diagram不支持的渲染能力KaTeX 公式渲染不支持的机制Lazy loading懒加载仅按需加载命中的图类型也就是说完整库借助懒加载首次加载更快、只加载所需图表而 tiny 版本没有该机制。README 明确建议除非有非常明确的减小包体积的理由否则应使用完整mermaid包tiny 包不通过 npm 直接安装而是面向 CDN 场景使用例如!-- 锁定主版本 -- script srchttps://cdn.jsdelivr.net/npm/mermaid-js/tiny11/dist/mermaid.tiny.js/script四、securityLevel安全级别与点击/标签能力若要启用节点上的点击事件click与 HTML 标签如 FontAwesome 图标必须先调整securityLevel。该参数设定了对解析出的图表的信任级别并限制点击功能——它是 8.2 版本作为安全改进引入的目的是防止恶意使用。文档同时强调区分可信与不可信用户群体的责任在站点所有者应审慎使用。参数描述类型必填取值securityLevel解析图表的信任级别String可选sandbox,strict,loose,antiscript四个取值的语义strict默认文本中的 HTML 标签会被转义编码点击功能被禁用antiscript文本中允许 HTML 标签仅移除script元素点击功能启用loose文本中允许 HTML 标签点击功能启用sandbox所有渲染都发生在沙盒 iframe 中脚本无法在页面上下文中执行。代价是可能妨碍图表的交互能力如脚本、序列图中的 popup、跳转其他标签页/目标的链接等。该级别在文档中仍标注为 beta。注意自 8.2 升级后若未显式修改securityLevel默认行为即 strict——flowchart 中的标签会被当作标签编码、点击被禁用。修改方式为调用mermaid.initializemermaid.initialize({ securityLevel: loose, });源码印证取值范围packages/mermaid/src/config.type.ts 中类型定义为securityLevel?: strict | loose | antiscript | sandbox与文档表格一致。sandbox 的落地机制packages/mermaid/src/rendering-util/selectSvgElement.ts 中当securityLevel sandbox时SVG 元素的选择改从#i${id}对应的 iframe 的contentDocument内进行——这正是渲染发生在沙盒 iframe 中的实现证据C4 渲染器packages/mermaid/src/diagrams/c4/c4Renderer.ts等同样按securityLevel决定取用哪个文档根节点。不可通过图内指令降权packages/mermaid/src/config.spec.ts 的测试断言表明即使图定义里通过%%init指令携带securityLevel: loose最终配置仍保持strict测试注释即// cant be changed。也就是说securityLevel只能通过宿主页面代码中的initialize设定不能被图表文本自身改写——这是一个值得注意的安全边界。五、解决标签越界字体加载时序如果使用 CSS 动态加载的字体Mermaid 应等待整个页面DOM 静态资源尤其是字体文件加载完成后再渲染否则很可能出现标签文字超出节点边界的渲染问题。传统写法是在 jQuery 的就绪回调中初始化$(document).ready(function () { mermaid.initialize(); });文档同时解释Mermaid 默认集成使用window.load事件启动渲染对应前文源码中的window.addEventListener(load, ...)而document.ready早于资源加载完成二者时序不同。另一个常见问题是页面 body 中有其他字体时节点文字可能误用页面字体而非 Mermaid 字体。文档给出的规避方案是在样式中显式指定字体pre.mermaid { font-family: trebuchet ms, verdana, arial; }六、mermaid.runv10 起的推荐编程入口mermaid.run自 v10 起加入是处理更复杂集成场景的首选方式。默认情况下mermaid.run会在文档就绪时被调用渲染所有classmermaid的元素通过mermaid.initialize({startOnLoad: false})可以阻止页面加载后的自动渲染改由自己控制时机。从源码 RunOptions 接口 看mermaid.run(options)接受四个选项选项类型说明querySelectorstring查找待渲染元素的选择器默认.mermaidnodesArrayLikeHTMLElement直接传入元素集合设置后querySelector被忽略postRenderCallback(id: string) unknown每张图渲染完成后的回调suppressErrorsboolean为true时错误仅记录到 console 而不抛出默认false文档给出的三类典型用法渲染querySelector命中的元素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), });渲染所有.mermaid元素并抑制错误mermaid.initialize({ startOnLoad: false }); await mermaid.run({ suppressErrors: true, });源码中的错误处理链run 的实现 包装了内部的runThrowsErrors发生错误时先log.error若设置了mermaid.parseError则调用它最后根据suppressErrors决定是否把错误抛给调用方并提示Use the suppressErrors option to suppress these errors。单张图的解析异常由 handleError 统一处理会尝试把 DetailedError 解包为{ str, hash }结构后回调parseError。七、mermaid.init已弃用的旧入口警告mermaid.init自 v10 起弃用将在未来版本移除请改用mermaid.run。行为上mermaid.init同样默认在文档就绪时查找所有classmermaid元素。如果页面内容在 mermaid 加载后才追加或需要更细的控制可以自行调用init参数为一个配置对象 一批节点节点本身、类数组节点集合或 W3C 选择器。文档示例mermaid.init({ noteMargin: 10 }, .someOtherClass);不带配置对象、传入 jQuery 选择结果mermaid.init(undefined, $(#someId .yetAnotherClass));源码 init 实现 印证了这一兼容逻辑先打印弃用警告log.warn(mermaid.init is deprecated. Please use run instead.)把config转交initialize再把nodes归一化为RunOptions后直接await run(runOptions)——即init本质上已降级为initializerun的语法糖。八、API 用法mermaid.render与事件绑定API 的核心思想是以字符串形式的图定义调用 render 函数由它渲染图表并回调现以 Promise 形式返回生成的 SVG。图定义由站点自己获取例如来自 textarea渲染结果放到页面任意位置完全由集成方掌控。基本渲染示例文档示例仅把 SVG 结果写入目标容器原示例中还演示了把 SVG 打到控制台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绑定交互事件bindFunctions当生成的图表包含 tooltip、click 等交互时使用 API 渲染必须把事件绑定发生在 SVG 插入 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 调用提供的回调旧 API 中称为insertSvg回调携带两个参数生成图的 SVG 代码 一个绑定函数该函数在 SVG插入 DOM 之后把事件绑定到 SVG 上把 SVG 代码插入 DOM 展示调用绑定函数完成事件绑定。从源码结构看render 的公开实现 与parse一样经过executionQueue串行队列执行Multiple calls to this function will be enqueued to run serially避免并发渲染互相干扰失败路径同样会触发mermaid.parseError回调。用mermaid.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其实现见 packages/mermaid/src/diagram-api/detectType.ts先剥离 front matter、%%{...}%%指令与注释再按注册顺序遍历各图类型的 detector第一个返回真的 detector 获胜源码注释也提醒detector 顺序很重要更具体的 detector 应放前面全部不命中时抛出UnknownDiagramError——这正是文档示例中catch分支的异常来源。九、marked 渲染器示例Markdown 管道中的 Mermaid文档提供了官方文档站点自身使用的 marked 渲染器改造方案识别sequenceDiagram/graph开头的代码块输出pre classmermaid交给 Mermaid 自动渲染其余代码块保持普通precodeconst 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 的 script 标签且仅注入一次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这类管道非常适合Markdown 文档即图表来源的场景编辑器里写代码块HTML 输出里自动出现 SVG。十、进阶不渲染的语法校验mermaid.parsemermaid.parse(text, parseOptions)只校验图定义是否合乎 Mermaid 语法不做渲染定义合法时返回{ diagramType: string }定义非法时若parseOptions.suppressErrors为true则返回false否则抛出错误抛错时会调用mermaid.parseErrorsuppressErrors为true时不调用。该函数可在应用侧覆写以按自身方式呈现错误。文档给出的元代码式完整示例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);典型应用即所见即所得编辑器输入框每次变化先parse预检通过才触发重渲染。源码层面parse 实现 同样入队串行执行并在失败时调用mermaid.parseError与文档描述的行为一致。十一、配置mermaid.initialize是唯一推荐入口把所需配置传入mermaid.initialize是配置 Mermaid 的首选方式script typemodule import mermaid from ./mermaid.esm.mjs; let config { startOnLoad: true, htmlLabels: true, flowchart: { useMaxWidth: false } }; mermaid.initialize(config); /script配置对象的完整清单见 Mermaid API 文档入口其下按config/defaultConfig/mermaid三个模块组织。已弃用的旧方式直接给 mermaid 对象赋值仅支持mermaid.startOnLoad与mermaid.htmlLabels两个参数mermaid.startOnLoad true;警告这种设置方式已弃用仅为向后兼容保留请改用initialize。需要说明的前提mermaid对象默认startOnLoad: true见 mermaid 对象初始化因此若你不打算自行调用run保持默认即可让页面加载后自动渲染。十二、构建工具支持与其他集成说明webpack文档明确 mermaid 完全支持 webpack 构建仓库中 tests/webpack 目录内含一套基于 webpack 的测试工程含webpack.config.js与最小页面可作为集成参考。多图表页面同一页面可以承载多个图定义run会遍历所有命中的节点依次渲染且通过data-processed标记保证重复调用不产生副作用。外部扩展mermaid.registerExternalDiagrams支持注册外部图类型默认懒加载lazyLoad: false时立即加载本仓库的 packages/mermaid-example-diagram 即示例扩展包getRegisteredDiagramsMetadata可返回所有已注册图类型的元数据。关键源码与文档索引内容路径本文主体文档自动生成源文件在packages/mermaid/src/docs/config/usage.mddocs/config/usage.md页面集成入口run/init/render/parse/contentLoadedpackages/mermaid/src/mermaid.ts图表类型检测packages/mermaid/src/diagram-api/detectType.tssandbox 模式的 SVG 根节点切换packages/mermaid/src/rendering-util/selectSvgElement.ts配置类型含securityLevel取值packages/mermaid/src/config.type.tssecurityLevel不可被图内 init 指令覆盖的测试packages/mermaid/src/config.spec.tsTiny 版本说明packages/tiny/README.md新手集成指南docs/intro/getting-started.md配置文档入口docs/config/setup/README.md适用前提小结run需 v10 且init在该版本中已弃用securityLevel的sandbox级别仍为 beta 且可能限制交互能力CDN 示例中的mermaid11与当前仓库根版本号 10.2.4 不同集成时以你实际引入的版本为准tiny 版本不具备懒加载与 Mindmap / Architecture / KaTeX 能力选型时注意差异。【免费下载链接】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），仅供参考