mermaid 完整解析：一段文本变成 SVG 图的 5 站旅程

mermaid 完整解析一段文本变成 SVG 图的 5 站旅程【免费下载链接】mermaidGeneration of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown项目地址: https://gitcode.com/GitHub_Trending/me/mermaid在一个 HTML 页面里写下graph LR; A--B这样的几行文字刷新页面原文字消失了取而代之的是一张带箭头的流程图。这个文字变图的过程是 mermaid 的完整渲染链路从扫描页面到把 SVG 写回 DOM。下面沿这一段文本的旅程走一遍你既能看懂它的原理也拿到一张图不显示时往哪查的排障地图。全景概览先拿地图。整条链路只有 5 站可以用一张 mermaid 流程图表示B、C 属于输入侧把原始文本变成可解析的数据D、E 属于计算侧把数据变成图形F 属于输出侧把图形放回页面。下面按这三组逐站拆解。输入侧 · 扫描页面提取图表文本第一站在packages/mermaid/src/mermaid.ts的run()函数。它用默认选择器.mermaid找到页面上所有图表容器然后逐格处理element.setAttribute(data-processed, true); const id mermaid-${idGenerator.next()}; txt dedent(utils.entityDecode(element.innerHTML)).trim();三件事打标记、生成 id、取文本。data-processed标记决定了run()可以安全地被调用多次——已处理的元素直接跳过避免同一张图渲染两遍。dedent去掉缩进也不是审美问题而是解析器对前导空格敏感不处理就会误判结构。这一站有个容易忽略的细节id 不只是显示用的它会成为 SVG 的根 id 和临时 DOM 元素的 id后面交互绑定、错误定位都靠它。输入侧 · mermaid 如何识别图类型下一站是packages/mermaid/src/diagram-api/detectType.ts里的detectType。它先剥掉三类不算图表语法的行text text.replace(frontMatterRegex, ) .replace(directiveRegex, ) .replace(anyCommentRegex, \n);剩下的纯语法文本再交给所有已注册的检测器逐个试探第一个命中的检测器决定图类型一个都没命中就抛出UnknownDiagramError——这就是页面显示 No diagram type detected错误的来源。为什么要先剥指令和注释因为%%{init}%%这类配置行混在语法里会让检测器误判。同样关键的还有注册顺序越具体的类型越要排前面否则宽泛的检测器会抢先截胡。计算侧 · 把文本解析成图数据第三站分两步。先是preprocessDiagram把图内指令抽出来合并进全局configApi——这是%%{init}%%单图配置生效的入口然后packages/mermaid/src/Diagram.ts的Diagram.fromText完成真正的解析const { db, parser, renderer } getDiagram(type); parser.parser.yy db; await parser.parse(text);这里的设计值得停下来看Jison 解析器解析文本时并不画图它只是把节点、边、样式一条条写进db数据库对象。解析器负责记笔记绘制器之后从db里读笔记。正是这个解耦让 mermaid 可以替换布局引擎——默认布局或外部 ELK 布局读的是同一份db。计算侧 · 布局与绘制 SVG第四站在mermaidAPI.render里。它先搭好临时渲染区当securityLevel是sandbox时所有绘制都在一个沙箱 iframe 内完成否则直接在目标元素里建临时 div。随后renderer.draw(text, id, ...)执行布局计算和 SVG 绘制。这一站有两个为什么沙箱 iframe 是安全设计。标签文本里允许携带 HTMLloose级别下 HTML 会被原样渲染脚本就能执行——沙箱模式用 iframe 把它和主页面 DOM 隔开解析失败时不留白。默认行为是换一张error图把错误信息画出来红色错误图比一片空白更容易定位问题。输出侧 · SVG 写回页面最后一站回到run()element.innerHTML svg用生成的 SVG 字符串替换原始文本接着bindFunctions(element)把你在文本里声明的交互点击跳转、工具提示等绑定到 SVG 元素上。至此闭环文本进图出页面就绪。实用技巧单图配置在图开头写%%{init: {theme:dark}}%%preprocessDiagram会把它抽出并合并进configApi只影响这一张图不用改全局设置securityLevel: sandbox当你无法控制图表文本来源比如用户提交的文本时开启HTML 标签被关进 iframe防 XSS 的同时不影响正常显示deterministicIds: trueid 不再随机递增。快照测试、锚点跳转、多次渲染对比都依赖稳定的 id配合deterministicIDSeed可以完全固定。排障对照表现象链路断点解决办法提示 No diagram type detected输入侧 · mermaid 如何识别图类型检查首行的图类型关键字graph、sequenceDiagram等是否拼写正确、前面有无多余空行文本原地不动没变成图输入侧 · 扫描页面提取图表文本检查元素 class 是否为mermaid、是否调用过run()带data-processed标记的元素不会重渲页面出现红色错误图计算侧 · 把文本解析成图数据语法有误先用mermaid.parse单独校验文本按报错定位行标签里的脚本被执行、样式被改写计算侧 · 布局与绘制 SVG将securityLevel设为sandbox用 iframe 隔离 HTML每次渲染 id 都变快照对比总失败输入侧 · 扫描页面提取图表文本id 生成开启deterministicIds: true并固定 seed扫描 → 识别 → 解析 → 绘制 → 写回这就是 mermaid 全链路的全部。下一步可以克隆仓库随便改坏一个.mmd文件里的一行你会看到红色错误图正好出现在解析这一站git clone https://gitcode.com/GitHub_Trending/me/mermaid【免费下载链接】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），仅供参考