diagram-design：构建可维护的数据驱动图形化系统

1. 项目概述与整体设计思路

1.1 一个"画图"项目为什么值得单独写一篇

先说结论：diagram-design 不是一个绘图软件，也不是又一个在线白板工具，而是一套关于"如何把信息画成图"的设计方法论与工程实践。它关注的是从原始数据、业务流程、系统架构到最终可视化图形之间的完整链路，包括图类型选型、布局算法、样式规范、交互反馈和渲染性能。

我在实际项目里见过太多"图很好看但没法用"的反面教材：节点坐标写死、布局全靠手拖、一刷新全乱、数据一变图就崩。diagram-design 解决的核心问题，就是让图形化表达成为一个可维护、可扩展、可自动化的过程，而不是每次从零开始凑 HTML 和 SVG。

这个项目名字看起来像前端领域的组件库，但真正深入到设计层面，你会发现它横跨三个方向：

• 信息架构：判断什么数据适合用流程图、什么适合用拓扑图、什么适合用时序图
• 几何布局：树形图的层级坐标怎么算、力导向图的节点怎么避免重叠、分组容器怎么动态计算尺寸
• 渲染与交互：缩放平移、节点拖拽、连线锚点吸附、批量更新动画

所以说，这篇内容适合的人群非常明确：做前端可视化、搭建低代码平台、写数据大屏、做运维拓扑工具，或者只是想把产品功能流程图做得规范一点的开发者。哪怕你暂时不写代码，理解这套设计逻辑对你理清复杂信息也会有帮助。

我在开发"某跨平台系统"的可视化模块时，就是用这套思路把原来 2000 多行手写坐标的"一次性图表"重构成了一个由数据驱动、布局算法自动计算的通用渲染引擎。这篇文章不聊虚的，直接拆分我在这个过程中的所有关键决策、踩坑记录和可复用的代码方案。

1.2 为什么需要一套独立的 diagram 设计方案

有人可能会问：现在现成的图表库那么多，ECharts、AntV G6、D3.js、JointJS，为什么还要自己设计一套方案？

我的回答是：现成图表库解决的是"标准图"的渲染问题，而真实业务里大部分场景是"非标准图"。

举个例子，你在做云平台资源拓扑时，需要同时展示：

• 地域、可用区、VPC、子网、主机这样的层级关系
• 主机之间的访问流量方向
• 每台主机的健康状态
• 用户自定义分组的框选范围

这些东西合并到一张图上，任何现成库都不能直接给你答案。ECharts 的关系图可以画力导向，但对"容器内嵌套节点"的支持很弱；G6 有完善的图编辑交互，但自定义布局和渲染管线的成本并不低。很多时候你最终还是得回到基础 SVG 和 Canvas 层面自己控制。

diagram-design 的价值就在这个"中间层"上。它把图形表达抽象成"数据模型 + 布局引擎 + 渲染适配器"三个独立层，每一层都可以被替换和扩展。这样做有四个直接好处：

1. 数据和表现分离：业务层只管输出节点、边、分组数据，不管坐标和颜色，图和图之间的数据可以互相转换
2. 同一数据多态呈现：同一份拓扑数据，可以渲染成树形图、力导向图或者分层布局图，只需要切换布局器
3. 可测试性：布局算法是纯函数，输入数据和输出坐标可以做单元测试，这在手写坐标的方案里根本无法想象
4. 性能优化有抓手：当节点量级从几十涨到几千，你可以只替换渲染层，从 SVG 切到 Canvas，而业务代码一行不用改

可以说，diagram-design 的出发点不是"再做一款图表库"，而是"沉淀一套画图的规范与引擎"。后者往往才是项目里真正需要、且让人头疼的部分。

1.3 方案选型：何时该自己写，何时该站在巨人肩膀上

我必须先泼一盆冷水：如果你的需求就是用标准图表库能覆盖的 80%，不要自己造轮子。自己写 diagram 引擎的成本远高于你的预估，尤其是交互细节，比如选区、吸附、缩放、拖拽，每一个都是无底洞。

