渲染管道

相关源文件

• cypress/integration/rendering/errorDiagram.spec.js
• demos/error.html
• packages/mermaid-layout-elk/src/find-common-ancestor.ts
• packages/mermaid-layout-elk/src/render.ts
• packages/mermaid/src/Diagram.ts
• packages/mermaid/src/__mocks__/mermaidAPI.ts
• packages/mermaid/src/diagram-api/detectType.ts
• packages/mermaid/src/diagram-api/diagram-orchestration.ts
• packages/mermaid/src/diagram-api/diagramAPI.spec.ts
• packages/mermaid/src/diagram-api/diagramAPI.ts
• packages/mermaid/src/diagram-api/types.ts
• packages/mermaid/src/diagram.spec.ts
• packages/mermaid/src/diagrams/error/errorDiagram.ts
• packages/mermaid/src/diagrams/error/errorRenderer.ts
• packages/mermaid/src/diagrams/flowchart/flowDiagram.ts
• packages/mermaid/src/diagrams/flowchart/flowRenderer-v3-unified.ts
• packages/mermaid/src/diagrams/state/stateRenderer-v3-unified.ts
• packages/mermaid/src/mermaid.spec.ts
• packages/mermaid/src/mermaid.ts
• packages/mermaid/src/mermaidAPI.spec.ts
• packages/mermaid/src/mermaidAPI.ts
• packages/mermaid/src/rendering-util/insertElementsForSize.js
• packages/mermaid/src/rendering-util/layout-algorithms/dagre/index.js
• packages/mermaid/src/rendering-util/layout-algorithms/dagre/mermaid-graphlib.js
• packages/mermaid/src/rendering-util/render.ts
• packages/mermaid/src/rendering-util/rendering-elements/clusters.js
• packages/mermaid/src/rendering-util/rendering-elements/edges.js
• packages/mermaid/src/rendering-util/rendering-elements/shapes/labelRect.ts
• packages/mermaid/src/styles.ts
• scripts/tsc-check.ts

本文档描述了 Mermaid.js 中的核心渲染管道，它将基于文本的图表定义转换为可视化的 SVG 输出。渲染管道涵盖了从初始图表文本输入到解析、布局计算和最终 SVG 渲染的完整流程。

有关图表类型检测的具体信息，请参阅图表类型检测。

概述

渲染管道是处理图表定义并生成可视化输出的核心机制。它涉及几个关键阶段：

来源：packages/mermaid/src/mermaidAPI.ts306-475 packages/mermaid/src/Diagram.ts17-46

主要组件

渲染管道涉及协同工作的几个核心组件：

来源：packages/mermaid/src/mermaidAPI.ts534-552 packages/mermaid/src/Diagram.ts16-67 packages/mermaid/src/diagram-api/types.ts68-92

详细渲染过程

渲染管道主要在 mermaidAPI.ts 的 render 函数中实现。以下序列图说明了渲染过程中发生的详细步骤：

来源：packages/mermaid/src/mermaidAPI.ts306-475 packages/mermaid/src/Diagram.ts17-46 packages/mermaid/src/diagram-api/detectType.ts36-51

1. 配置处理

当渲染过程开始时，系统首先处理图表文本中的所有配置指令并应用它们。

processAndSetConfigs(text) {
  const processed = preprocessDiagram(text);
  configApi.reset();
  configApi.addDirective(processed.config ?? {});
  return processed;
}

来源：packages/mermaid/src/mermaidAPI.ts54-59

2. 图表创建

系统使用 Diagram.fromText 方法创建一个新的图表实例，该方法会执行以下操作：

1. 检测图表类型
2. 如果尚未加载，则加载相应的图表定义
3. 获取图表组件（数据库、解析器、渲染器）
4. 初始化图表数据库和解析器
5. 将文本解析到数据库中

来源：packages/mermaid/src/Diagram.ts17-46

3. 样式化

图表创建后，系统会为图表生成 CSS 样式：

1. createCssStyles 根据配置和类定义生成样式
2. getStyles 检索图表特有的样式
3. 样式使用 stylis 库进行编译
4. 样式被插入到 SVG 元素中

来源：packages/mermaid/src/mermaidAPI.ts110-172 packages/mermaid/src/styles.ts7-102

4. 绘制

通过调用渲染器的 draw 方法来绘制图表。

渲染器会执行以下操作：

1. 根据图表数据库中的数据创建 SVG 元素
2. 计算图表元素的布局（位置、大小）
3. 将 SVG 元素插入到 DOM 中

来源：packages/mermaid/src/mermaidAPI.ts425-426 packages/mermaid/src/diagram-api/types.ts116-121

5. 后处理

绘制完成后，会进行几个后处理步骤：

1. 添加辅助功能信息以改进屏幕阅读器支持
2. 清理 SVG 代码以处理特殊情况（marker-end URL、实体解码等）
3. 根据配置的安全级别应用安全措施

来源：packages/mermaid/src/mermaidAPI.ts183-204 packages/mermaid/src/mermaidAPI.ts522-530

安全考量

渲染管道实施了多项安全措施：

安全级别	行为
"sandbox"（沙盒）	SVG 在具有受限权限的沙盒 iframe 中渲染
"loose"（宽松）	SVG 直接渲染，不进行净化处理
默认	SVG 使用 DOMPurify 进行净化以防止 XSS 攻击

安全级别可以作为 Mermaid 配置的一部分进行设置。

来源：packages/mermaid/src/mermaidAPI.ts33-35 packages/mermaid/src/mermaidAPI.ts453-460

与前端 API 的集成

mermaid.ts 中的 mermaid.render() 函数是渲染管道的公共 API。此函数会执行以下操作：

1. 将渲染任务排队以便串行运行（以防止并发问题）
2. 调用 mermaidAPI.render() 执行实际渲染
3. 处理错误并提供适当的反馈

来源：packages/mermaid/src/mermaid.ts392-416

结论

渲染管道是一个复杂的流程，负责处理从文本到可视化图表的转换。它涉及图表类型检测、解析、样式化、布局计算和渲染，并额外考虑了安全性和辅助功能。

这种架构使 Mermaid 能够通过一致的接口支持各种图表类型，同时保持灵活性和可扩展性。