Mermaid 新图表类型开发指南从文法解析、渲染器到类型检测的完整流程【免费下载链接】mermaidGeneration of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown项目地址: https://gitcode.com/GitHub_Trending/me/mermaid本文基于 Mermaid 仓库中官方的开发者指南 新增图表文档 编写讲解在 Mermaid 中添加一个全新图表类型diagram/chart的标准流程使用 Chevrotain 编写词法/语法分析器、编写渲染器、在detectType中注册类型检测、实现无障碍accessibility与主题theming集成并通过mermaid-js/examples包提供示例。读完后你将掌握 Mermaid 图表扩展机制的完整调用链能够以 usecase 图usecase-beta作为参考实现来设计并落地自己的新图表模块。整体流程概览Mermaid 官方将新增图表的工作拆为三大步骤外加一组所有图表都应遵循的通用能力约定Step 1: Grammar Parsing文法与解析——使用 Chevrotain 编写词法器lexer、CstParser与 CST visitor构建图表数据模型Step 2: Rendering渲染——编写渲染器根据解析出的数据渲染出 SVGStep 3: Detection of the new diagram type类型检测——在diagram-api/detectType.ts的注册体系中登记检测器返回作为aria-roledescription使用的类型键Common parts通用能力——Directives图内配置指令、Accessibility无障碍标题/描述、Themes主题、Comments注释规范需要在各图表间保持行为一致。官方特别指出把文法放在图表自己的目录之下mirrors the existing JISON layout这样图表保持自包含self-contained解析器也无需从独立包发布。Step 1文法与解析Grammar Parsing官方指南明确新图表的文法应使用 Chevrotain并与图表本身共置于packages/mermaid/src/diagrams/diagram/parser/目录下。usecase 图usecase-beta是官方指定的参考实现其目录结构正是标准范式usecase.lexer.ts——词法器lexerusecase.parser.ts——CstParser语法定义usecase.visitor.ts——CST visitor遍历 CST 构建图表模型usecase.tokens.ts——词法 token 定义usecaseModelBuilder.ts 与 usecaseJson.ts——模型构建与 JSON 转换。共享入口runChevrotainParse所有 Chevrotain 图表共享 runChevrotainParse.ts 中的runChevrotainParse函数来运行lexer/parser 对并以带源码位置的错误报告解析失败。从源码结构看它的工作流程是interface ChevrotainParseConfig { diagramType: string; lexer: Lexer; parser: CstParser; entry: () CstNode; visit: (cst: CstNode) void; }调用lexer.tokenize(input)分词若lexResult.errors非空立即抛出携带行/列与字符区间[start,end)的Error——源码注释特别说明词法失败不会出现在parser.errors中因此必须在词法阶段就附加位置信息保证两种失败模式lexing/parsing报告相同的字段将 tokens 交给 parserconfig.parser.input lexResult.tokens执行入口规则config.entry()得到 CST若parser.errors非空则抛出解析错误最后调用config.visit(cst)即由图表自己的 visitor 把 CST 转成数据模型。参考实现细节usecase 的 CstParserusecase.parser.ts 展示了一个典型的 Chevrotain 图表解析器应包含的要素单例模式export const usecaseParser new UsecaseParser()词法器的构造与校验、语法的performSelfAnalysis()都只在模块加载时执行一次入口规则start规则消费Usecase关键字对应文法中的usecase-beta声明头随后循环消费若干line行级分发line规则通过OR分派到blankLine/commentLine/statement并使用GATE门控如isStatementStart()提前排除空行、注释与 EOF提高回溯效率语句级分发statement规则按优先级OR匹配accTitleStatement、accDescrStatement、directionStatement、actorStatement、systemBoundaryStatement、noteStatement、jsonStatement、classDefStatement、classStatement、styleStatement、元数据赋值、实体声明等——可见无障碍标题/描述、classDef/class/style等通用能力正是在文法层被统一支持的nodeLocationTracking: full构造CstParser时开启了完整的节点位置追踪使 visitor 能把 CST 节点回溯到源码区间。词法器本身非常薄——usecase.lexer.ts 只有一行export const usecaseLexer new Lexer(usecaseLexerModes);token 与 lexer mode 的定义集中在usecase.tokens.ts中。解析行为由配套测试覆盖例如 usecase.parser.spec.ts、usecase.lexer.spec.ts 与 usecaseJson.spec.ts新图表开发时同样应提供解析器、词法器与 JSON 输出三层的规格测试。现存的其他文法技术栈Langium 与 JISON指南同时说明了几种历史技术栈的现状部分现有图表使用 Langium 文法位于 packages/parser 包中包括 architecture、gitGraph、info、packet、pie、radar、treemap更老的图表使用 JISON文法仓库中可见 18 个.jison文件如 docs/community/new-diagram-jison.md 专门讲 JISON 文法的写法。两者的定位都仍受支持——遇到 bug 应就地修改modify them in place而不是重写但都不是新工作的目标。新图表一律采用 Chevrotain 方案使解析器与图表共置、无需独立发包。Step 2渲染器Rendering解析阶段产出的数据需要由渲染器转换为 SVG。官方建议的参考对象是时序图渲染器sequenceRenderer而不是流程图渲染器因为时序图渲染器是更通用的示例more generic example。要点渲染器接收解析阶段构建的数据模型作为输入渲染器文件应放在该图表自己的目录下如 usecaseRenderer.ts由图表入口模块如 usecaseDiagram.ts组合 db、解析器与渲染器并导出统一的diagram对象usecase 目录下的 usecase.spec.ts 与 usecaseRenderer.spec.ts 展示了如何对渲染结果做单测断言可作为新图表渲染测试的样板。Step 3新图表类型的检测Detection检测机制位于 detectType.ts。该模块维护一个detectors注册表detectType(text, config)会先剥掉 front-matter、%%init之类的 directive 与注释再按注册顺序遍历各图表的检测器第一个返回真值truthy的键即被认定为图表类型全部失败则抛出UnknownDiagramError。注册通过两个函数完成registerLazyLoadedDiagrams(...diagrams)——批量注册懒加载图表每个条目是{ id, detector, loader }结构addDetector(key, detector, loader)——单个注册键冲突时给出 warn 并覆盖。源码注释特别强调检测器的顺序很重要第一个返回true的检测器决定加载哪个图表因此更具体的检测器必须放在前面。以 usecase 为例usecaseDetector.ts 展示了标准写法const id usecase; const detector: DiagramDetector (txt) { return /^\s*usecase-beta(?:\s|$)/.test(txt); }; const loader: DiagramLoader async () { const { diagram } await import(./usecaseDiagram.js); return { id, diagram }; }; export const usecase: ExternalDiagramDefinition { id, detector, loader, };可以看到三件事检测器用文件起始处的关键字正则识别图表类型usecase-beta后必须跟空白或行尾loader用await import(...)异步加载图表模块实现按需加载——图表代码只有在其类型被检测到时才进入运行时最后导出符合ExternalDiagramDefinition接口的对象交由注册流程登记。类型键key的选取原则指南对检测返回的 key 提出了专门要求因为它会被用作 SVG 的aria-roledescription所以必须是一个能清晰描述图表类型的词。官方给出的正误对照键示例是否合格原因UMLDeploymentDiagram推荐读屏软件会读作 U-M-L Deployment diagramdeploymentDiagram推荐读屏读作 Deployment Diagram描述充分deployment不合格不足以描述图表类型另外注意类型 key 不必与文法中选择的图表关键字完全相同但相同会更有帮助。图表的通用能力Common PartsMermaid 致力于让不同类型的图表对最终用户尽可能相似地工作。指南列出了四类所有新图表都应支持的通用能力其中后三类的实现方式在源码中有明确的公共模块支撑。Accessibility无障碍Mermaid 会为图表的 SVG 元素自动附加以下无障碍信息aria-roledescription——自动设置为 detectType 检测到的图表类型键并插入 SVG 元素其含义遵循 W3C ARIA 标准中aria-roledescription的定义accessible title / accessible description——作者可通过 Mermaid 文本提供额外的标题与描述供读屏用户理解图表内容。指南指向了 docs/config/accessibility.md 中无障碍标题/描述的具体语法。设置与读取这些信息的函数由公共模块commonDb提供在流程图数据库flowDb.js中的导入方式即新图表应采用的方式import { setAccTitle, getAccTitle, getAccDescription, setAccDescription, clear as commonClear, } from ../../commonDb;无障碍标题与描述会在 mermaidAPI 的render函数中被插入 SVG 元素。也就是说图表自身只需在解析时调用setAccTitle/setAccDescription把值存入 commonDb最终注入 DOM 的工作由公共渲染管线统一完成——这是图表保持自包含、通用能力由公共层收口的典型设计。Theming主题Mermaid 支持主题并内置主题引擎面向用户的使用说明见 docs/config/theming.md。为图表接入主题需要在几个关键位置落代码样式引擎入口 src/styles.tsgetStyles函数在 Mermaid 应用样式时被调用它转而调用你的图表提供的返回 CSS 的函数图表目录下提供自己的getStyles按惯例放在src/diagrams/yourDiagram/下文件名为styles.js新图表一般用 TypeScript如 usecase/styles.ts接收主题 options 参数例如const getStyles (options) .line { stroke-width: 1; stroke: ${options.lineColor}; stroke-dasharray: 2; } // ... ;把图表的getStyles挂到主入口的themes对象上src/styles.tsconst themes { flowchart, flowchart-v2: flowchart, sequence, xyzDiagram, //... };颜色等取值的定义在 src/theme/theme-[xyz].js只要你在既有的各主题文件中提供了你的图表所需的 options主题切换就能平滑工作、不出现断档。Directives 与 CommentsDirectives是从图表代码内部修改图表配置的方式如%%{init: ...}%%检测阶段 detectType 在匹配图表类型前就会先剥除 directive 与注释说明该机制是全图表统一的注释应遵循 Mermaid 标准%%行注释等usecase 解析器的commentLine规则正是通过独立的Commenttoken 在词法层跳过注释实现的。提供示例Examples 包mermaid-js/examples包含一组示例集被 mermaid.live 等工具用来帮助用户快速上手新图表。接入方式复制一个现有图表的示例文件如 flowchart.ts改成你的图表专属内容在 packages/examples/src/index.ts 中导入该示例并加入examples数组。规范要求每个图表至少有一个示例且必须有一个标记为默认default建议多提供几个示例以展示图表的不同功能。端到端核对清单综合上述各步新增一个图表类型时可在仓库中对照以下文件逐项自检以 usecase 为参照检查项参照路径Chevrotain 词法器packages/mermaid/src/diagrams/usecase/parser/usecase.lexer.tsChevrotain CstParser含performSelfAnalysispackages/mermaid/src/diagrams/usecase/parser/usecase.parser.tsCST visitor / 模型构建packages/mermaid/src/diagrams/usecase/parser/usecase.visitor.ts共享解析入口packages/mermaid/src/diagrams/common/parser/runChevrotainParse.ts渲染器packages/mermaid/src/diagrams/usecase/usecaseRenderer.ts图表入口组合 db/parser/rendererpackages/mermaid/src/diagrams/usecase/usecaseDiagram.ts类型检测与懒加载 loaderpackages/mermaid/src/diagrams/usecase/usecaseDetector.ts检测注册体系packages/mermaid/src/diagram-api/detectType.ts主题样式接入packages/mermaid/src/styles.ts 与 packages/mermaid/src/diagrams/usecase/styles.ts示例包接入packages/examples/src/index.ts解析/渲染测试样板packages/mermaid/src/diagrams/usecase/parser/usecase.parser.spec.ts、packages/mermaid/src/diagrams/usecase/usecase.spec.ts结语Mermaid 的新图表扩展机制可以概括为三处落点、一套公共约定文法Chevrotain图表目录内自包含、渲染图表目录内、检测detectType注册表 懒加载 loader再加上 Directives、无障碍、主题、注释四条全图表统一的公共约定——前者的细节决定图表能不能画后者决定它用起来是否与 Mermaid 其他图表一致。以 usecaseusecase-beta作为参考实现逐文件对照再配合 docs/community/contributing.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），仅供参考