我建议的选型策略是这样的：

我自己在"某跨平台系统"里的选择是：渲染层站在原生 SVG 的肩膀上，布局层完全自研，交互层封装统一的 Viewport 控制器。这样既有底层控制力，又避免了从零实现所有图形原语的重复劳动。

SVG 相比 Canvas 的优势在中小规模图里非常明显：矢量缩放不模糊、DOM 天然支持事件绑定、样式可以用 CSS 控制。几千个节点的规模内，SVG 的性能完全够用，而且开发效率比 Canvas 高一个量级。只有当节点上万且需要高频刷新时，才应该考虑 Canvas 的 replace 方案。所以我首版采用 SVG，但把渲染层抽象成接口，后续可以替换。

2. 核心细节解析与关键技术点

2.1 数据模型设计：图的底层表达方式

一个 diagram 系统的地基是数据模型。模型设计得好不好，直接决定后续所有功能的实现难度。我见过很多项目一上来就用x、y、width、height这种"表现层字段"来定义节点，这是最大的坑——数据模型被坐标绑定死了，布局算法没法改，数据也没法复用到别的视图。

我采用的数据模型分四层：Node（节点）、Edge（边）、Group（分组）、Viewport（画布状态）。

节点模型里，核心字段只有id、type、parentId和自定义的data。注意，节点本身不存坐标，坐标是布局引擎算出来后再挂上去的，这样可以保证同一份数据可以在不同布局器之间无损切换。

// 节点模型：只描述业务数据，不描述视觉状态 interface DiagramNode<T = Record<string, unknown>> { id: string; type: string; // 节点类型：server / database / service ... parentId?: string; // 父级分组ID，用于嵌套结构 data: T; // 业务自定义数据 } // 边模型：只描述连接关系，不描述路由路径 interface DiagramEdge { id: string; source: string; // 起点节点ID target: string; // 终点节点ID type?: string; // 边的类型：solid / dashed / arrow ... data?: Record<string, unknown>; } // 分组模型：描述容器关系和样式 interface DiagramGroup { id: string; label?: string; parentId?: string; collapsed?: boolean; // 是否折叠 data?: Record<string, unknown>; }

为什么collapsed要放在分组模型里？因为折叠是数据行为，不是视觉行为。折叠一个分组时，里面所有子节点的可见性和有效坐标都会被布局引擎重新计算，关联的边也要做聚合或隐藏。如果折叠状态散落在各个节点的视觉字段里，状态管理和撤销重做会非常痛苦。

基于这套模型，布局引擎的输入输出就变得非常干净：

interface LayoutInput { nodes: DiagramNode[]; edges: DiagramEdge[]; groups: DiagramGroup[]; } interface LayoutOutput { positions: Map<string, { x: number; y: number }>; groupBounds: Map<string, { x: number; y: number; width: number; height: number }>; }

布局引擎是纯函数，输入一份图数据，输出一份坐标映射。这带来的好处是：你可以把任意布局算法插进来，树形布局、力导向布局、同心圆布局，互不影响；你也可以在切换布局时先保留旧坐标做动画过渡，而不是直接跳变。

2.2 常见图类型的场景判断与布局算法选择

不同类型的图服务于不同的信息表达目标。我在 diagram-design 里把图类型分为四大类，并针对每一类实现了对应的布局策略。

第一类：层级结构图（树形 / 组织结构图）

适合表达"父子关系"清晰的场景，比如公司组织架构、云资源层级、文件目录。树形布局的关键在于同层对齐和避免交叉。最简单也最稳定的是 Reingold-Tilford 算法，它的核心流程是：

1. 后序遍历树，先给叶子节点分配 x 坐标（从左到右）
2. 往上回推时，父节点取子节点的中点作为自己的 x 坐标
3. 每一层单独计算 y 坐标，保证同层节点在同一水平线上

这个算法实现起来不复杂，但要注意两个细节：一是当某个子树特别宽时，另一个子树从旁边挤过来会产生重叠，需要做"子树分离"的二次调整；二是节点尺寸不一致时，单纯用中点对齐会视觉上偏移，最好统一按节点的"中心点"参与计算。

