diagram-design 这个名字放在技术社区里可能被理解成“画图组件”或“图表设计规范”但对我来说它是过去大半年一直在迭代的一个内部项目代号。简单说它是一套完整的图编辑器内核覆盖从数据模型、自动布局、Canvas 渲染、鼠标交互、快捷键、JSON 存档到 PNG 导出的一整条链路。团队里用它来画架构图、流程图、网络拓扑图和状态机图省去了“画完截图再贴文档”这种反人类的流程。为什么想写这篇总结因为这类项目最容易踩的坑其实不在某个具体算法而在整体设计数据怎么组织、坐标怎么换算、事件在哪一层接、性能退化发生在哪一行。这里面的多数问题不是看文档就能想到的。所以我按自己做 diagram-design 的真实顺序把从思路拆解到工程落地、再到排障实录的过程完整写出来。如果你正准备在公司内部自建一套图编辑器或者需要用代码生成和维护技术图纸这篇文章应该能帮你少走不少弯路。整个项目做完后我对“图表设计工具”这件事的理解有一点变化它不是一个你拖拽节点、连线就完事的小玩具。真正的复杂度来自对坐标、数据、渲染和交互这四个模块的一致性管理。任何一个环节没对齐用户就会感觉“这个图怎么那么难用”。下面按决策顺序来聊。1. 项目整体设计与思路拆解1.1 为什么自研而不是直接拿来改先说结论自研 diagram-design 不是“造轮子上瘾”而是当时确实找不到一个能完全贴着业务走的方案。我们把市面上主流的流程编辑器、图表库都拉来跑了一圈。有的擅长流程图节点只能按固定模板来做成自定义业务节点会非常痛苦有的擅长组织架构图但连线的路由方式写死了想改成正交折线要改内部源码还有一些看起来功能很全但 API 设计围绕它自己的数据模型展开和我们的接口协议完全对不上。最要命的往往是事件模型别人的库只给你暴露“节点被点击”“边被双击”可我们要的是“拖拽过程中实时拿到坐标并做合法性提示”这种需求在封闭的插件机制里很难干净实现。后来我算了一笔账用现成库前两周确实能快速搭出 Demo。但只要进入业务定制阶段每改一个小需求都要去查它的源码、做 monkey patch时间成本会快速上升而且版本升级后这些改动大概率要重写。自己维护一套图引擎前期投入会高一些但数据模型、渲染、交互全部可控后续增加新功能只是往自己的框架里填代码不用看别人的眼色。那是不是所有图都应该自研也不是。如果需求就是简单的流程图、思维导图用成熟方案反而更稳。判断标准我总结成三条业务节点是否高度自定义、是否需要与后端协议强绑定、是否对操作体验有非主流要求。只要踩中第二条自研的收益就很明显因为你可以把数据格式设计和接口协议放在一起规划而不是在别人的模型外面再做一层蹩脚的适配。1.2 渲染层选型Canvas、SVG 还是 WebGLdiagram-design 最大的技术决策是渲染层用什么。我们最终选了 Canvas 为主但做决定之前我列过一个很朴素的对比表。渲染方式节点规模交互精度文本渲染开发成本典型场景SVG小几百节点高天然支持事件清晰可复用 DOM 文本低流程图、图标绘制Canvas中到大数千节点需要自做命中检测需要手动排版遇缩放需控制中拓扑图、架构图、大画布WebGL很大上万节点复杂基本要自研拾取最费力纹理或字形方案很高图数据库可视化、大规模网络图我们的场景是架构图和拓扑图单张画布里节点数量可能到几千而且节点大多不是简单矩形要带端口、状态图标、缩略信息。SVG 在两千个节点、三千条边的时候DOM 数量直接上万一个拖动操作会触发大量的样式和属性变更浏览器很快就喘不过气。WebGL 性能确实强但我们要做的是交互编辑器不是纯展示页面拾取、文本排版、多状态绘制都要在渲染管线里自己处理以当时的团队精力来说并不划算。Canvas 相对中庸它有足够的绘制能力也能承受几千节点的全量重绘只要做好视口裁剪和状态降级。代价是事件系统、点击拾取、坐标转换全部要自己写。所以选 Canvas 不是因为它最好而是它在“功能完整度”和“开发成本”之间最平衡。后来的实现也证明只要你把命中检测和数据索引做好交互精度完全不输 SVG甚至因为少了 DOM 事件分发拖拽反而更顺滑。1.3 功能边界先做减法再做加法这种项目最怕的就是大而全。最早的问卷里有人希望它能当 Visio 用有人想让它跑工作流引擎还有人建议直接做成在线协同白板。如果这些都做项目半年内都看不到一个能验收的版本。我先把范围砍到一条核心链路上画布能展示图、能拖拽编辑、数据能持久化。具体功能列下来是这样的必做节点拖拽移动、节点新增删除、连线新增删除、画布缩放平移、框选多选、撤销重做、自动布局、JSON 存档、PNG 导出。缓做多人实时协同、流程图执行引擎、自由绘制图形、模板市场、一键美化。明确不做矢量绘图软件级别的自由画布、复杂图文混排、PPT 式演示模式。边界明确之后很多设计就有了依据。比如因为不需要自由绘制任意路径所以图形基础只有矩形、圆角矩形、椭圆、菱形这几种节点模型可以简化因为不需要协同数据层不需要做冲突合并和操作日志同步。定义好“不做”的部分等于提前砍掉一大半隐形成本。2. 核心数据模型与布局算法拆解2.1 图数据的抽象把数据和渲染解耦自研图编辑器最重要的一步就是先定数据模型。这个模型一定要和渲染解耦。我见过很多失败案例是把节点的 x、y、宽高直接存在 DOM 元素或者 Canvas 对象上看起来方便但一旦要序列化、撤销重做、自动布局就会陷入“到处同步状态”的泥潭。diagram-design 的数据模型分成三层Graph 是整张图Node 是节点Edge 是边。下面是我在实际代码里使用的核心接口省略了业务扩展字段但骨架就是这样interface GraphNode { id: string; type: string; // 节点形状类型 x: number; y: number; width: number; height: number; ports?: Port[]; // 连接点 data: Recordstring, unknown; // 业务自定义数据 } interface Port { id: string; side: top | right | bottom | left; index: number; } interface GraphEdge { id: string; source: string; target: string; sourcePort?: string; targetPort?: string; type: straight | orth | bezier; points?: { x: number; y: number }[]; // 手动航点 data: Recordstring, unknown; } interface DiagramData { nodes: GraphNode[]; edges: GraphEdge[]; viewport?: { x: number; y: number; scale: number }; }关键点有三个。第一节点的坐标只存一份就是世界坐标渲染时再转换成屏幕坐标不额外保存“渲染后的位置”。第二data字段是开放的黑盒业务可以在里面塞任何内容而内核永远不解析它这样节点组件就能自由定制。第三边的端点不直接存坐标而是存节点 id 和端口 id在渲染前通过端口位置计算出来。这样节点移动时边会自动跟着变化不需要为每条边维护位置缓存。当时为了处理“数据类型安全”也犹豫过要不要为每种节点定义强类型接口。后来我放弃了因为业务节点太多太杂强制收口会让上层的每个业务都来改内核类型定义反而破坏解耦。只要保证最外层的节点类型注册机制是强约束的内部的 data 就是透明的 JSON 就好。2.2 自动布局先跑通层次布局再谈好看图编辑器如果没有自动布局在节点一多的时候会非常痛苦。人肉拖出来的图往往毫无章法连线交叉得一塌糊涂。但自动布局又是一个巨大的技术面力导向、树形布局、层次布局、网格布局各有适用场景。diagram-design 里我优先做的也是最常被用到的是层次布局用来处理有依赖关系的架构图。层次布局的核心思路很直接先确定每个节点在第几条水平线上再调整同一层内的左右顺序最后给每一层分配 y 坐标。基础的层分配算法可以这样描述function layeredLayout(nodes, edges): 构建有向图边从 source 指向 target 计算每个节点的“最长路径层” 没有入边的节点层为0 其他节点层 max(入边源节点层) 1 按层排序层内先用原始顺序 给每层分配 y层高 最大节点高度 层间距 对相邻层执行节点排序调整降低边交叉 由边两端节点位置计算每条边的路径 返回更新后的节点坐标这里最容易被忽视的是“最长路径层”而不是“最短路径层”。如果用最短路径一个被多条路径依赖的节点会被过早地放到上层导致后面大量边的走向都是反向的。最长路径能保证每个节点都至少排在它所有前置节点的后面视觉上所有边的方向基本一致整张图看起来就顺很多。层内排序降低交叉是一个可以一直优化的点。第一版我只做了“同层按入边源节点的平均 x 排序”效果已经能接受。更复杂的算法比如重心法、启发式交换后续可以慢慢加但不必在第一版就追求极致美观。另外不是所有图都适合层次布局比如前后端调用关系往往是网状结构这时候力导向布局会更好。所以我在设计里保留了布局接口自动布局模块通过注册机制扩展不同图类型可以绑定不同布局策略。2.3 连线路径与正交路由连线是 diagram-design 里视觉专业度的胜负手。如果连线都直接画一条直线稍微复杂一点的图就会互相穿心没法看。所以默认的连线类型是正交折线也就是横平竖直的连接方式这种风格在架构图、网络拓扑图里最通用。实现正交路由第一版没必要上重型算法可以先做一个“带偏移方向偏好的简单路由”从源节点的连接口出发先沿水平或垂直方向走一段中间遇到节点或边的包围盒阻挡时在阻挡物之前插入垂直/水平转折点到达目标连接口附近时再沿水平或垂直方向接入。听起来简单但代码关键在“出线方向”和“进线方向”。端口定义在节点的左、右、上、下四边那么从右边端口出去第一段肯定向右进入目标节点的左侧端口最后一段肯定向左。两者的垂直坐标如果不在同一条线上就插入一个垂直连接段。这样的连线天然只包含水平线段和垂直线段视觉上干净很多。当然这种简单路由不会完美合路多条边共用一段路径的情况也处理不了。所以我在边上保留了points数组业务人员可以手动拖拽增加“途经点”。绘制时路径会依次穿过这些航点。底层折线算法只负责“从端口出发到第一个航点”“在两个航点之间”“从最后一个航点到目标端口”这三段这样复杂绕线问题就可以用人类智慧手动解决程序只需要保持基础整洁。3. 实操过程与核心环节实现3.1 多画布分层渲染diagram-design 最终是四个 Canvas 叠在一起而不是一个 Canvas 画所有内容。从底下往上分别是网格画布、连线画布、节点画布、交互画布。每层都有明确的职责互不越界。为什么拆层因为重绘频率不一样。拖动节点时节点层必须每帧刷新但网格层完全不用动框选时交互层每帧都要画虚线框可节点层没必要跟着重绘。拆层之后update 时可以只标记需要变化的那层draw 时只重绘对应画布性能会好非常多。代价是四个画布叠加在一起的层级管理要小心不过 CSS 里设置position: absolute加上统一宽高对齐问题并不难。初始化时的要点是处理 devicePixelRatio。Canvas 的物理像素宽高和 CSS 宽高不一致会导致模糊。我会在每次尺寸变化时重新设置画布 buffer 大小function resizeCanvas(canvas: HTMLCanvasElement, width: number, height: number) { const dpr window.devicePixelRatio || 1; canvas.width width * dpr; canvas.height height * dpr; canvas.style.width ${width}px; canvas.style.height ${height}px; const ctx canvas.getContext(2d); ctx.setTransform(dpr, 0, 0, dpr, 0, 0); // 保证内部按 CSS 像素绘制 }这里如果漏掉setTransform后面画出来的所有坐标都会乘上 dpr导致文字小、形状错位而且导出图片时差异还会更明显。有时间的话甚至可以把每一层画布的刷新逻辑都包成一个小型 renderer对外只提供invalidate()接口由内部决定哪一层需要重绘这样业务调用方完全不需要关心渲染细节。3.2 拖拽、缩放、框选背后的坐标变换画布类编辑器的核心是把“世界坐标”和“屏幕坐标”分开。世界坐标是图本身的坐标缩放平移不影响它屏幕坐标是你鼠标事件的坐标。节点拖拽时鼠标返回的是屏幕坐标但节点的位置存在世界坐标里所以每时每刻都需要换算。换算公式很基础但必须统一到一处防止到处重复实现导致偶然错误。我在代码里维护了viewport对象它是{ x, y, scale }含义是“世界坐标原点在屏幕上的位置”和“放大倍数”。对应的两个函数长这样function worldToScreen(wx: number, wy: number) { return { x: wx * viewport.scale viewport.x, y: wy * viewport.scale viewport.y, }; } function screenToWorld(sx: number, sy: number) { return { x: (sx - viewport.x) / viewport.scale, y: (sy - viewport.y) / viewport.scale, }; }缩放操作有个常见的坑如果只是简单地把scale变大变小画面会围绕画布左上角缩放而不是围绕鼠标位置。用户会觉得缩放很“飘”。正确做法是缩放前先用screenToWorld算出鼠标所在的世界坐标缩放后保证这个点仍处于鼠标位置function zoomAt(mouseX: number, mouseY: number, nextScale: number) { const world screenToWorld(mouseX, mouseY); viewport.scale clamp(nextScale, 0.2, 4); viewport.x mouseX - world.x * viewport.scale; viewport.y mouseY - world.y * viewport.scale; }框选实现则简单得多在交互画布上用虚线矩形表示选区判断一个节点是否被选中只需要看节点矩形和选区矩形是否相交。注意这里要用世界坐标比较可以把选区矩形也先转换到世界坐标再做 AABB 相交判断省去把每个节点都转回屏幕坐标的开销。命中检测同理遍历所有节点用矩形包含或相交判断。3.3 导出图片与工程保存图表画完之后要能拿出去用所以导出是刚需。diagram-design 支持导出为 PNG 图片同时也支持保存工程文件用于后续继续编辑。PNG 导出的坑在于我们用的是多 Canvas 分层渲染不能直接拿某一个 Canvas 去toDataURL。正确做法是新建一个离屏 Canvas宽度和高度按当前图的“世界包围盒”乘以导出倍率计算再逐个把网格、连线、节点的内容绘制上去。绘制时注意先fill一个背景色否则透明背景下浅色节点会看不清。整个过程我封装成一个工具方法核心代码大概是这样function exportPNG(scale 2) { const bounds getWholeGraphBounds(); // 世界坐标系包围盒 const canvas document.createElement(canvas); canvas.width bounds.width * scale; canvas.height bounds.height * scale; const ctx canvas.getContext(2d); ctx.fillStyle currentTheme.background; ctx.fillRect(0, 0, canvas.width, canvas.height); ctx.scale(scale, scale); // 依次绘制网格、连线、节点注意平移到 bounds 的左上角 drawGrid(ctx, bounds); drawEdges(ctx, bounds); drawNodes(ctx, bounds); return canvas.toDataURL(image/png); }工程保存则不保存像素而是保存 JSON 形式的DiagramData里面包含节点、边、视口信息。这样重新打开时可以回到之前的位置继续编辑。比较关键的是加上version字段因为后续结构肯定会调整没有版本号的存档就是给自己埋雷。加载时根据 version 走不同的迁移逻辑虽然麻烦但这是长期维护里性价比最高的一件事。3.4 性能优化从全量重绘到视口裁剪几千节点直接全量重绘Canvas 也能扛一阵子但拖拽时会明显掉帧。第一刀永远是视口裁剪只画当前可见区域内的节点和边。这个优化非常朴素效果却立竿见影。判定可见性的代码也简单function isNodeVisible(node: GraphNode, viewportBounds: Bounds) { return ( node.x node.width viewportBounds.left node.x viewportBounds.right node.y node.height viewportBounds.top node.y viewportBounds.bottom ); }有了裁剪函数后渲染循环从“遍历所有节点画出来”变成“遍历所有节点不在视口内就跳过”。对于与视口相交的边也可以做裁剪尤其是跨越很长距离的折线如果两端都不在视口内而且离视口很远就跳过不画。但要注意一条线的两个端点一个在视口内、一个在视口外这种线不能简单跳过还得画。第二刀是“缩放降级”。当画布缩放比例比较小的时候整个图都缩成一小块这时候再画节点内部的文字、阴影、渐变没有意义。我设置了两个阈值低于 0.6 不绘制文本低于 0.4 不绘制阴影和复杂状态图标。用户缩小后看到的是一块块色块反而比一堆糊掉的文字更清爽放大的时候又能看到完整细节。第三刀是网格缓存。网格背景每帧都是重复线段完全没必要跟着节点层一起重绘。我会在 resize 时创建一个独立的离屏 Canvas把所有网格线一次性画上去刷新时直接drawImage能省掉每一帧的几十次stroke调用。这个优化很小但对低端设备很友好。4. 常见问题与排查技巧实录4.1 坐标偏移和缩放失真十次里有八次是 DPR 问题做 diagram-design 过程中我被问得最多的一个问题就是“为什么我拖节点到某个位置松开后它跳了一下”。这通常不是事件逻辑有问题而是鼠标坐标换算不对。最常见的原因有三个。第一拿到的是offsetX / offsetY但 Canvas 的物理尺寸和 CSS 尺寸不一致鼠标偏移量没有除以缩放倍数。第二多 Canvas 布局时事件绑在最上层 Canvas但getBoundingClientRect用的是容器元素导致坐标系基准不统一。第三窗口更换显示器或者浏览器缩放后devicePixelRatio变化了但没有重置 Canvas 的 buffer 大小。排查这类问题我习惯在画布角落写一个调试面板同时显示三组坐标原生鼠标屏幕坐标、经过getBoundingClientRect换算后的本地坐标、经过screenToWorld后的世界坐标。然后在画布中心画一个十字标记用鼠标把它拖到网格交叉点上。如果视觉位置和实际数据的坐标对不上很快就能看出来是哪个环节丢了缩放因子。4.2 大数据量卡顿先从性能消耗大头开始查有段时间全图画到 4000 个节点、6000 条边时拖动节点每帧要 30 毫秒以上体感已经明显卡顿。我没有盲目去优化数据结构而是先用performance.now()把渲染的每个阶段都卡了一遍时间结果发现耗时大头有三个连线渲染占了接近一半因为每条边都画了带阴影的贝塞尔曲线节点文本绘制占用 30%因为在视口内有大量可见节点都要执行fillText最后 20% 来自阴影shadowBlur和各种状态判断。定位到具体原因后优化就是按部就班的事。连线默认从贝塞尔改成直线或简单的正交折线因为架构图里太多平滑曲线反而是视觉噪音文本绘制只在缩放阈值以上时才执行阴影改成绘制一个半透明圆角矩形作为“假阴影”而不是用 Canvas 原生shadowBlur后者性能实在太差。把这些改完之后同样一张图的拖拽帧耗时降到了 8 毫秒左右体感丝滑很多。这里有个经验先量化再优化。不要听人说“ShadowBlur 性能差”就立刻把阴影全部去掉你得先知道自己的卡顿是不是由它引起的。用分阶段计时器把所有耗时摆出来优化会变得异常朴素就是找到最大头干掉它然后再测。4.3 拖拽出画布后事件突然不触发了这类问题在桌面浏览器上不容易出现但在触摸屏和部分窗口环境下会偶发。现象是你按住节点快速拖出浏览器窗口再拖回来发现节点卡住了pointermove不再触发。原因在于鼠标指针移出画布后原来绑定在 Canvas 上的事件不再收到消息而pointerup也被浏览器吞掉状态机一直停留在“拖拽中”。解决办法有两个一是监听事件时直接挂在容器元素上而不是某个 Canvas 上让事件区域覆盖整个画布容器二是在pointerdown时主动调用setPointerCapture强制浏览器把后续指针事件都派发给当前元素canvas.addEventListener(pointerdown, (e) { canvas.setPointerCapture(e.pointerId); startDrag(e); }); canvas.addEventListener(pointermove, (e) { if (isDragging) updateDrag(e); }); canvas.addEventListener(pointerup, (e) { canvas.releasePointerCapture(e.pointerId); endDrag(e); });除了事件绑定还有一个容易被忽略的点是“多画布层级下事件到底发给谁”。如果四个 Canvas 叠在一起事件会自动派发给最上面的那个元素。为了统一我会把事件统一绑在最上层的交互画布上内部再通过screenToWorld换算到世界坐标而不是让每一层都处理自己的事件。这样即使未来把交互层重构掉事件入口也不需要改。4.4 主题定制最容易演变成颜色硬编码灾难业务上会同时出现深色模式、浅色模式、品牌定制色、状态告警色。如果一开始不把主题机制做出来后期就会在代码里到处写死#1890ff这种颜色而且每种节点组件还会再抄一遍。diagram-design 里我定义了一套Theme接口所有绘制函数只从theme读取颜色、线宽、字体不写死任何视觉参数interface Theme { background: string; gridColor: string; nodeFill: string; nodeStroke: string; nodeText: string; edgeColor: string; edgeWidth: number; selectionStroke: string; shadowColor: string; fontFamily: string; }节点绘制函数签名大概是drawNode(ctx, node, theme)内部用到颜色时一律theme.nodeFill、theme.nodeStroke。这样切换主题时只需要替换 theme 对象然后通知渲染层重绘即可。为了支持交互状态我还会在绘制前根据节点状态合并一个状态主题比如 hover 时边框加亮、selected 时描边换色、invalid 时填充变红。这个“状态样式叠加”不要和主题混在一起否则主题会膨胀得很难维护。顺带提一个教训不要为了“图省事”把颜色同时写进数据和 theme 里。如果业务节点的data里带了一个bgColor绘制时就会优先用它结果就是深色主题下个别节点依然白得刺眼。后来我明确规则业务数据可以控制内容但视觉表现统一走主题如果某个节点确实需要特殊颜色通过注册的节点组件显式声明而不是在通用渲染链路里开口子。5. 一些收尾的实践心得做 diagram-design 的过程里我最大的一点体会是这类项目看起来是绘图本质上是“数据描述、坐标转换、正确渲染”六个字。只要把数据模型定义清楚、坐标换算统一到同一个工具库、渲染层只消费不修改数据后续所有功能都能往里稳定叠加。反过来如果前期为了省事把坐标散落到各个组件里后面加自动布局和协同编辑时会痛不欲生。给准备入手的团队一个建议不要一开始就想着实现最复杂的全局自动布局和完美路由。先把“人工拖一张 20 个节点的图”做到流畅好用再逐步加自动布局、性能优化、大图支撑。因为人工编辑场景是所有高级功能的地基地基不稳自动布局排出来的图再漂亮也没法继续编辑。最后分享一个我自己的小习惯把所有边界操作整理成一个交互测试清单。比如“节点拖到画布外再拖回来”“缩放比例小于最小值时的提示”“框选时恰好从节点右下角开始”“导出图片时包含超出视口的节点”。每个边界情况都写成一个最小可复现 Demo每次改动后按清单过一遍。这个小清单帮我挡掉过至少三次回归问题也让我在加新功能时更有底气。diagram-design 到现在还在迭代后续考虑接入自动化布局推荐和更丰富的节点组件体系但这个“先让基础链路稳如磐石”的思路我会一直带下去。 
长河君 · 2026/10/17 15:00:16 · 阅读 1.2k 自研图编辑器内核：从数据模型到Canvas渲染的完整实践
diagram-design 这个名字放在技术社区里可能被理解成“画图组件”或“图表设计规范”但对我来说它是过去大半年一直在迭代的一个内部项目代号。简单说它是一套完整的图编辑器内核覆盖从数据模型、自动布局、Canvas 渲染、鼠标交互、快捷键、JSON 存档到 PNG 导出的一整条链路。团队里用它来画架构图、流程图、网络拓扑图和状态机图省去了“画完截图再贴文档”这种反人类的流程。为什么想写这篇总结因为这类项目最容易踩的坑其实不在某个具体算法而在整体设计数据怎么组织、坐标怎么换算、事件在哪一层接、性能退化发生在哪一行。这里面的多数问题不是看文档就能想到的。所以我按自己做 diagram-design 的真实顺序把从思路拆解到工程落地、再到排障实录的过程完整写出来。如果你正准备在公司内部自建一套图编辑器或者需要用代码生成和维护技术图纸这篇文章应该能帮你少走不少弯路。整个项目做完后我对“图表设计工具”这件事的理解有一点变化它不是一个你拖拽节点、连线就完事的小玩具。真正的复杂度来自对坐标、数据、渲染和交互这四个模块的一致性管理。任何一个环节没对齐用户就会感觉“这个图怎么那么难用”。下面按决策顺序来聊。1. 项目整体设计与思路拆解1.1 为什么自研而不是直接拿来改先说结论自研 diagram-design 不是“造轮子上瘾”而是当时确实找不到一个能完全贴着业务走的方案。我们把市面上主流的流程编辑器、图表库都拉来跑了一圈。有的擅长流程图节点只能按固定模板来做成自定义业务节点会非常痛苦有的擅长组织架构图但连线的路由方式写死了想改成正交折线要改内部源码还有一些看起来功能很全但 API 设计围绕它自己的数据模型展开和我们的接口协议完全对不上。最要命的往往是事件模型别人的库只给你暴露“节点被点击”“边被双击”可我们要的是“拖拽过程中实时拿到坐标并做合法性提示”这种需求在封闭的插件机制里很难干净实现。后来我算了一笔账用现成库前两周确实能快速搭出 Demo。但只要进入业务定制阶段每改一个小需求都要去查它的源码、做 monkey patch时间成本会快速上升而且版本升级后这些改动大概率要重写。自己维护一套图引擎前期投入会高一些但数据模型、渲染、交互全部可控后续增加新功能只是往自己的框架里填代码不用看别人的眼色。那是不是所有图都应该自研也不是。如果需求就是简单的流程图、思维导图用成熟方案反而更稳。判断标准我总结成三条业务节点是否高度自定义、是否需要与后端协议强绑定、是否对操作体验有非主流要求。只要踩中第二条自研的收益就很明显因为你可以把数据格式设计和接口协议放在一起规划而不是在别人的模型外面再做一层蹩脚的适配。1.2 渲染层选型Canvas、SVG 还是 WebGLdiagram-design 最大的技术决策是渲染层用什么。我们最终选了 Canvas 为主但做决定之前我列过一个很朴素的对比表。渲染方式节点规模交互精度文本渲染开发成本典型场景SVG小几百节点高天然支持事件清晰可复用 DOM 文本低流程图、图标绘制Canvas中到大数千节点需要自做命中检测需要手动排版遇缩放需控制中拓扑图、架构图、大画布WebGL很大上万节点复杂基本要自研拾取最费力纹理或字形方案很高图数据库可视化、大规模网络图我们的场景是架构图和拓扑图单张画布里节点数量可能到几千而且节点大多不是简单矩形要带端口、状态图标、缩略信息。SVG 在两千个节点、三千条边的时候DOM 数量直接上万一个拖动操作会触发大量的样式和属性变更浏览器很快就喘不过气。WebGL 性能确实强但我们要做的是交互编辑器不是纯展示页面拾取、文本排版、多状态绘制都要在渲染管线里自己处理以当时的团队精力来说并不划算。Canvas 相对中庸它有足够的绘制能力也能承受几千节点的全量重绘只要做好视口裁剪和状态降级。代价是事件系统、点击拾取、坐标转换全部要自己写。所以选 Canvas 不是因为它最好而是它在“功能完整度”和“开发成本”之间最平衡。后来的实现也证明只要你把命中检测和数据索引做好交互精度完全不输 SVG甚至因为少了 DOM 事件分发拖拽反而更顺滑。1.3 功能边界先做减法再做加法这种项目最怕的就是大而全。最早的问卷里有人希望它能当 Visio 用有人想让它跑工作流引擎还有人建议直接做成在线协同白板。如果这些都做项目半年内都看不到一个能验收的版本。我先把范围砍到一条核心链路上画布能展示图、能拖拽编辑、数据能持久化。具体功能列下来是这样的必做节点拖拽移动、节点新增删除、连线新增删除、画布缩放平移、框选多选、撤销重做、自动布局、JSON 存档、PNG 导出。缓做多人实时协同、流程图执行引擎、自由绘制图形、模板市场、一键美化。明确不做矢量绘图软件级别的自由画布、复杂图文混排、PPT 式演示模式。边界明确之后很多设计就有了依据。比如因为不需要自由绘制任意路径所以图形基础只有矩形、圆角矩形、椭圆、菱形这几种节点模型可以简化因为不需要协同数据层不需要做冲突合并和操作日志同步。定义好“不做”的部分等于提前砍掉一大半隐形成本。2. 核心数据模型与布局算法拆解2.1 图数据的抽象把数据和渲染解耦自研图编辑器最重要的一步就是先定数据模型。这个模型一定要和渲染解耦。我见过很多失败案例是把节点的 x、y、宽高直接存在 DOM 元素或者 Canvas 对象上看起来方便但一旦要序列化、撤销重做、自动布局就会陷入“到处同步状态”的泥潭。diagram-design 的数据模型分成三层Graph 是整张图Node 是节点Edge 是边。下面是我在实际代码里使用的核心接口省略了业务扩展字段但骨架就是这样interface GraphNode { id: string; type: string; // 节点形状类型 x: number; y: number; width: number; height: number; ports?: Port[]; // 连接点 data: Recordstring, unknown; // 业务自定义数据 } interface Port { id: string; side: top | right | bottom | left; index: number; } interface GraphEdge { id: string; source: string; target: string; sourcePort?: string; targetPort?: string; type: straight | orth | bezier; points?: { x: number; y: number }[]; // 手动航点 data: Recordstring, unknown; } interface DiagramData { nodes: GraphNode[]; edges: GraphEdge[]; viewport?: { x: number; y: number; scale: number }; }关键点有三个。第一节点的坐标只存一份就是世界坐标渲染时再转换成屏幕坐标不额外保存“渲染后的位置”。第二data字段是开放的黑盒业务可以在里面塞任何内容而内核永远不解析它这样节点组件就能自由定制。第三边的端点不直接存坐标而是存节点 id 和端口 id在渲染前通过端口位置计算出来。这样节点移动时边会自动跟着变化不需要为每条边维护位置缓存。当时为了处理“数据类型安全”也犹豫过要不要为每种节点定义强类型接口。后来我放弃了因为业务节点太多太杂强制收口会让上层的每个业务都来改内核类型定义反而破坏解耦。只要保证最外层的节点类型注册机制是强约束的内部的 data 就是透明的 JSON 就好。2.2 自动布局先跑通层次布局再谈好看图编辑器如果没有自动布局在节点一多的时候会非常痛苦。人肉拖出来的图往往毫无章法连线交叉得一塌糊涂。但自动布局又是一个巨大的技术面力导向、树形布局、层次布局、网格布局各有适用场景。diagram-design 里我优先做的也是最常被用到的是层次布局用来处理有依赖关系的架构图。层次布局的核心思路很直接先确定每个节点在第几条水平线上再调整同一层内的左右顺序最后给每一层分配 y 坐标。基础的层分配算法可以这样描述function layeredLayout(nodes, edges): 构建有向图边从 source 指向 target 计算每个节点的“最长路径层” 没有入边的节点层为0 其他节点层 max(入边源节点层) 1 按层排序层内先用原始顺序 给每层分配 y层高 最大节点高度 层间距 对相邻层执行节点排序调整降低边交叉 由边两端节点位置计算每条边的路径 返回更新后的节点坐标这里最容易被忽视的是“最长路径层”而不是“最短路径层”。如果用最短路径一个被多条路径依赖的节点会被过早地放到上层导致后面大量边的走向都是反向的。最长路径能保证每个节点都至少排在它所有前置节点的后面视觉上所有边的方向基本一致整张图看起来就顺很多。层内排序降低交叉是一个可以一直优化的点。第一版我只做了“同层按入边源节点的平均 x 排序”效果已经能接受。更复杂的算法比如重心法、启发式交换后续可以慢慢加但不必在第一版就追求极致美观。另外不是所有图都适合层次布局比如前后端调用关系往往是网状结构这时候力导向布局会更好。所以我在设计里保留了布局接口自动布局模块通过注册机制扩展不同图类型可以绑定不同布局策略。2.3 连线路径与正交路由连线是 diagram-design 里视觉专业度的胜负手。如果连线都直接画一条直线稍微复杂一点的图就会互相穿心没法看。所以默认的连线类型是正交折线也就是横平竖直的连接方式这种风格在架构图、网络拓扑图里最通用。实现正交路由第一版没必要上重型算法可以先做一个“带偏移方向偏好的简单路由”从源节点的连接口出发先沿水平或垂直方向走一段中间遇到节点或边的包围盒阻挡时在阻挡物之前插入垂直/水平转折点到达目标连接口附近时再沿水平或垂直方向接入。听起来简单但代码关键在“出线方向”和“进线方向”。端口定义在节点的左、右、上、下四边那么从右边端口出去第一段肯定向右进入目标节点的左侧端口最后一段肯定向左。两者的垂直坐标如果不在同一条线上就插入一个垂直连接段。这样的连线天然只包含水平线段和垂直线段视觉上干净很多。当然这种简单路由不会完美合路多条边共用一段路径的情况也处理不了。所以我在边上保留了points数组业务人员可以手动拖拽增加“途经点”。绘制时路径会依次穿过这些航点。底层折线算法只负责“从端口出发到第一个航点”“在两个航点之间”“从最后一个航点到目标端口”这三段这样复杂绕线问题就可以用人类智慧手动解决程序只需要保持基础整洁。3. 实操过程与核心环节实现3.1 多画布分层渲染diagram-design 最终是四个 Canvas 叠在一起而不是一个 Canvas 画所有内容。从底下往上分别是网格画布、连线画布、节点画布、交互画布。每层都有明确的职责互不越界。为什么拆层因为重绘频率不一样。拖动节点时节点层必须每帧刷新但网格层完全不用动框选时交互层每帧都要画虚线框可节点层没必要跟着重绘。拆层之后update 时可以只标记需要变化的那层draw 时只重绘对应画布性能会好非常多。代价是四个画布叠加在一起的层级管理要小心不过 CSS 里设置position: absolute加上统一宽高对齐问题并不难。初始化时的要点是处理 devicePixelRatio。Canvas 的物理像素宽高和 CSS 宽高不一致会导致模糊。我会在每次尺寸变化时重新设置画布 buffer 大小function resizeCanvas(canvas: HTMLCanvasElement, width: number, height: number) { const dpr window.devicePixelRatio || 1; canvas.width width * dpr; canvas.height height * dpr; canvas.style.width ${width}px; canvas.style.height ${height}px; const ctx canvas.getContext(2d); ctx.setTransform(dpr, 0, 0, dpr, 0, 0); // 保证内部按 CSS 像素绘制 }这里如果漏掉setTransform后面画出来的所有坐标都会乘上 dpr导致文字小、形状错位而且导出图片时差异还会更明显。有时间的话甚至可以把每一层画布的刷新逻辑都包成一个小型 renderer对外只提供invalidate()接口由内部决定哪一层需要重绘这样业务调用方完全不需要关心渲染细节。3.2 拖拽、缩放、框选背后的坐标变换画布类编辑器的核心是把“世界坐标”和“屏幕坐标”分开。世界坐标是图本身的坐标缩放平移不影响它屏幕坐标是你鼠标事件的坐标。节点拖拽时鼠标返回的是屏幕坐标但节点的位置存在世界坐标里所以每时每刻都需要换算。换算公式很基础但必须统一到一处防止到处重复实现导致偶然错误。我在代码里维护了viewport对象它是{ x, y, scale }含义是“世界坐标原点在屏幕上的位置”和“放大倍数”。对应的两个函数长这样function worldToScreen(wx: number, wy: number) { return { x: wx * viewport.scale viewport.x, y: wy * viewport.scale viewport.y, }; } function screenToWorld(sx: number, sy: number) { return { x: (sx - viewport.x) / viewport.scale, y: (sy - viewport.y) / viewport.scale, }; }缩放操作有个常见的坑如果只是简单地把scale变大变小画面会围绕画布左上角缩放而不是围绕鼠标位置。用户会觉得缩放很“飘”。正确做法是缩放前先用screenToWorld算出鼠标所在的世界坐标缩放后保证这个点仍处于鼠标位置function zoomAt(mouseX: number, mouseY: number, nextScale: number) { const world screenToWorld(mouseX, mouseY); viewport.scale clamp(nextScale, 0.2, 4); viewport.x mouseX - world.x * viewport.scale; viewport.y mouseY - world.y * viewport.scale; }框选实现则简单得多在交互画布上用虚线矩形表示选区判断一个节点是否被选中只需要看节点矩形和选区矩形是否相交。注意这里要用世界坐标比较可以把选区矩形也先转换到世界坐标再做 AABB 相交判断省去把每个节点都转回屏幕坐标的开销。命中检测同理遍历所有节点用矩形包含或相交判断。3.3 导出图片与工程保存图表画完之后要能拿出去用所以导出是刚需。diagram-design 支持导出为 PNG 图片同时也支持保存工程文件用于后续继续编辑。PNG 导出的坑在于我们用的是多 Canvas 分层渲染不能直接拿某一个 Canvas 去toDataURL。正确做法是新建一个离屏 Canvas宽度和高度按当前图的“世界包围盒”乘以导出倍率计算再逐个把网格、连线、节点的内容绘制上去。绘制时注意先fill一个背景色否则透明背景下浅色节点会看不清。整个过程我封装成一个工具方法核心代码大概是这样function exportPNG(scale 2) { const bounds getWholeGraphBounds(); // 世界坐标系包围盒 const canvas document.createElement(canvas); canvas.width bounds.width * scale; canvas.height bounds.height * scale; const ctx canvas.getContext(2d); ctx.fillStyle currentTheme.background; ctx.fillRect(0, 0, canvas.width, canvas.height); ctx.scale(scale, scale); // 依次绘制网格、连线、节点注意平移到 bounds 的左上角 drawGrid(ctx, bounds); drawEdges(ctx, bounds); drawNodes(ctx, bounds); return canvas.toDataURL(image/png); }工程保存则不保存像素而是保存 JSON 形式的DiagramData里面包含节点、边、视口信息。这样重新打开时可以回到之前的位置继续编辑。比较关键的是加上version字段因为后续结构肯定会调整没有版本号的存档就是给自己埋雷。加载时根据 version 走不同的迁移逻辑虽然麻烦但这是长期维护里性价比最高的一件事。3.4 性能优化从全量重绘到视口裁剪几千节点直接全量重绘Canvas 也能扛一阵子但拖拽时会明显掉帧。第一刀永远是视口裁剪只画当前可见区域内的节点和边。这个优化非常朴素效果却立竿见影。判定可见性的代码也简单function isNodeVisible(node: GraphNode, viewportBounds: Bounds) { return ( node.x node.width viewportBounds.left node.x viewportBounds.right node.y node.height viewportBounds.top node.y viewportBounds.bottom ); }有了裁剪函数后渲染循环从“遍历所有节点画出来”变成“遍历所有节点不在视口内就跳过”。对于与视口相交的边也可以做裁剪尤其是跨越很长距离的折线如果两端都不在视口内而且离视口很远就跳过不画。但要注意一条线的两个端点一个在视口内、一个在视口外这种线不能简单跳过还得画。第二刀是“缩放降级”。当画布缩放比例比较小的时候整个图都缩成一小块这时候再画节点内部的文字、阴影、渐变没有意义。我设置了两个阈值低于 0.6 不绘制文本低于 0.4 不绘制阴影和复杂状态图标。用户缩小后看到的是一块块色块反而比一堆糊掉的文字更清爽放大的时候又能看到完整细节。第三刀是网格缓存。网格背景每帧都是重复线段完全没必要跟着节点层一起重绘。我会在 resize 时创建一个独立的离屏 Canvas把所有网格线一次性画上去刷新时直接drawImage能省掉每一帧的几十次stroke调用。这个优化很小但对低端设备很友好。4. 常见问题与排查技巧实录4.1 坐标偏移和缩放失真十次里有八次是 DPR 问题做 diagram-design 过程中我被问得最多的一个问题就是“为什么我拖节点到某个位置松开后它跳了一下”。这通常不是事件逻辑有问题而是鼠标坐标换算不对。最常见的原因有三个。第一拿到的是offsetX / offsetY但 Canvas 的物理尺寸和 CSS 尺寸不一致鼠标偏移量没有除以缩放倍数。第二多 Canvas 布局时事件绑在最上层 Canvas但getBoundingClientRect用的是容器元素导致坐标系基准不统一。第三窗口更换显示器或者浏览器缩放后devicePixelRatio变化了但没有重置 Canvas 的 buffer 大小。排查这类问题我习惯在画布角落写一个调试面板同时显示三组坐标原生鼠标屏幕坐标、经过getBoundingClientRect换算后的本地坐标、经过screenToWorld后的世界坐标。然后在画布中心画一个十字标记用鼠标把它拖到网格交叉点上。如果视觉位置和实际数据的坐标对不上很快就能看出来是哪个环节丢了缩放因子。4.2 大数据量卡顿先从性能消耗大头开始查有段时间全图画到 4000 个节点、6000 条边时拖动节点每帧要 30 毫秒以上体感已经明显卡顿。我没有盲目去优化数据结构而是先用performance.now()把渲染的每个阶段都卡了一遍时间结果发现耗时大头有三个连线渲染占了接近一半因为每条边都画了带阴影的贝塞尔曲线节点文本绘制占用 30%因为在视口内有大量可见节点都要执行fillText最后 20% 来自阴影shadowBlur和各种状态判断。定位到具体原因后优化就是按部就班的事。连线默认从贝塞尔改成直线或简单的正交折线因为架构图里太多平滑曲线反而是视觉噪音文本绘制只在缩放阈值以上时才执行阴影改成绘制一个半透明圆角矩形作为“假阴影”而不是用 Canvas 原生shadowBlur后者性能实在太差。把这些改完之后同样一张图的拖拽帧耗时降到了 8 毫秒左右体感丝滑很多。这里有个经验先量化再优化。不要听人说“ShadowBlur 性能差”就立刻把阴影全部去掉你得先知道自己的卡顿是不是由它引起的。用分阶段计时器把所有耗时摆出来优化会变得异常朴素就是找到最大头干掉它然后再测。4.3 拖拽出画布后事件突然不触发了这类问题在桌面浏览器上不容易出现但在触摸屏和部分窗口环境下会偶发。现象是你按住节点快速拖出浏览器窗口再拖回来发现节点卡住了pointermove不再触发。原因在于鼠标指针移出画布后原来绑定在 Canvas 上的事件不再收到消息而pointerup也被浏览器吞掉状态机一直停留在“拖拽中”。解决办法有两个一是监听事件时直接挂在容器元素上而不是某个 Canvas 上让事件区域覆盖整个画布容器二是在pointerdown时主动调用setPointerCapture强制浏览器把后续指针事件都派发给当前元素canvas.addEventListener(pointerdown, (e) { canvas.setPointerCapture(e.pointerId); startDrag(e); }); canvas.addEventListener(pointermove, (e) { if (isDragging) updateDrag(e); }); canvas.addEventListener(pointerup, (e) { canvas.releasePointerCapture(e.pointerId); endDrag(e); });除了事件绑定还有一个容易被忽略的点是“多画布层级下事件到底发给谁”。如果四个 Canvas 叠在一起事件会自动派发给最上面的那个元素。为了统一我会把事件统一绑在最上层的交互画布上内部再通过screenToWorld换算到世界坐标而不是让每一层都处理自己的事件。这样即使未来把交互层重构掉事件入口也不需要改。4.4 主题定制最容易演变成颜色硬编码灾难业务上会同时出现深色模式、浅色模式、品牌定制色、状态告警色。如果一开始不把主题机制做出来后期就会在代码里到处写死#1890ff这种颜色而且每种节点组件还会再抄一遍。diagram-design 里我定义了一套Theme接口所有绘制函数只从theme读取颜色、线宽、字体不写死任何视觉参数interface Theme { background: string; gridColor: string; nodeFill: string; nodeStroke: string; nodeText: string; edgeColor: string; edgeWidth: number; selectionStroke: string; shadowColor: string; fontFamily: string; }节点绘制函数签名大概是drawNode(ctx, node, theme)内部用到颜色时一律theme.nodeFill、theme.nodeStroke。这样切换主题时只需要替换 theme 对象然后通知渲染层重绘即可。为了支持交互状态我还会在绘制前根据节点状态合并一个状态主题比如 hover 时边框加亮、selected 时描边换色、invalid 时填充变红。这个“状态样式叠加”不要和主题混在一起否则主题会膨胀得很难维护。顺带提一个教训不要为了“图省事”把颜色同时写进数据和 theme 里。如果业务节点的data里带了一个bgColor绘制时就会优先用它结果就是深色主题下个别节点依然白得刺眼。后来我明确规则业务数据可以控制内容但视觉表现统一走主题如果某个节点确实需要特殊颜色通过注册的节点组件显式声明而不是在通用渲染链路里开口子。5. 一些收尾的实践心得做 diagram-design 的过程里我最大的一点体会是这类项目看起来是绘图本质上是“数据描述、坐标转换、正确渲染”六个字。只要把数据模型定义清楚、坐标换算统一到同一个工具库、渲染层只消费不修改数据后续所有功能都能往里稳定叠加。反过来如果前期为了省事把坐标散落到各个组件里后面加自动布局和协同编辑时会痛不欲生。给准备入手的团队一个建议不要一开始就想着实现最复杂的全局自动布局和完美路由。先把“人工拖一张 20 个节点的图”做到流畅好用再逐步加自动布局、性能优化、大图支撑。因为人工编辑场景是所有高级功能的地基地基不稳自动布局排出来的图再漂亮也没法继续编辑。最后分享一个我自己的小习惯把所有边界操作整理成一个交互测试清单。比如“节点拖到画布外再拖回来”“缩放比例小于最小值时的提示”“框选时恰好从节点右下角开始”“导出图片时包含超出视口的节点”。每个边界情况都写成一个最小可复现 Demo每次改动后按清单过一遍。这个小清单帮我挡掉过至少三次回归问题也让我在加新功能时更有底气。diagram-design 到现在还在迭代后续考虑接入自动化布局推荐和更丰富的节点组件体系但这个“先让基础链路稳如磐石”的思路我会一直带下去。