Mermaid 渲染管线核心契约：深入解析 LayoutData 接口的结构与使用

本文围绕 Mermaid 官方 API 文档中的 LayoutData 接口 展开：它定义了 Mermaid 内部"解析（parse）→ 布局（layout）→ 渲染（render）"三段式管线中，解析器交给布局算法的唯一数据契约。读完后你将掌握 LayoutData 四个核心成员（nodes、edges、config、diagramId）与索引签名各自的职责，理解它如何驱动 dagre / swimlane / ELK 等布局算法，以及作为插件或扩展开发者时应当如何正确地填充这份数据。

1. LayoutData：管线中的位置与定义

LayoutData 是 Mermaid v11 统一渲染架构中的关键 TypeScript 接口，定义于 packages/mermaid/src/rendering-util/types.ts：

// packages/mermaid/src/rendering-util/types.ts (L214-L220)
// Specific interfaces for layout and render data
export interface LayoutData {
  nodes: Node[];
  edges: Edge[];
  config: MermaidConfig;
  diagramId?: string;
  [key: string]: any; // Additional properties not yet defined
}

其对应的 API 参考文档 LayoutData.md 由 TypeDoc 自动从该源文件生成，文档顶部带有标准的自动生成警告：

Warning

THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.

Please edit the corresponding file in /packages/mermaid/src/docs/...。

因此该接口文档的字段说明、定义位置（types.ts:214 起）均与源码一一对应，修改类型定义后重新生成文档即可保持一致。

从源码结构看，LayoutData 处于管线的"腰部"：

1. 解析阶段：各 diagram 模块（flowchart、state、usecase、mindmap、er 等）各自维护 xxxDb.ts 解析数据库，产出统一的 LayoutData 对象；
2. 布局阶段：layoutAlgorithm 字段指定的算法（dagre、swimlane、cose-bilkent 等）消费 nodes、edges 和 config，计算出每个节点的坐标；
3. 渲染阶段：通用渲染器把布局结果画进 SVG。

2. 四个核心成员逐一解析

2.1 nodes: Node[] —— 节点集合

Node 本身是一个联合类型（types.ts#L131）：

// Common properties for any node in the system
export type Node = ClusterNode | NonClusterNode;

两者都继承自内部的 BaseNode 接口，包含大量可选字段（types.ts#L14-L99），例如：

• 标识与内容：id（必填）、label、description、stereotype（UML 立体类型行）、domId；
• 层级关系：parentId（所属分组节点 id）、children（NodeChildren，即子节点数组）、isGroup（区分 ClusterNode/NonClusterNode 的判别字段）、dir（分组内部方向）;
• 交互属性：link、linkTarget、tooltip、haveCallback；
• 尺寸与位置：x、y、width、height、wrappingWidth、labelBBox（标签包围盒）、groupTitleRect（分组的标题区域，类型见 types.ts#L106-L111 的 GroupTitleRect）；
• 样式属性：cssStyles、cssCompiledStyles、cssClasses、backgroundColor、borderColor、labelTextColor 等。

对特定图类型，源码在 BaseNode 基础上做了进一步扩展，例如类图的 ClassDiagramNode（types.ts#L209-L211）额外要求 memberData，看板图的 KanbanNode（types.ts#L247-L254）携带 priority、ticket、level 等字段。

2.2 edges: Edge[] —— 边集合

Edge 接口定义于 types.ts#L134-L194，字段可分为几组：

字段	说明
id（必填）、label	边标识与标签文本
start / end	边的起终点节点 id（布局阶段使用）
arrowhead、arrowTypeStart、arrowTypeEnd	箭头类型，支持 open 等多种取值
style、classes、cssCompiledStyles	边的 CSS 样式与 class
thickness	线宽：'normal' | 'thick' | 'invisible' | 'dotted'
curve、interpolate、minlen、labelpos	曲线插值与最短长度等渲染参数
startLabelRight / endLabelLeft 等	类图等特定图的端点标签
isLabelEdge、labelNodeId	泳道路由中标签作为途经点的特殊边
isLayoutOnly	布局专用虚拟边：仅供 Sugiyama 分层/排序使用，渲染消费方必须跳过