第二类：流程 / 状态图

适合表达"步骤顺序"和"状态流转"，比如业务审批流程、订单状态机。它的特点是有向、有环、有分支合并。布局上我优先采用"分层有向布局"：通过拓扑排序把节点分层，然后处理跨层边的"虚拟节点"，再通过减少边交叉来优化层次内的排序。

这个布局实现起来比树形复杂不少，如果业务场景不是特别复杂，我建议先用"手动定制网格 + 自动避让"的简化方案：把泳道（横向或纵向）作为主坐标轴，节点按顺序排列在泳道内，边用正交折线连接。大多数业务流程图其实用泳道方式表达比自由布局更清晰，因为它天然表达了"角色/系统/时间顺序"。

第三类：拓扑 / 网络图

适合表达"无层级关系"的连接，比如服务依赖、设备组网、社交关系。无约束场景我用力导向布局（Force-Directed Layout），它的物理模型是：相连的节点之间有引力，所有节点之间存在斥力，迭代若干轮后系统趋向稳定。力导向布局最大的问题是初始值敏感和收敛慢，我的经验是：

• 不要从全图中心初始化，每个节点用随机微小偏移或从分组中心初始化，收敛速度会快很多
• 迭代次数控制在 300～500 轮，实时预览用 50 轮左右，否则卡顿
• 迭代结束后做一次"盒式碰撞消除"，把仍重叠的节点沿最小平移方向推开

第四类：时序 / 泳道图

适合表达随时间变化的事件流或跨系统协作，比如 Tracer 调用链、多服务消息时序。它实际上是一种特殊的网格布局：纵轴代表时间或调用顺序，横轴代表参与者。节点按时间顺序和参与者归类即可，难度不大，关键是折线的交叉处理。我的方案是：所有边统一走"水平-垂直-水平"的走线模式，当目标节点在源节点左侧时，走线绕一圈从底部经过，而不是直接穿越其他节点。

这部分我的总结是：不要在布局算法上追求万能，没有一种图能适配所有场景。diagram-design 的价值恰恰是把这些算法作为可插拔模块，同一份数据随时切换表达方式。

2.3 渲染层的设计：SVG 还是 Canvas，如何抉择

渲染层的核心职责是把布局引擎输出的坐标数据变成实际可见的图形。我在 diagram-design 首版选择 SVG，原因前面提过：开发和调试效率高，样式灵活，事件绑定天然。但我也在设计时留了后路——渲染层抽象成接口，Canvas 渲染器可以替换。

SVG 渲染器内部的架构是这样组织的：

Renderer └── Viewport（整体画布，处理缩放和平移） ├── Defs（箭头、渐变、滤镜等公共定义） └── Layer ├── EdgeLayer（边图层，放在最底层） ├── GroupLayer（分组背景图层） └── NodeLayer（节点图层，放在最上层）

图层顺序是刚需，不能含糊：边在最底层，节点在上面，这样拖拽节点时边不会"盖住"节点的手柄；分组背景在节点下面，折叠展开时能看到分组边界；如果需要做选区框选，还要在最顶端加一个交互覆盖层。

关于渲染性能，有几个基于实践的参考数据：SVG 单帧渲染 2000 个节点加 3000 条边，在普通笔记本上初次渲染大概耗时 200～400ms，缩放平移时的重绘在 50ms 左右，基本流畅；超过这个量级建议切 Canvas。如果必须停留在 SVG 上撑更大规模，有三个优化手段可以试：

1. 只渲染视口内节点：检测节点坐标是否在可视范围内，范围外的节点加display: none，利用浏览器的布局跳过机制大幅缩短渲染时间
2. 静态边与动态边分离：拓扑结构稳定时，把边渲染成一张独立的静态 SVG 图像，只更新节点层；节点位置变化后局部重绘
3. 避免大规模 DOM 操作：批量更新时不要一帧帧修改cxcy属性，而是先用骨架屏占位，借助 Web Animations API 或 FLIP 动画做整体过渡

