Mermaid @mermaid-js/examples 包版本演进解析：从 CHANGELOG 看官方示例体系的构建方法

Mermaid mermaid-js/examples 包版本演进解析从 CHANGELOG 看官方示例体系的构建方法【免费下载链接】mermaidGeneration of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown项目地址: https://gitcode.com/GitHub_Trending/me/mermaidmermaid-js/examples是 Mermaid 生态中专门承载“各图表类型官方示例”的独立发布包。本文以 packages/examples/CHANGELOG.md 为主线完整梳理 1.0.0 至 1.4.0 五个版本的变更内容并结合 src/index.ts、src/types.ts 与测试 example.spec.ts说明这个包的数据结构、注册机制与“每个图表至少一个默认示例”的质量契约帮助你在开发 Mermaid 类工具如在线编辑器、模板库时正确复用官方示例数据。1. 包的定位与 CHANGELOG 全览根据 packages/examples/README.md 的说明mermaid-js/examples包含一组示例集合供 mermaid.live 等工具使用帮助用户快速上手各类图表。包的 package.json 中声明了type: module入口为./dist/mermaid-examples.core.mjs类型入口为./dist/index.d.ts通过exports字段只暴露包根路径一个子路径其运行时依赖为空对象唯一的 devDependency 是mermaidworkspace:*指向 monorepo 内的 packages/mermaid也就是说示例包本身不含渲染逻辑只负责“示例数据 元信息”的发布。CHANGELOG 采用 changesets 生成的标准格式Minor Changes/Patch Changes分级完整记录如下版本类型变更来源内容1.4.0MinorPR #7832feat: add relatable, real-world examples for every diagram type, showcasing each diagrams strengths1.3.0MinorPR #7915feat(examples): Add relatable, real-world examples for every diagram type, showcasing each diagrams strengths1.2.0MinorPR #7526add new TreeView diagram1.1.0MinorPR #7387feat: Add Ishikawa diagram (ishikawa-beta)1.0.0Minor PatchPR #6453、#6510feat: Add examples for diagrams in themermaid-js/examplespackagechore: Move packet diagram out of beta并跟随 mermaid11.9.0 的依赖升级五个版本全部为 Minor 升版符合语义化版本中“向后兼容地新增能力”的定义。从升版节奏可以归纳出一条清晰的演进主线1.0.0 建立示例体系 → 1.1.0 / 1.2.0 随新图表类型扩充覆盖面 → 1.3.0 / 1.4.0 提升示例质量从“能渲染”走向“贴近真实场景”。下面逐版本展开。2. 1.0.0示例包的诞生1.0.0 是起点版本包含两类变更MinorPR #6453在mermaid-js/examples包中为各图表添加示例即建立“每个图表类型对应一份元数据 示例代码”的基础体系PatchPR #6510将 packet 图表移出 beta 阶段。值得注意的是CHANGELOG 同时记录了 “Updated dependencies: mermaid11.9.0”共 6 个上游 commit说明示例包与主包 packages/mermaid 在 monorepo 内是强联动发布的——主包每次升版示例包都会同步记录依赖变更保证示例代码与渲染引擎版本匹配。从 src/index.ts 看1.0.0 之后持续累积的diagramData数组如今已注册 33 个图表条目flowchart、c4、class、sequence、er、gantt、gitgraph、architecture、xychart、sankey、timeline、quadrant、packet、block、treemap、usecase、eventmodeling、venn、treeView、wardley、cynefin、kanban、requirement、radar、mindmap、state、pie、user-journey、ishikawa以及 railroad 及其 ebnf/abnf/peg 三个变体与 CHANGELOG 中“逐版本新增图表”的记录相互印证。3. 1.1.0 与 1.2.0新图表类型进入示例体系3.1 1.1.0 —— Ishikawa 图ishikawa-betaPR #7387 引入了鱼骨图因果分析图示例对应源文件 src/examples/ishikawa.ts。其元数据为id: ishikawa、名称 “Ishikawa Diagram”、描述 “Visualize problem and causes in fishbone”并提供了 2 个示例默认示例isDefault: true“Ishikawa Diagram”以Blurry Photo照片模糊为问题按 Process / User / Equipment / Environment 四类原因展开其中Equipment下还有LENS、SENSOR二级分组展示了语法支持的嵌套因果层级扩展示例 “Late Food Delivery Root Causes”外卖迟到根因分析额外演示了Measurement度量这一原因维度。两个示例均使用ishikawa-beta标识符与 CHANGELOG 中 “(ishikawa-beta)” 的标注一致说明该图表在加入时仍处于 beta 阶段。3.2 1.2.0 —— TreeView 图PR #7526 引入树视图图对应源文件 src/examples/tree-view.tsid: treeView描述 “Visualize hierarchical data as a tree structure”。该版本贡献了 5 个示例是覆盖维度最丰富的示例文件之一Project File Structure默认示例用treeView-beta缩进语法直接呈现一个my-project/的项目目录树覆盖src/components多级嵌套与普通文件Shared Drive with Quoted Names演示双引号包裹的带空格名称如Team Drive、Quarterly ReportsAnnotations演示在代码块前置 YAML frontmatter 配置treeView.showIcons: true以及行内注释语法## main component、行内图标icon(logos:react)、icon(none)、高亮:::highlightFile-Type Icons via Config Maps演示通过defaultIconPack、filenameIcons、extensionIcons按文件名或扩展名批量映射图标Unicode Icons in Filenames演示文件名中直接使用 emoji如 rocket-app/的表现。从源码结构看TreeView 示例把“基础语法、引号转义、配置项、图标体系、Unicode 边界”逐一拆开恰好对应了该图表语法的主要特性面为后来 1.3.0/1.4.0 的“贴近现实示例”风格定下了基调。4. 1.3.0 与 1.4.0面向真实场景的示例升级1.3.0PR #7915与 1.4.0PR #7832两条记录的主题相同为每一种图表类型补充 relatable、real-world 的示例展示每种图表的长处showcasing each diagrams strengths。两次 minor 版本说明这是一项持续性的质量工程而不是一次性提交。这类升级在现有示例文件中可以直接观察到。以 src/examples/flowchart.ts 为例默认示例 “Basic Flowchart” 保留了经典的 Christmas 购物流程含fa:fa-carFontAwesome 图标边标签但随后新增了三个场景化示例Online Checkout Flow完整的电商结账流程含条件回环Retry -- Pay与style节点着色CI/CD Pipeline with Subgraphs用subgraph划分 Development / Continuous Integration / Deployment 三个阶段体现流程图在工程流程表达上的优势Expanded Node Shapes使用{ shape: ... }新语法展示manual-input、docs、procs、diam、cyl、stadium等扩展节点形状。同样地Ishikawa 的第二个示例 “Late Food Delivery Root Causes”、TreeView 的 “Project File Structure” 都是同一思路的产物示例不再只是“语法演示”而是“某类图表适合解决什么现实问题”的最小可运行答案。对于 mermaid.live 一类的产品这意味着用户切换图表类型时看到的默认模板即刻具备参考价值。5. 数据结构与消费方式如何正确使用这个包5.1 数据契约DiagramMetadata 与 Example示例包的全部类型定义集中在 src/types.tsexport interface Example { title: string; // 示例标题 code: string; // 可直接投喂给 mermaid.parse / mermaid.render 的代码 isDefault?: boolean; // 是否为该图表的默认示例 } export interface DiagramMetadata { id: string; // 与 mermaid 注册表中的图表 id 对应如 flowchart-v2 name: string; // 展示名如 Flowchart description: string; // 一句话说明该图表的用途 examples: Example[]; }每个示例文件都用satisfies DiagramMetadata做类型约束如 src/examples/flowchart.ts因此新增图表示例时编译器会强制你补全id、name、description、examples四个字段这是“元信息完整性”的第一道保障。5.2 注册入口与 README 推荐的消费代码所有示例在 src/index.ts 中以diagramData: DiagramMetadata[]数组统一导出。README 给出的标准用法mermaid.live 的取默认示例逻辑如下pnpm add mermaid-js/examplesimport { diagramData } from mermaid-js/examples; type DiagramDefinition (typeof diagramData)[number]; const isValidDiagram (diagram: DiagramDefinition): diagram is RequiredDiagramDefinition { return Boolean(diagram.name diagram.examples diagram.examples.length 0); }; export const getSampleDiagrams () { const diagrams diagramData .filter((d) isValidDiagram(d)) .map(({ examples, ...rest }) ({ ...rest, example: examples?.filter(({ isDefault }) isDefault)[0], })); const examples: Recordstring, string {}; for (const diagram of diagrams) { examples[diagram.name.replace(/ (Diagram|Chart|Graph)/, )] diagram.example.code; } return examples; };这段代码的要点先用isValidDiagram做类型收窄保证examples非空再为每个图表挑出isDefault true的示例最后用正则replace(/ (Diagram|Chart|Graph)/, )把 “Ishikawa Diagram” 这类名称归一化为 “Ishikawa” 作为 key得到一张“图表名 → 默认示例代码”的映射表。如果你的产品需要“每种图表一个可渲染的起始模板”直接复用该模式即可。5.3 新增示例的流程README 给出了扩展步骤复制一个现有示例文件如 src/examples/flowchart.ts按你的图表改造然后在 src/index.ts 中 import 并加入diagramData数组。每条图表至少需要一个isDefault: true的示例“并建议增加更多示例以展示图表的不同特性”——这条约定正是 CHANGELOG 1.3.0/1.4.0 两次 real-world 升级的直接来源。6. 质量保障example.spec.ts 的三重校验示例包的价值不只在于“有示例”而在于示例永远可解析。测试文件 src/example.spec.ts 建立了三重契约覆盖性校验should have examples for each diagrams调用mermaid.registerExternalDiagrams([])触发注册后遍历mermaid.getRegisteredDiagramsMetadata()的全部图表排除白名单error、info、class、graph、flowchart-elk、flowchart、state、swimlane等——白名单注释说明它们由 v2 版本或 flowchart 覆盖断言每个剩余图表在diagramData中都存在条目、examples.length 0且默认示例有且仅有一个data.examples.filter((e) e.isDefault).length).toBe(1)。这意味着任何主包新增图表而忘记补示例CI 会直接失败——CHANGELOG 中 1.1.0/1.2.0 每次新图表都伴随示例包 minor 升版正是这条契约在起作用。全量可解析校验should have valid examples对diagramData中每一个图表的每一个示例执行mermaid.parse(example.code)断言解析成功。即示例代码不只是字符串而是每次提交都必须通过真实解析器的回归。渲染校验以 usecase 为例对 usecase 的每个示例先parse再render并检查产物 DOM 中存在[data-usecase-kind]节点。测试还通过 mockSVGElement.getBBox/getComputedTextLength来屏蔽 jsdom 环境缺失的 SVG 度量能力保证无头环境下布局计算不崩溃。这三层校验覆盖性 → 可解析 → 可渲染与 CHANGELOG 的演进方向互为表里1.3.0/1.4.0 大胆地替换为更复杂的 real-world 示例底气正来自这套“改完示例必过解析”的测试护栏。7. 小结回看 CHANGELOGmermaid-js/examples五个 minor 版本构成了一条完整的示例工程演进路径1.0.0建包、建机制diagramData统一出口 packet 出 beta对齐 mermaid11.9.01.1.0 / 1.2.0Ishikawa、TreeView 等新图表类型随主包能力同步进入示例体系1.3.0 / 1.4.0将全部示例升级为贴近真实业务的场景突出每种图表的适用优势。对使用者的直接启示有三点其一把diagramData当作“图表类型元数据 官方模板”的单一事实来源按 README 的getSampleDiagrams模式消费其二新增示例时遵守DiagramMetadata契约并在 src/index.ts 注册其三用 example.spec.ts 的思路为自建示例库加上“覆盖性 可解析”的双重断言。相关配套文档可参阅 docs/syntax/ 目录下各图表的语法参考如 flowchart.md、ishikawa.md、treeView.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），仅供参考