其中 isLayoutOnly 字段的注释（types.ts#L188-L193）明确说明：这类边"exists solely to feed Sugiyama layering / ordering"，路由或渲染边的消费者必须跳过。这一点在通用渲染器 common/index.ts 中有直接实现——shouldSkipPaintEdge 会过滤掉所有 isLayoutOnly 为真的边。

2.3 config: MermaidConfig —— 全局配置快照

config 的类型是 MermaidConfig，定义于 packages/mermaid/src/config.type.ts。它携带主题（theme）、主题变量（themeVariables，含 useGradient、gradientStart、gradientStop）以及各类 diagram 的配置项。

render 入口实际从中读取 theme 与 themeVariables 来生成 SVG 的阴影滤镜和渐变定义（见 render.ts#L79-L131）：

// packages/mermaid/src/rendering-util/render.ts
const { theme, themeVariables } = data4Layout.config;
const { useGradient, gradientStart, gradientStop } = themeVariables;

也就是说，LayoutData.config 让布局/渲染阶段无需再回查全局配置，即可独立完成外观相关的决策。

2.4 diagramId?: string —— 多图表 id 隔离

可选字段，用于同一页面渲染多张图时保证 DOM id 唯一。render 入口会利用它给所有节点的 domId 加前缀（render.ts#L69-L74）：

if (data4Layout.diagramId) {
  for (const node of data4Layout.nodes) {
    const originalDomId = node.domId || node.id;
    node.domId = `${data4Layout.diagramId}-${originalDomId}`;
  }
}

相关测试见 packages/mermaid/src/rendering-util/multi-diagram-id-uniqueness.spec.ts。

2.5 索引签名 [key: string]: any —— 算法专用扩展位

文档与源码一致地标注了 [key: string]: any（"Additional properties not yet defined"）。这是刻意保留的扩展空间：diagram 模块与布局算法通过它挂载尚未被提升到接口的字段。例如 flowchart 渲染器在构造 data4Layout 时会写入（flowRenderer-v3-unified.ts）：

data4Layout.layoutAlgorithm = getRegisteredLayoutAlgorithm(layout);
data4Layout.direction = direction;
data4Layout.nodeSpacing = conf?.nodeSpacing || 50;
data4Layout.rankSpacing = conf?.rankSpacing || 50;
data4Layout.markers = ['point', 'circle', 'cross'];
data4Layout.diagramId = id;

状态图渲染器 stateRenderer-v3-unified.ts 同样会设置 layoutAlgorithm 与 diagramId。这些字段正是通过索引签名进入 LayoutData 的。

3. 姊妹类型：RenderData 与 LayoutMethod

LayoutData 并非孤立存在，同一文件中还定义了两个相邻契约（types.ts#L222-L238）：

export interface RenderData {
  items: (Node | Edge)[];
  [key: string]: any;
}

export type LayoutMethod =
  | 'dagre'
  | 'dagre-wrapper'
  | 'elk'
  | 'neato'
  | 'dot'
  | 'circo'
  | 'fdp'
  | 'osage'
  | 'grid';

• RenderData 用于无需完整布局、只需把节点与边混合绘制的项目（如 pie 类图表），items 同时接受 Node 与 Edge；
• LayoutMethod 是从源码结构可推断的布局方法字符串联合类型，涵盖 Graphviz 系列方法（neato、dot、circo、fdp、osage）与 grid 等，为布局算法选择提供了命名空间。

4. 布局算法如何消费 LayoutData

4.1 统一渲染工厂 createCommonLayoutRenderer

现代布局算法不再各自实现完整渲染流程，而是通过 common/index.ts 的工厂函数组装四阶段管线：

prepareLayout → measureLayout → runLayoutCore → paintLayout → afterPaint

每个阶段的签名都以 LayoutData 作为第一个入参（CommonLayoutRendererDefinition）：

• prepareLayout：算法专属的输入变换；
• measureLayout：测量标签与元素尺寸，默认实现 defaultMeasureLayout 调用 createGraphWithElements 生成隐藏 SVG 图并测量；
• runLayoutCore：真正计算节点坐标的算法核心，"This is the core piece where functions are supposed to be different between different algorithms"（源码注释原文）；
• paintLayout / afterPaint：把布局结果画到 SVG，afterPaint 用于边渲染完成后的二次处理（如泳道图中边标签的最终定位）。