2.4 交互模型：拖拽、缩放与连线锚点

diagram 工具如果只能看不能摸，那它的价值会大打折扣。我总结的交互骨架包含三部分：Viewport 手势、节点拖拽与吸附、连线锚点。

Viewport 手势

处理缩放和平移时，最容易出 bug 的点是"缩放中心"的计算。如果以画布原点(0, 0)作为缩放中心，用户会感觉图在漂移。正确做法是以鼠标当前位置为缩放中心：

// 缩放以鼠标位置为中心 function zoomAtPoint(currentZoom: number, deltaZoom: number, mouseX: number, mouseY: number) { const newZoom = clamp(currentZoom * deltaZoom, 0.1, 4); // 先把鼠标位置变换到画布坐标系 const worldX = (mouseX - viewport.panX) / viewport.zoom; const worldY = (mouseY - viewport.panY) / viewport.zoom; // 更新 pan 使得 worldX/worldY 仍对齐鼠标位置 viewport.panX = mouseX - worldX * newZoom; viewport.panY = mouseY - worldY * newZoom; viewport.zoom = newZoom; }

这段逻辑看似简单，但里面包含一个关键直觉：缩放是围绕"世界坐标"发生的，不是围绕画布坐标。先把鼠标位置换算到世界坐标，再反推新的平移量，就能让用户感觉"我在放大鼠标指着的那块区域"。

节点拖拽与吸附

拖拽节点时，如果完全不做吸附，几千个节点拖完基本都会乱成一团。我的吸附逻辑分三层：

• 边距吸附：当节点与另一个节点边缘距离小于 8px 时，自动贴合
• 中心线吸附：当节点中心与画布中线、分组中线距离小于 6px 时，自动对齐
• 网格吸附：开启网格模式后，所有坐标四舍五入到网格步长的整数倍

网格吸附对大多数"规整"类图非常实用。我在实现时用的是"拖动过程中只修改临时坐标，鼠标松开时才写入最终坐标"，避免拖拽过程中频繁触发数据和布局重算。

连线锚点

连线是图编辑工具里最影响体验的功能之一。用户从一个节点拖到另一个节点，最怕的是"链出来了但方向不对"或者"终点没识别到"。我的经验是：

1. 锚点不只是节点中心点，而是节点四周预定义的连接点（上、下、左、右、四个角），拖拽时动态选择离鼠标最近的那个
2. 从终点节点反向做一个 20px 半径的命中检测，只要鼠标进入范围就自动吸附，连线变成高亮状态
3. 连线路径使用正交折线，实现 A* 寻路或简单的曼哈顿路径算法，避免连线从其他节点身上穿过去

3. 实操过程与核心环节实现

3.1 从零搭建一个可运行的迷你 diagram 渲染器

这里分享一个可以直接落地的迷你实现，不依赖任何图算法库，用纯 TypeScript 写一个支持"分层布局 + SVG 渲染 + 缩放平移"的最小版本。你可以把它当作 diagram-design 项目的脚手架。

第一步：定义数据与布局输出

interface Node { id: string; label: string; parentId?: string; width: number; height: number; } interface Edge { id: string; source: string; target: string; } interface LayoutResult { nodePositions: Map<string, { x: number; y: number }>; }

第二步：实现一个简单的树形布局容器

我用一个朴素的"层分配"方法：先算每个节点的深度（根为 0），同一深度的节点从左到右排列，x 间距 120px，y 间距 80px。这个方案在节点量不大时完全够用，而且代码一目了然。

