★ FEATURED ARTICLE diagram-design 这个名字第一眼看上去会让人以为是个画图工具库的代号。真正把它做成一个能用的项目之后我才意识到它背后藏着的其实是一整套“交互式图编排引擎”的设计问题。我前后花了大概三周从零搭了一个可以拖拽节点、锚点连线、画布缩放平移、框选多选、撤销重做的图表设计器。如果你正在做流程编排、网络拓扑、架构图编辑器这类功能或者只是好奇一个可视化编辑器内部是怎么组织的这篇文章会把我踩过的坑、做过的取舍、改过的方案从头到尾讲清楚。这个项目适合的人群我大致分三类第一类是前端开发者想自己实现一个轻量图编辑器而不是直接套用现成商业库第二类是可视化方向的后端工程师想理解数据模型和渲染逻辑怎么解耦第三类是产品经理或技术负责人想评估自研图形编辑器的成本和边界。下面所有内容我都尽量按照“先讲为什么再讲怎么做”来写。1. 项目定位与整体设计思路1.1 到底要做什么不做什么diagram-design 从一开始就不是一个传统的图表库。传统的图表库解决的是“把数据渲染成折线图、柱状图、饼图”坐标轴、图例、动画这些是核心。而 diagram-design 要解决的是“让用户在画布上自由搭建一张图”节点可以拖来拖去节点之间可以连线画布可以缩放平移选中一个或多个节点可以批量移动或删除最终整张图可以导出成图片或结构化数据。想清楚“不做什么”比“做什么”更重要。我在项目第一天就列了一个边界清单不做自动布局。自动布局算法树形布局、力导向布局本身就是一个巨大的独立领域强行集成进来会拖垮交付周期。不做图形编辑器级别的复杂绘图比如钢笔路径、贝塞尔编辑、组合形状这些属于设计软件的能力。不做在线协作实时同步多人协同涉及 CRDT 或 OT 算法加上去复杂度指数级上升。让第一个版本专注于“单机、单用户、可交互、可导出”这个核心闭环是项目能快速跑起来的关键。1.2 技术选型SVG 还是 Canvas这是整个项目里最值得纠结的决策。市面上的图编辑产品大致分成 SVG 路线和 Canvas 路线还有少数用 WebGL。我把三者放在一起对比了一段时间维度SVG 渲染Canvas 2DWebGL节点数承载能力中等几百个节点尚可较高几千上万个节点可用最高十万级但成本极高交互热区命中浏览器自动处理事件需要自己做命中检测需要深度定制拾取方案样式定制CSS 内联样式非常灵活需要重绘逻辑写好样式函数学习成本极高开发效率高适合快速迭代中需要封装绘制层低不适合业务项目导出图片需要转 canvas 再导出天然支持 toDataURL复杂最终我选了 SVG 做主渲染。理由有几个节点数量中等时 SVG 的 DOM 事件模型可以省掉大量命中检测代码流程图、架构图这类场景下节点数量一般不超过三四百个SVG 完全扛得住样式可以直接用 CSS 控制hover 高亮、选中边框、拖拽透明度都很好做。Canvas 的优势要在超大图场景才明显但如果第一版就把渲染层选得太重开发效率会明显下降。选型之后我也没有完全抛弃 Canvas。画布的网格背景和缩略图导航是用 Canvas 画的因为这些东西不需要事件命中用 Canvas 画可以避免生成大量无意义 DOM 节点实测在连续缩放平移时性能更好。1.3 架构分层数据、渲染、交互三者解耦diagram-design 的代码结构严格分成三层数据层维护一份完整的图数据包含节点列表、连线列表、视口状态。这是唯一的事实来源所有操作最终都会落到数据层。渲染层监听数据层的变化把节点、边、标注符号渲染到画布上。渲染层不直接处理用户事件只负责“表达”。交互层捕获鼠标和触控事件调用数据层的 API 完成具体操作。交互层不直接修改 DOM 或 SVG 元素。这个分层方式在最初看起来有点绕但它解决了一个真实痛点如果没有数据层直接把拖拽逻辑写在 SVG 事件回调里当功能越来越多时代码会出现大量“这个地方改节点位置那个地方改线还有一个地方要刷新侧边栏”的隐形耦合。举个例子当用户拖拽一个节点时交互层只更新数据层里对应的节点坐标渲染层监听到坐标变化后重新计算该节点的所有连线路径并更新 SVG 元素。快速连线的重算逻辑不用担心去哪里拿最新数据直接从数据层读即可。撤销重做功能也只和数据层打交道撤销一个操作就是反着执行一次数据变更。这种稳定状态让项目后期扩展“右键菜单”“多选删除”“缩放定位到节点”都变得很快。2. 画布坐标系与节点模型最容易被忽略的底层细节2.1 逻辑坐标和屏幕坐标必须分开第一次写图编辑器时最容易犯的错误就是节点位置直接用鼠标事件的屏幕坐标赋值。这个做法在画布不缩放时看起来很正常一旦加上缩放问题就全来了——zoom 变成 1.5 的时候节点要么跟不上鼠标要么乱跳。正确做法是维护两套坐标屏幕坐标screen鼠标事件返回的坐标相对浏览器窗口。逻辑坐标logic图数据里真实使用的坐标相对画布内容本身。转换关系很简单核心是把 viewport 的偏移量pan和缩放值zoom带上// 屏幕坐标转逻辑坐标 function toLogic(screenX, screenY, viewport) { return { x: (screenX - viewport.panX) / viewport.zoom, y: (screenY - viewport.panY) / viewport.zoom }; } // 逻辑坐标转屏幕坐标 function toScreen(logicX, logicY, viewport) { return { x: logicX * viewport.zoom viewport.panX, y: logicY * viewport.zoom viewport.panY }; }这套公式几乎适用于所有操作。拖拽节点的流程是按下鼠标时记录节点的逻辑坐标和鼠标的屏幕坐标移动时计算“鼠标屏幕坐标的增量”保存到节点数据里的永远是“逻辑坐标的变化量”。缩放的唯一作用是在“屏幕坐标到逻辑坐标”的转换中体现数据本身不因缩放而改变。为什么必须按这个思路做原因在于节点的位置是业务数据它应该代表图中某个点在世界里的位置而不是它碰巧在屏幕上出现在哪里。只有把视口状态独立出来缩放和拖动视图才只是“换了一副眼镜看数据”而不是去修改世界本身。项目后期增加“导出图片”时这个设计直接让导出逻辑变成“把视口设为整图范围再逐项绘制即可”。2.2 节点数据模型与端口机制节点虽小它的数据模型却直接决定后续所有功能的复杂度。我第一版只有一个矩形节点字段是 id、x、y、width、height很直接。但加到连线功能之后就发现不够了。所有连线都应该连接节点上的一个“端口”port而不是直接连在节点中心或无规则位置。端口是一个节点上预定义的锚点常见的端口有三个顶部端口top底部端口bottom图形形状的固定锚点一个节点可以对应多个端口数据模型设计如下{ id: node-a, type: rect, x: 100, y: 120, width: 140, height: 60, ports: [ { id: node-a-top, name: 顶部, direction: top, offsetX: 0.5, offsetY: 0 }, { id: node-a-bottom, name: 底部, direction: bottom, offsetX: 0.5, offsetY: 1 } ] }port 的 position 不写死像素值而用 offsetX、offsetY 表示相对节点矩形的位置比例。这样当节点尺寸变化时端口能自动跟随不需要手工同步。渲染时端口坐标等于portX node.x node.width * port.offsetX; portY node.y node.height * port.offsetY;把端口机制设计好之后连线功能可以站在这上面从端口 A 拖出一条线到端口 B线就会正确地吸附在两个端口上即使端口所在节点被拖动连线也跟着变。不用端口机制的图编辑系统也能做出来但连线常常显得粗糙要么端点在节点内部要么需要手工调线位置给用户的感受是“这里不太对”。2.3 边的渲染贝塞尔曲线与端点交点计算节点之间的连线我第一版用的是直线效果非常粗糙。当一条边从 A 节点的底部端口连到 B 节点的顶部端口时直线会穿过节点自身的边框视觉上非常混乱。后来改成贝塞尔曲线同时加入了交点计算。贝塞尔曲线的控制点采用了水平或垂直控制的方式伪造出一种“正交化”的观感。对从左侧连到右侧的边控制点可以这样计算const dx Math.abs(sourceX - targetX) * 0.5; const pathData [ M ${sourceX} ${sourceY}, C ${sourceX dx} ${sourceY}, ${targetX - dx} ${targetY}, ${targetX} ${targetY} ].join( );核心点是sourceX/sourceY 不是端口直接坐标而是端点在节点矩形边界上的焦点的坐标。如果不做交点计算曲线会画到节点的内部去看起来就像是线条穿过了方块。求交点的做法基于射线检测从端口中心向目标一侧发出一条射线求这条射线与节点矩形的第一个交点。简化实现如下function getBorderPoint(portCenter, targetPoint, nodeRect) { // 根据端口方向确定射线求与矩形边界的交点 const dx targetPoint.x - portCenter.x; const dy targetPoint.y - portCenter.y; // 按比例参数 t 进入边界 let t Infinity; if (dx ! 0) t Math.min(t, (dx 0 ? nodeRect.right - portCenter.x : nodeRect.left - portCenter.x) / dx); if (dy ! 0) t Math.min(t, (dy 0 ? nodeRect.bottom - portCenter.y : nodeRect.top - portCenter.y) / dy); return { x: portCenter.x dx * t, y: portCenter.y dy * t }; }这个函数要小心 t 可能为负数或无穷大的情况实际代码里还要加边界保护。之后我把它扩展为支持“边线从端口连接点发出就先走到矩形外侧的辅助线再走曲线”的样式可视效果又上了一个台阶。很多图编辑器的连线核心其实就这么一个几十行的函数。3. 实操全流程把一个可用的图设计器跑起来3.1 主循环与事件模型图编辑器的交互核心不是某个具体的处理函数而是一整条事件链条。我采用的是 Pointer Events 而不是 Mouse Events因为 Pointer Events 天然覆盖鼠标和触控笔桌面端和触屏端可以共用一套逻辑。交互层的事件流程是监听画布容器的 pointerdown 事件记录按下时的屏幕坐标。根据坐标命中检测判断用户按到的是节点、端口、连线还是空白背景。根据命中对象分别初始化不同操作模式拖节点、拉连线、框选空白区域。监听后续的 pointermove 和 pointerup在移动过程中实时更新数据层。pointerup 时结束模式整理一次历史记录。事件委派方面我没有在每个 SVG 节点上都绑定事件而是给画布容器统一绑定事件然后在内部做命中检测。这样做的好处是新加的图形类型不需要单独管理事件删除节点时不用担心遗留事件监听。SVG 的 isPointInFill 和 isPointInStroke 有时能用但如果节点复杂还是自己写矩形碰撞检测稳定。svgElement.addEventListener(pointerdown, (e) { const pos screenToClient(e); const target hitTest(pos.screenX, pos.screenY); if (target.type node) startDragNode(target.nodeId, pos); else if (target.type port) startConnect(target.nodeId, target.portId, pos); else startRubberBand(pos); });3.2 拖拽移动与框选多选的实现要点拖拽节点时我建议不要每移动一个像素就直接改数据触发全量渲染而是用 requestAnimationFrame 把待更新的节点收集起来在下一帧统一渲染。这个优化在节点少时看不出来但当画面上有三十个节点同时被框选移动时区别是天壤之别。let dragDirty false; const dragBatch new Set(); function onPointerMove(e) { const dx e.screenX - dragStart.screenX; const dy e.screenY - dragStart.screenY; dragTargets.forEach(nodeId { const node graph.getNode(nodeId); node.x dragStart.nodes[nodeId].x dx / viewport.zoom; node.y dragStart.nodes[nodeId].y dy / viewport.zoom; dragBatch.add(nodeId); }); if (!dragDirty) { dragDirty true; requestAnimationFrame(renderDirtyNodes); } }框选功能的底层是矩形相交测试。用户拖出一个蓝色矩形选区只要节点矩形和选区矩形相交就认为节点被选中。这里我加了一个细节选区模式下按下 shift 时把原有选中集合与新选中集合做差集/交集运算否则替换选中集合。大多数图编辑器都有这个习惯如果第一版不做好用户一旦习惯多选操作之后就会觉得编辑器“不专业”。3.3 连线交互从端口到端口的完整闭环从端口拖出连线是图编辑器中最有仪式感的交互。完整流程包括按下端口时记录源端口并创建一条临时连线。临时连线使用虚线样式并跟着鼠标位置更新。移动过程中实时检测鼠标是否悬停在某个可连接端口上是的话高亮它。松开鼠标时检查目标端口是否存在且不是源端口自己满足条件则创建正式边否则取消临时线。检测目标端口不需要全图扫描。端口数量通常不多直接遍历即可。但要注意排除不可连的情况一个端口可以设置“出”或“入”方向只允许“出”连“入”不允许“出”连“出”。这是从数据流系统里继承来的约束。创建边后我还会自动给边生成一个 id并记录它是从哪个端口连到哪个端口。此时数据层的 edge 结构如下{ id: edge-1, source: { nodeId: node-a, portId: node-a-bottom }, target: { nodeId: node-b, portId: node-b-top } }渲染层根据这个结构每次动态计算出线路径而不是保存一组固定路径坐标。因为一旦节点移动计算必须重新做所以线的坐标不是持久化数据计算才是。3.4 数据序列化与多格式导出图设计器最核心的价值是“做好的图能带走”。我设计了三种导出方式JSON完整的工程文件包含节点、连线、端口、视口信息可以重新加载编辑器。SVG矢量图适合文档插入和二次编辑。PNG位图适合直接贴到聊天工具或者报告中。JSON 的 Schema 必须带有 version 字段。这个版本号在初始开发时看不出价值但项目一旦开始迭代数据结构变化就需要版本迁移函数。如果没有 version老数据在编辑器升级后就会变成一团乱。我吃过这个亏某次给节点增加了 theme 字段结果旧数据因为缺少该字段被默认值渲染得乱七八糟排查了很久才发现是旧文件没有带版本。导出 SVG 的做法是用一个脱离画布的独立 SVG 根节点遍历数据生成节点、连线和文本子元素最后用 XMLSerializer 序列化成字符串。文本节点要注意字体宽度和换行同一段文字在浏览器里的宽度和导出 SVG 在另一台机器上的宽度可能不一致所以导出时我会把文本行用 tspan 明确拆分出来而不是让接收方依赖自动换行。导出 PNG 的做法是把画布内容重新绘制到一个离屏 canvas 上。这里有一组坑如果图很大canvas 要按 zoom1 的实际尺寸创建在绘制前要把所有涉及图像的素材都加载完成如果导出内容中包含外部图片跨域问题会导致画布被“污染”toDataURL 直接抛错。我的做法是在编辑器内部设置图片代理标识导出时候转换成安全的 base64 数据从源头规避跨域。3.5 性能优化哪些该做哪些不该做很多刚上手图编辑器的人会过早优化节点还没五十个就开始琢磨虚拟滚动、四叉树、Canvas 渲染。我的实际经验是性能问题必须先用性能分析工具定位再针对性优化。第一优先级优化是“减少 DOM 突变”。节点拖动过程中我用 rAF 批量更新把同一帧内的移动合并成一次变换。实测在 200 个节点同时拖拽的场景里渲染帧率能达到 60 帧上下而不做合并时会掉到 30 帧以下。第二优先级是“减少重算范围”。连线路径重算只涉及与被移动节点相连的边不需要全局重算。我用邻接表保存每个节点的出入边 id节点移动时只更新邻接表里的边。第三是命中检测优化节点数量超过 500 时我用网格索引把整个画布切成若干区块鼠标命中时先定位区块再遍历区块内的节点减少全量比对耗时。有些优化真的不需要做。比如把一个 200 行的线性遍历全部改成哈希索引收益微乎其微还增加了代码复杂度。图编辑器的瓶颈普遍不在“数据查询”而在“渲染更新”和“事件链长度”先把这两件事做对性能基本就够了。4. 常见问题与排查实录4.1 坐标漂移缩放后拖拽节点总是对不准鼠标这是一个必踩的经典坑。现象是画布 zoom 不为 1 时按下节点开始拖动节点移动方向正确但速度要么快要么慢最终位置和鼠标位置明显偏移。根因在于直接用屏幕坐标增量去更新逻辑坐标。假设当前 zoom2鼠标在屏幕上移动了 4px但逻辑坐标只应移动 2 个单位如果直接用 4px 作为逻辑坐标增量节点就会以两倍速度跑。解决办法在 2.1 的公式里已经给出但这里我再补一条实操经验拖拽开始时必须把节点的起点逻辑坐标和鼠标的起点屏幕坐标都记录在状态里移动中始终用“当前屏幕坐标 - 起始屏幕坐标 起始逻辑坐标”计算新位置而不是用累计增量方式。因为累计增量在连续精度丢失后容易产生漂移直接基于起始状态计算则每帧都是精确的。4.2 连线端点穿进节点内部连线一端在节点矩形中心附近另一端才从正确端口出来看起来就像线长在节点肚子里面。这个问题的原因是边路径直接以端口原始坐标作为端点没有做过矩形边界交点计算。修复方案就是实现 2.3 中的 getBorderPoint。还有一个额外细节不要使用端口中心点作为源点去算曲线要从端口中心点沿着“指向目标端口的方向”求交点后再用交点作为曲线端点。这样线从节点边界发出视觉上才干净。另外如果节点带圆角或者装饰边框最简单的方法是预留一个“内边距”值把交点计算用的矩形往里收缩几个像素视觉纠正效果好很多。4.3 撤销重做栈的内存增长失控撤销重做如果直接保存整份数据快照在画布内容稍大时内存会迅速爆掉。比如 300 个节点的图快照一次可能要几百 KB用户连续操作 20 次就占掉十几 MB还把 GC 压力搞上去了。我的做法是命令模式每类操作对应一个命令对象命令记录的是“反向执行所需的最小信息”。移动节点命令记录每个被移动节点移动前的位置和移动后的位置撤销时把位置改回去创建边命令记录边的完整数据撤销时删除边。删除节点命令则需要把被删除节点以及与之相连的边全部备份下来撤销时一并恢复。命令模式的一个附加好处是操作自动具备可组合性。拖拽几个节点时连续的 mousemove 会产生很多个中间位置我会在释放鼠标时将整个拖拽会话合并为一个命令而不是每个像素变化都记录一条历史。合并逻辑是按下时创建命令对象移动中只更新命令的结束状态释放时提交到历史栈。4.4 吸附对齐时的高频判断导致拖拽卡顿开启节点吸附对齐后拖拽节点时要实时计算参考线包括画布中心线、节点中心线、节点边缘线等。如果每移动一个像素就对全图所有节点参考线做一次距离计算和绘制性能压力巨大尤其在节点多时。我的优化分两步。第一步在拖拽时只搜索距离当前节点“一定阈值”以内的参考线超出阈值的直接忽略第二步把参考线的收集计算从 rAF 渲染回调放到一个独立的低优先级循环里即使某帧没计算完成也不阻塞主交互。吸附实现时还要注意一个反向问题开启吸附后节点会被“吸”到参考线上如果用户想微调但又不想吸附通常需要按住 alt 键临时禁用吸附。这个交互细节在成熟编辑器里几乎是标配我第一版没做后来发现测试时经常有人说“节点为什么自己跳来跳去”加了这个开关后就没人抱怨了。4.5 问题排查速查表现象常见根因处理方式拖拽节点坐标漂移屏幕坐标与逻辑坐标混淆统一使用逻辑坐标增量除以 zoom缩放后节点缩放变形对节点的 width/height 应用了 zoom 缩放节点大小保持逻辑尺寸由 render 层统一转换框选时节点闪烁选中样式和渲染更新不同步选中状态放到数据层渲染层按数据刷新连线只剩一条直线控制点计算缺少目标方向分支根据 source/target 相对位置选择左右或上下控制点撤销后连线不回显边数据存在临时对象未进历史栈确保创建/删除边都生成命令对象导出 PNG 空白Canvas 在图片资源未加载时就绘制先 await 所有图片加载完成再绘制导图5. 一些想补充的经验心得如果让我再写一遍 diagram-design我会把数据层的定义做得更早、更严格。第一次写的时候我因为偷懒让渲染层直接访问了节点的内部属性图省事跳过数据转换结果每次重构某个样式都要回头改好几处。后来把“唯一的入口是 Graph 对象的方法”作为铁律代码质量立刻稳定下来。在交互层还有一个很小的细节值得分享所有拖拽和框选的坐标在进入逻辑坐标空间之后最好做一次四舍五入。否则节点在不为整数的位置时SVG 渲染出来的边缘会发虚字体也模糊。看起来是小问题但对用户来说一个拖起来边缘一直发虚的编辑器很容易被判定为“不太行”。最后是个心态问题。图编辑器这种项目的复杂度不体现在算法上而是体现在细节链路中一次拖拽经过事件捕获、坐标转换、数据更新、连带边重算、历史记录、渲染刷新任何一环出现偏差最终效果都会出问题。调试时不要只盯着渲染代码逐行看而是顺着整条链路去检查每个环节的数据是否一致。我调试 4.1 坐标漂移问题的时候就是先画出了三组坐标鼠标屏幕坐标、鼠标逻辑坐标、节点逻辑坐标一对比立刻发现了异常比盲目改代码要高效得多。这次项目做完最大的感受是可视化编辑器的核心从来不是绘制图形而是把图形当成数据来管理。只要数据模型切得足够干净后续加什么功能都不会太难。diagram-design 目前还只是一个人工规划、静态导出的阶段下一步我打算给它补上自动布局接口和组件的复制粘贴组合逻辑方向上依然是围绕数据模型做文章。如果你也在做类似的图编辑项目欢迎沿着数据处理这条主线继续往下钻这条路的每一个点都还大有空间。
阅读完成 · 觉得有帮助？