默认的 paintLayoutData 直接遍历 data4Layout.nodes 与 data4Layout.edges（common/index.ts#L210-L235）：节点按 isGroup 决定插入 cluster 还是 positionNode，边则跳过 isLayoutOnly 后逐条绘制，并为 edge.label 计算居中位置。

4.2 入口 render：算法注册与懒加载

render.ts 中的 render(data4Layout, svg) 是 LayoutData 进入渲染管线的总入口：

1. 校验 data4Layout.layoutAlgorithm 是否已注册，未注册则抛出 Unknown layout algorithm 错误；
2. 用 diagramId 前缀化所有节点 domId；
3. 懒加载对应算法（dagre 与 swimlane 默认注册，cose-bilkent 仅在大特性开关下注册，见 render.ts#L39-L58）；
4. 注入阴影滤镜/渐变后调用 layoutRenderer.render(data4Layout, svg, internalHelpers, { algorithm })。

LayoutAlgorithm 接口的 render 签名（render.ts#L14-L21）即为每个布局算法包（dagre/index.js、swimlanes/index.ts、cose-bilkent/index.ts）必须实现的契约。

4.3 算法回退与外部布局

getRegisteredLayoutAlgorithm 提供回退机制（render.ts#L141-L150）：未注册的算法会告警并回退到 dagre。一个典型例子是 flowchart 对 ELK 的处理（flowRenderer-v3-unified.ts#L35-L40）：ELK 布局在 Mermaid v11 已移入外部包 packages/mermaid-layout-elk，若用户仍配置 elk，源码会记录"将使用 dagre 作为回退"的警告日志。这也解释了为何 LayoutMethod 联合类型中保留了 elk 等取值——命名约定与具体实现包解耦。

此外，测量阶段为避免污染原始数据，会用 cloneLayoutDataForMeasure.ts 对 LayoutData 做克隆，保证算法可以安全地改写克隆体上的坐标字段而不影响解析层。

5. 实战视角：填充一份合格的 LayoutData

结合上文，一个插件或扩展在产出 LayoutData 时应遵循的最小清单：

import type { LayoutData } from 'mermaid/dist/rendering-util/types.js'; // 类型位置以仓库实际导出为准

const data4Layout: LayoutData = {
  nodes: [
    { id: 'A', label: '开始', isGroup: false },
    { id: 'B', label: '处理', isGroup: false },
  ],
  edges: [{ id: 'e1', label: '是', start: 'A', end: 'B', arrowhead: 'classic' }],
  config: getConfig(),          // 必须携带完整 MermaidConfig（含 theme/themeVariables）
  diagramId: 'my-diagram-001',  // 多图表页面强烈建议提供
  // 索引签名扩展位：布局算法与方向等
  layoutAlgorithm: 'dagre',
  direction: 'TB',
};
await render(data4Layout, svg);

要点回顾：

• nodes/edges/config 三者缺一，render 或测量/绘制阶段即会失败（nodes 为空数组时至少需要 config.theme 供滤镜配色）；
• 分组容器请显式给出 isGroup: true 与 parentId/children，这是 cluster 渲染路径（insertCluster）的判定依据；
• 布局虚拟边务必标记 isLayoutOnly: true，否则会被当作真实边绘制出来；
• 若算法尚未在 layoutAlgorithms 注册，render 会直接抛错，需先经 registerLayoutLoaders（render.ts#L32-L36）注册。

6. 小结

LayoutData 虽然只有五行接口定义，却是 Mermaid 渲染体系的中枢契约：nodes/edges 承载图结构，config 提供主题与配置快照，diagramId 解决多图隔离，索引签名则容纳了 layoutAlgorithm、nodeSpacing 等算法私有字段。配合 Node/Edge 联合类型、RenderData 与 LayoutMethod 两个姊妹类型，以及 createCommonLayoutRenderer 四阶段管线，构成了从文本解析到 SVG 输出的完整数据流。开发布局算法或图表插件时，建议以 rendering-util/types.ts 为第一手依据，并对照 LayoutData、CommonLayoutRendererDefinition、RenderOptions 等自动生成的 API 文档核对字段签名。