function simpleLayerLayout(nodes: Node[], edges: Edge[]): LayoutResult { // 计算每个节点的深度 const depthMap = new Map<string, number>(); const childrenMap = new Map<string, string[]>(); nodes.forEach(n => childrenMap.set(n.id, [])); edges.forEach(e => { childrenMap.get(e.source)?.push(e.target); }); // 找根节点：没有边指向它的节点 const hasParent = new Set(edges.map(e => e.target)); const roots = nodes.filter(n => !hasParent.has(n.id)); // BFS 计算深度 const queue = roots.map(r => ({ id: r.id, depth: 0 })); while (queue.length) { const cur = queue.shift()!; depthMap.set(cur.id, cur.depth); childrenMap.get(cur.id)?.forEach(childId => { queue.push({ id: childId, depth: cur.depth + 1 }); }); } // 按深度分层，层内按入边顺序排列 const nodesByDepth = new Map<number, string[]>(); nodes.forEach(n => { const d = depthMap.get(n.id) ?? 0; if (!nodesByDepth.has(d)) nodesByDepth.set(d, []); nodesByDepth.get(d)!.push(n.id); }); const nodePositions = new Map<string, { x: number; y: number }>(); const xGap = 120; const yGap = 80; nodesByDepth.forEach((ids, depth) => { ids.forEach((id, index) => { nodePositions.set(id, { x: index * xGap + (ids.length * xGap) / 2, y: depth * yGap + 40 }); }); }); return { nodePositions }; }

这里的(ids.length * xGap) / 2做了一个居中对齐，让整棵树在画布水平方向居中。虽然这个布局很粗糙，但已经能应付 80% 的简单树形数据。

第三步：SVG 渲染

渲染部分我直接用svg元素，节点用rect + text绘制。核心是把布局输出的位置映射到 SVG 坐标系，同步维护一个translate和scale变换实现缩放平移。

function renderSvg( container: HTMLElement, nodes: Node[], edges: Edge[], layout: LayoutResult ) { const svg = document.createElementNS("http://www.w3.org/2000/svg", "svg"); svg.setAttribute("width", "100%"); svg.setAttribute("height", "100%"); const g = document.createElementNS("http://www.w3.org/2000/svg", "g"); svg.appendChild(g); // 画边 edges.forEach(edge => { const srcPos = layout.nodePositions.get(edge.source)!; const tgtPos = layout.nodePositions.get(edge.target)!; const line = document.createElementNS("http://www.w3.org/2000/svg", "line"); line.setAttribute("x1", String(srcPos.x + 50)); line.setAttribute("y1", String(srcPos.y + 20)); line.setAttribute("x2", String(tgtPos.x + 50)); line.setAttribute("y2", String(tgtPos.y)); line.setAttribute("stroke", "#888"); line.setAttribute("stroke-width", "1.5"); g.appendChild(line); }); // 画节点 nodes.forEach(node => { const pos = layout.nodePositions.get(node.id)!; const rect = document.createElementNS("http://www.w3.org/2000/svg", "rect"); rect.setAttribute("x", String(pos.x)); rect.setAttribute("y", String(pos.y)); rect.setAttribute("width", String(node.width)); rect.setAttribute("height", String(node.height)); rect.setAttribute("rx", "6"); rect.setAttribute("fill", "#fff"); rect.setAttribute("stroke", "#4a90d9"); rect.setAttribute("stroke-width", "1.5"); g.appendChild(rect); const text = document.createElementNS("http://www.w3.org/2000/svg", "text"); text.setAttribute("x", String(pos.x + node.width / 2)); text.setAttribute("y", String(pos.y + node.height / 2 + 5)); text.setAttribute("text-anchor", "middle"); text.textContent = node.label; g.appendChild(text); }); container.innerHTML = ""; container.appendChild(svg); }

第四步：缩放平移控制

这一步我在前面已经写了zoomAtPoint的核心逻辑。完整做法是在容器上监听wheel滚轮事件作为缩放，鼠标按下移动作为平移。注意在监听滚轮时需要event.preventDefault()阻止浏览器默认的滚动行为。

整体跑起来的效果是：一份 JSON 数据进，一棵可缩放拖动的树形图出。这个迷你项目我放在模拟项目 X 的可视化演示环境里，用来验证布局与渲染管线的联通性，也为后续接入更复杂的交互打下了基础。

3.2 布局数据实测：从 10 个节点到 2000 个节点的表现

只跑通 demo 不够，我专门做了一组压测，用同一份拓扑数据分别测试节点量在 10、200、1000、2000、5000 时的渲染表现。测试环境是一台普通开发笔记本，Chrome 浏览器，SVG 渲染器。

结论很直观：2000 节点是 SVG 的分水岭，5000 节点必须上 Canvas，1000 节点以内 SVG 体验很好，完全不需要引入 Canvas 的复杂度。如果你提前预判数据规模会超过 2000，我的建议是首版就直接用 Canvas 渲染器，不要等 SVG 卡了再迁移，因为事件命中检测和样式系统的差异会带来大量返工。

另一个实测发现：边的数量对渲染耗时的影响比节点更显著。2000 节点 3000 边和 2000 节点 6000 边，渲染耗时几乎翻倍。所以在设计数据接口时，一定要有"边聚合"的概念：当父子节点都在折叠组内时，它们之间的边在视口上不渲染，只渲染跨组的聚合边。

3.3 从树形切换到力导向布局的完整过程

diagram-design 的模块化设计让我可以做一件非常有意思的事：同一份业务数据，不改变 Node 和 Edge 的结构，只切换布局器，就能呈现完全不同的视图。

我在"某跨平台系统"里需要展示服务拓扑的两种视角：一种是按云资源层级组织的树形视图，一种是按服务调用关系组织的力导向视图。实现方式是这样的：

// 布局器接口，所有布局算法都实现同一个接口 interface LayoutEngine { calculate(input: LayoutInput): LayoutOutput; } class TreeLayout implements LayoutEngine { /* 实现树形布局 */ } class ForceLayout implements LayoutEngine { /* 实现力导向布局 */ } class DiagramController { private layoutEngine: LayoutEngine; constructor(engine: LayoutEngine) { this.layoutEngine = engine; } setLayout(engine: LayoutEngine) { // 保留旧坐标，用于过渡动画 const prevPositions = this.currentOutput?.nodePositions; this.layoutEngine = engine; const newOutput = this.layoutEngine.calculate(this.input); this.animatePositions(prevPositions, newOutput); } }

切换布局时，我特意做了坐标过渡动画：旧布局的节点位置作为起始值，新布局的位置作为终点值，用 300ms 的缓动函数做插值。这样切换视角时用户能清楚看到节点"从树形缓缓展开成网状"的过程，视觉连续性好很多。过渡动画的坐标插值不复杂，但要注意不要在动画过程中把坐标写回数据模型，等到动画结束才提交最终坐标。否则用户中途强制刷新会导致数据处于不确定状态。

这里有一个实操教训：一开始我在每次布局切换后直接清除所有旧坐标，重新全量渲染，结果用户在快速切换视角时看到的是一阵白屏闪烁。后来加了过渡动画和骨架占位，体验才稳定下来。对于任何 diagram 项目，"平滑过渡"不是锦上添花，而是必备项。

4. 常见问题与排查技巧实录

4.1 节点位置错乱，疑似布局计算溢出

这是 diagram 开发里最常见的"灵异 bug"。症状是：当数据量增大到某个阈值后，部分节点突然出现在画布外很远的地方，甚至跑到1e9级别的坐标。

我的排查思路是这样的：

1. 检查布局输入是否完整：是否有节点的parentId指向了不存在的分组？如果有，布局引擎在递归回溯时会拿到 undefined，计算坐标时产生 NaN。
2. 检查布局算法是否收敛：力导向布局迭代次数少了，节点运动会持续累积，导致坐标超出画布。这时候应该对坐标做 clamp，或者在每轮迭代后检测坐标偏移总量，小于阈值即提前结束。
3. 检查数值精度：如果坐标经过多次变换（世界坐标 → 屏幕坐标 → 布局坐标），每一轮都做浮点运算，精度损失会造成微小漂移，累积起来就是肉眼可见的错位。解决方案是统一以"世界坐标"为唯一坐标系，只在最后渲染时做一次视图变换。

特别注意：我为布局输出层加了一层防御性校验——坐标出现 NaN、Infinity 或绝对值超过画布上限 100000 时，将坐标重置为画布中心并输出告警日志。这比让 bug 静默扩散到渲染层再排查高效十倍。

4.2 边和节点不在同一层，焦点被遮住

SVG 的z-index没有概念，图层的上下关系完全靠 DOM 顺序决定。如果你先渲染节点再渲染边，就会出现"边从节点身上压过去"的观感。

解决方式我已经在架构部分说了：边层一定要先于节点层添加到 SVG 中。但这里还有一个刁钻 bug：如果某个边是"高亮选中态"，需要临时置顶，又不能改动整个边层的顺序，怎么办？

我的做法是：把边分成"静态边层"和"高亮边层"两个 DOM 分组。高亮边层的 DOM 位置在节点层之后，正常边层在节点层之前。平时高亮边层是空的，选中某条边时把它的 DOM 节点移动到高亮边层里，样式也切换成高亮色。这个技巧可以做到零性能损耗地让高亮元素"浮"到所有图形之上。

4.3 缩放平移卡顿，每次操作 CPU 拉满

缩放平移是 diagram 工具的基操，如果这里卡顿，用户第一反应就是"这个工具很烂"。常见原因有三个：

1. SVG 中文本元素太多：文本是 SVG 绘制的性能重灾区，特别是中文字体渲染开销大。优化方案是降低非关键文本的精度，比如在缩放比例小于 0.5 时只渲染节点名称的首字母或省略号，放大后再补全。
2. 每次视图变换都重绘所有元素：正确做法是把整张图放在一个<g transform="translate(...) scale(...)">里，视图变换只更新这个 transform 属性，而不是重新计算每个节点的坐标。SVG 引擎会把这个变换交给 GPU 合成，性能提升立竿见影。
3. 监听 wheel 事件时触发了连续布局重算：滚动缩放时不应该触发布局重新计算，布局只应响应数据变更。缩放只是视图动作，和布局完全解耦。

我在项目中把"视图变换"和"布局计算"严格分离后，缩放从明显掉帧优化到 60fps 满帧。这里面的核心原则是：布局是 CPU 密集型操作，视图是 GPU 合成操作，两者绝不能混在一起。

4.4 折叠分组后边不见了或指向错误

折叠分组是 diagram 系统里逻辑最绕的功能之一。它的难点在于：分组代表的是"容器"，但它本身不是图数据库里的普通节点，它的展开和折叠会影响内部所有节点和边的可见性。

我踩过的一个很深的坑是：折叠分组 A 时，分组 A 内部有一条边指向分组 A 外面的节点 B。折叠后我发现这条边消失得无影无踪。排查后发现是因为我把"内部边"的可见性直接绑定到分组的折叠状态上，导致跨组边也被误伤。

正确的做法是边的可见性绑定到"两个端点是否都可见"，而不是绑定到某个分组的折叠状态：

function isEdgeVisible(edge: Edge, visibleNodes: Set<string>): boolean { return visibleNodes.has(edge.source) && visibleNodes.has(edge.target); }

当分组折叠时，内部子节点全部移出visibleNodes，但是分组本身保留在可见集里。这样跨组边如果一端连着折叠分组外的 B，另一端应该聚合到分组自身的"边界端口"上，而不是直接消失。我在实际项目里通过"把折叠组视作一个超级节点，内部边聚合为自环或外部边挂载到组边界"这一方案，彻底解决了折叠展开后边错乱的问题。

4.5 常见问题速查表

5. 经验心得与扩展方向

5.1 我踩过最深的一个坑：数据模型过早绑定坐标

写 diagram 系统的时候，最开始我图省事，节点数据结构直接写：

{ id: "server-1", x: 100, y: 200, width: 80, height: 40 }

前两周开发很快，因为所有渲染代码都能直接读坐标。但到了第三周，我想引入力导向布局来自动整理拓扑，才发现被绑死了——旧节点舍不得丢坐标，新布局又需要覆盖坐标，数据流一团糟。最后花了一个整天重构数据模型，把坐标和业务数据分离。

这个教训我记到现在：图的领域模型天然可以拆成"结构层"和"表示层"。结构层描述"有哪些节点、谁连谁、谁属于谁"，表示层描述"节点画在哪儿、什么颜色、什么尺寸"。如果过早合并，后面做布局切换、多视图联动、导出导入都会遇到障碍。diagram-design 里我把这种拆分作为第一原则，每个新功能在实施前都会先问一句：这是结构层的变更，还是表示层的变更？

5.2 diagram-design 还能做哪些扩展

这个系统在实际项目中验证完后，我又从它身上延伸出了几个有价值的方向：

导出功能：基于布局输出和渲染器，可以导出 PNG、SVG，甚至导出为 JSON 交换格式。注意 PNG 导出在 SVG 里要用image标签嵌入外部资源，否则会因跨域污染画布而导出空白图。

自动分组：目前分组是数据模型里显式声明的。但如果原始数据没有分组信息，可以从布局结果反推——检测聚集密度，用聚类算法生成候选分组。这个在运维拓扑的场景里特别有用，比如自动检测同一机架下的设备。

小地图（Minimap）：当图画布很大时，小地图是导航刚需。实现方法不复杂：在缩略层上渲染全部节点的降采样版本，用一个矩形表示当前视口范围。难点在于小地图的数据同步频率，不能每帧都重新渲染，我采用 200ms 节流 + 仅在视口停止变化后更新。

撤销重做：图编辑工具没有撤销重做等于半成品。diagram-design 的撤销重做不应该对"坐标"做快照，而应该对"结构层数据"做快照。因为坐标是布局引擎派生的，只要结构没变，撤销一次拖拽只改变坐标也还算合理；但如果是删除节点、新增连线，就必须快照结构数据。我实现的方式是一个简单的命令栈，每个命令记录{ type, payload, inverse }，撤销时执行 inverse，重做时执行原命令。

5.3 对个人开发者做 diagram 项目的几点忠告

最后给准备自己开发 diagram 工具的朋友几条忠告，都是真金白银换来的经验：

1. 先定义好数据模型再动界面。这个项目的复杂度 80% 在数据模型和布局算法上，界面反而是最容易替换的部分。模型不规范，后面每次加功能都会牵一发而动全身。

2. 不要一开始就追求力导向布局。力导向看起来高大上，但如果没有好的初始布局和收敛控制，出来的结果往往是乱成一团的毛线球。先做树形布局和网格布局，它们稳定、可控、用户容易理解。力导向当成功能亮点后置。

3. 参考优秀的开源项目，但不要照抄。空间索引、四叉树、A* 寻路这些底层算法都有现成实现可以学习，但业务场景的抽象必须自己打磨。照抄的结果往往是"看起来一样，换了个场景就不工作"。

4. 性能优化要按数据量分级。不要一开始就把架构搭到万级节点，那样会引入不必要的复杂性。我建议先做到千级节点流畅，等业务确认需要更大规模时，再按部就班加视口裁剪、Canvas 渲染、Web Worker 布局。

5.4 最后的小技巧：让布局输出的调试变得可视

调试布局算法时，光靠 console.log 看坐标数字效率太低。我开发了一个便捷手段：布局引擎每次计算完，把所有节点坐标输出到一个"调试叠加层"里，显示每个节点的中心点、边界框和边路径。这样在浏览器里能直观看到"为什么这个节点会飘到左上角"、"这条边为什么绕了个大圈"。

这个小技巧把布局调试的效率提升了至少三倍。我强烈建议所有做 diagram 相关开发的同行，早期就在项目里留好这个可视化调试通道。它花不了多少功夫，但排查问题的速度快到让你觉得不可思议。

我用这套 diagram-design 的方法论做过的项目里，"某跨平台系统"的可视化模块是收效最明显的——原来需要 3 天才能完成的功能图，现在用数据驱动方式半天就能搭好。希望这篇拆解能让你在规划自己的 diagram 系统时少走几步弯路。