diagram-design 这个项目是我在给内部低代码平台补流程图功能时被逼出来的产物。市面上现成的绘图组件要么太大太重要么定制一个交互细节要翻半天源码索性自己动手实现了一个轻量级的图设计引擎。做完之后发现这个领域看着简单真正落地时全是细节坐标怎么换算、锚点怎么命中、撤销重做怎么做才不卡、缩放平移怎么才能顺滑。这篇就把我从需求拆解到核心交互实现的全过程摊开来讲。整个项目不算大核心实现量大约在三千行左右但涉及到了图可视化编辑器的几乎所有基础能力节点模型、连线模型、坐标系变换、拖拽交互、多选框选、撤销重做。无论你是在做流程编辑器、架构图工具、脑图产品还是单纯想在项目里嵌入一个可以拖拽的绘图面板这篇内容都能直接拿来参考。我会把每一步的设计原因、代码结构和踩过的坑都写清楚尽量做到你看完就能自己复现。1. 这个工具到底要做什么需求与边界1.1 一眼看懂 diagram-design 是什么diagram-design 本质上是一个面向 Web 的轻量级图设计引擎核心能力是让用户在白板式的画布上自由创建节点、拖拽位置、用连线表达关系并且支持缩放、平移、多选、撤销重做这些编辑器级的基础操作。它不追求像专业绘图软件那样面面俱到而是把图表编辑里最常用、最核心的那条路径打磨顺。我一开始给自己定的目标是任何情况下从鼠标按下到完成一个节点的创建或一条连线的建立时间不能超过两秒操作不能超过三步。这个目标听起来容易实际上对交互设计要求很高。比如拖拽一个节点到另一个节点上自动吸附、连线时自动识别目标锚点、框选时多选命中范围这些体验细节都直接影响这两秒能不能成立。这个工具适合谁来参考如果你正在做或者准备做任何形式的可视化编辑器我的经验是不要一上来就接一个大型框架。先拆清楚自己的核心操作路径用最朴素的方式把模型和交互打通等确定模型稳定了再考虑迁移到成熟方案。diagram-design 的价值就在于把这条路径上的所有关键技术点都摊开讲清楚了。1.2 功能清单与不做清单每个项目开始之前必须先划定边界。我给 diagram-design 定的功能范围是这样节点操作创建、删除、拖拽、修改尺寸、层级调整置顶置底连线操作锚点连线、折线自动布局、跟随节点移动、删除画布操作缩放、平移、框选、多选、删除批量节点状态操作撤销、重做、保存与恢复序列化辅助能力对齐参考线、吸附网格、右键菜单预留同时我明确列了一个“不做清单”不做自动布局算法那是图形算法领域的事、不做复杂图元库、不做多人协同的冲突合并、不做移动端触屏适配。这些功能除非你的核心场景真的有刚需否则只会无限拉长开发周期。这个清单带来的直接好处是技术方案可以极简化。比如因为不需要多人协同我就完全不用考虑 Operation Transform 这类复杂算法状态管理只需要管好本地一份数据。不做自动布局就省掉了力导向、层级布局这一整套图形计算。每一块被砍掉的功能都是在给自己省时间也是在降低出 bug 的维度。1.3 技术选型为什么选 SVG 而不是纯 Canvas图编辑器领域有个经典争论渲染层到底用 SVG 还是 Canvas。我的选择是主渲染用 SVG部分辅助图层用 Canvas 或者干脆用绝对定位的普通 DOM。原因很简单diagram-design 的节点数量级在中低规模几百个以内在这个范围内 SVG 的 DOM 事件模型天然适合交互每个节点、每条连线都是一个独立的 DOM 元素click、mousedown、mouseenter 这些事件不需要自己做坐标命中计算就能直接绑定。Canvas 的优势在大规模渲染但代价是所有的拾取picking逻辑都要自己实现。比如你要判断用户点到了哪条线上就必须自己做线段距离计算要判断点到了哪个节点又得做矩形碰撞检测。这些不是不能做而是对一个初始版本来说开发成本和调试成本都很高。SVG 的缺点主要在性能上节点到几千个之后操作会明显变慢。我的折衷方案是静态场景下用 SVG 渲染连续拖拽过程中用 CSS transform 直接操作 DOM 元素而不是改 SVG 属性。CSS transform 走的是合成器线程不触发布局和绘制实测在中等画布下拖拽流畅度足够。如果后面真遇到几千节点的场景再考虑把渲染层替换成 Canvas但数据模型和交互逻辑都不用动这就是模型与视图分离设计带来的好处。2. 最容易被低估的部分图元模型与数据结构2.1 节点模型设计图编辑器的数据模型是整个项目的基石这块如果设计松了后面每一步交互实现都会痛苦。节点模型我最终是这样定义的export type NodeType rect | circle | diamond | text; export interface DiagramNode { id: string; type: NodeType; x: number; y: number; width: number; height: number; zIndex: number; attrs: { label?: string; fill?: string; stroke?: string; strokeWidth?: number; fontSize?: number; }; // 每个节点的四个锚点连线时使用 anchors?: Anchor[]; }关键设计决策有两点。第一id 必须是稳定且全局唯一的不能拿数组下标当 id。因为连线、撤销快照、序列化持久化都依赖 id 做引用一旦用下标数组顺序一变全线崩溃。第二x、y 保存的是节点的左上角坐标而不是中心点坐标。左上角坐标在框选、拖拽、对齐参考线时计算更直观和图形 API 的默认行为也一致。锚点Anchor这个设计很多人会忽略但对连线体验影响巨大。每个节点我默认生成四个锚点上、下、左、右外加一个中心锚点。锚点的位置不是存死的而是根据节点当前尺寸实时计算的。比如右侧锚点的坐标永远是(x width, y height / 2)。这样做的好处是节点一旦拖拽缩放锚点自动跟随不需要额外同步逻辑。export interface Anchor { id: string; direction: top | bottom | left | right | center; // 实时计算位置不存静态坐标 }2.2 连线模型设计连线比节点复杂得多因为一条连线可能经过多个转折点而且当它关联的节点移动时连线必须跟着变。我设计的连线模型长这样export interface NodeRef { nodeId: string; anchorId: string; } export interface DiagramEdge { id: string; source: NodeRef; target: NodeRef; // 中间转折点列表按顺序连接 points: Array{ x: number; y: number }; style?: { stroke?: string; strokeWidth?: number; arrow?: none | target | source; }; }这里最重要的设计决策是连线的起点和终点不直接存坐标而是存“引用”NodeRef。这样节点移动后连线可以重新计算端点的坐标但也带来一个新问题如果移动节点后直接改连线的 points节点的坐标一变折线就全部错位了。我的做法是连线数据里不存冗余的端点坐标只保存中间转折点。渲染时根据 source 锚点和 target 锚点的实时坐标加上 points 里的中间转折点动态生成最终的路径。在执行上节点移动时会触发一个rerouteEdge操作重新计算所有关联连线的转折点。对于相对简单的场景我先用直角折线正交连线算法先判断两个锚点的相对方位决定先走水平还是先走垂直中间最多生成两到三个转折点。2.3 画布坐标系不要把所有坐标都存成屏幕坐标这个坑几乎是所有绘图编辑器开发者的第一步必踩的坑。如果你在缩放或平移之后发现节点和鼠标位置对不上十有八九是坐标系统搞混了。我用了三套坐标的概念来避免这个问题世界坐标Model Coordinate节点和连线统一存放在这个坐标系里单位是逻辑像素与缩放比例无关。视口坐标Viewport Coordinate画布上实际显示出来的坐标等于世界坐标乘以缩放比例再加上平移偏移量。屏幕坐标Screen Coordinate浏览器页面的实际像素坐标viewport 坐标再加上画布 DOM 元素在页面里的偏移量。三者的换算关系是screenX worldX * scale panX canvasOffsetX screenY worldY * scale panY canvasOffsetY鼠标交互拿到的永远是 screen 坐标你所有的数据操作都应该换算到 world 坐标再执行。我封装了一组工具函数比如screenToWorld(clientX, clientY)和worldToScreen(worldX, worldY)并且强制规定在事件处理器里第一步就把屏幕坐标转成世界坐标后面所有逻辑一律只操作世界坐标。这个约定帮我避免了至少几十个疑难 bug。2.4 缩放与平移的实现策略缩放和平移我用的是 Transform 模型的中心方法。store 里维护一个viewport对象interface Viewport { scale: number; panX: number; panY: number; }渲染 SVGRoot 节点时用一个g transformtranslate(panX, panY) scale(scale)包住所有的图元。所有世界坐标都画在这个g里面缩放平移只改这一层 transform。这个方案的优缺点都很明显。优点是每次缩放平移只更新一个 transform浏览器原生处理速度快而且所有内部元素的坐标完全不用改。缺点是缩放之后 SVG 里文字、线宽这些会跟着放大缩小导致大图时线宽粗得离谱缩小时字小得看不清。我的处理方式是给连线的 strokeWidth 和节点的 fontSize 做反向缩放补偿实际渲染值等于设计值除以当前 scale。这样视觉上字号和线宽恒定体验和 canvas 手写类似。要注意这个补偿值只在 render 时计算不能写回 model 数据否则数据会被污染。3. 核心交互的完整实现过程3.1 拖拽创建节点节点创建的交互路径有很多种从左侧面板拖出一个图元、右键菜单添加、直接快捷键复制。我的实现优先支持从面板拖拽创建因为这个交互对用户体验最友好同时坑也最多。流程拆开是四步。第一步在左侧物料面板的每个图元上监听 mousedown记录起点屏幕坐标并把当前画布的 viewport 状态快照保存下来。第二步mousemove 时创建一个临时浮动的节点元素跟随鼠标移动此时在 store 里只做一个 preview 节点标记为isPreview true。第三步鼠标移动时实时检测当前鼠标位置是否落在画布区域内如果落在画布外就显示一个禁用样式。第四步mouseup 时把屏幕坐标换算成世界坐标设置新建节点的位置去掉 preview 标记正式提交进入 store。这里有一个非常关键的细节mousedown 发生在面板上时mousemove 和 mouseup 事件必须绑定到 window 上而不是绑定到面板或者画布上。原因是用户一旦按下鼠标后续事件可能在页面任意位置触发。如果只绑定在画布上鼠标快速移出画布后事件就丢了会出现“鼠标松开但拖拽没结束”的灵异现象。正确写法是 mousedown 时 window.addEventListener(mousemove, handler) 和 window.addEventListener(mouseup, handler)在 mouseup 之后统一移除。这套逻辑在拖拽节点、框选、连线等所有拖拽型交互里都要用。3.2 锚点连线的交互流程连线交互是图编辑器里最容易写乱的部分。我的实现思路是连接行为分成两个阶段第一阶段从源锚点拖出一条临时连线第二阶段在目标锚点上松手完成连接。具体交互流程是这样。第一监听每个锚点元素的 mousedown记录 source 锚点引用设置 editorState 为connecting。第二mousemove 时根据当前鼠标位置实时画一条临时线段或者曲线。如果当前没有悬浮在目标锚点上临时线的终点就是鼠标位置如果悬浮到了目标锚点上方临时线终点吸附到目标锚点上并给目标锚点加一个高亮样式。第三mouseup 时先取当前鼠标位置遍历所有可见锚点做命中测试。命中测试不是简单的“鼠标坐标等于锚点坐标”而是判断鼠标位置到锚点的距离是否在一个阈值范围内我采用的阈值是 10 个屏幕像素。命中成功就创建正式连线否则取消。连线实时绘制阶段我额外做了防抖处理mousemove 事件触发非常频繁每个事件都直接改 store 会引发大量渲染。我用了一个 requestAnimationFrame 的节流函数把最新的鼠标位置保存到一个临时变量里每个动画帧只读取一次这个变量来更新临时连线路径。这样一来即使 mousemove 每秒触发 60 次甚至 120 次实际的渲染频率也被限制在屏幕刷新率以内拖动明显更跟手。3.3 框选多选框选是多选操作的基础。用户在画布空白区域按下鼠标左键并拖动时绘制一个蓝色的半透明矩形鼠标松开时所有与矩形相交的节点被选中。矩形相交检测用 AABBaxis-aligned bounding box方法就是判断两个矩形是否有交集代码很简单function rectIntersect(rect1, rect2) { return !( rect1.x rect1.width rect2.x || rect2.x rect2.width rect1.x || rect1.y rect1.height rect2.y || rect2.y rect2.height rect1.y ); }但要注意一个细节框选区域是在屏幕坐标上绘制的而节点位置是世界坐标。你不能直接拿屏幕坐标的矩形和世界坐标的节点做相交判断必须先统一坐标系。我的做法是框选开始时记录起点世界坐标拖动过程中每次更新终点世界坐标最终形成一个世界坐标下的选择矩形再和所有节点的世界坐标做相交判断。这样框选在所有缩放级别下行为都一致。选中之后就需要维护一个 selection 状态里面保存一组选中的节点 id。所有后续操作比如删除、整体拖拽、属性面板展示都基于这个 selection。整体拖拽选中的多个节点时我会在拖拽开始时记录每个节点的原始位置然后把每次的鼠标位移增量统一加到所有选中节点上这样保证多节点相对位置不变。这里又是一个容易翻车的地方增量必须是世界坐标的增量不能直接加屏幕坐标的增量否则缩放状态下多选拖拽会和鼠标错位。3.4 撤销重做命令模式与快照撤销重做实现方案我对比过两种。一种是命令模式Command Pattern每个操作封装成一个可逆的类有 execute 和 undo 两个方法。优点是内存占用少、语义清晰缺点是每个操作类型都要单独实现反向逻辑比如拖拽节点可以记录前后位置做反向但复杂操作比如框选删除、批量移动、连线重路由反向逻辑很容易漏漏一个就是撤销后数据错乱排查成本很高。我最终采用了另一种更简单粗暴的方案快照模式。每次发生“可撤销操作”之前把整个图数据做一次序列化快照压入撤销栈。撤销时从栈中取出一份快照整体恢复重做时再从重做栈弹出历史快照。实现量很小而且因为每次撤销都是整体恢复不会存在“只恢复了一半”的情况。快照模式的核心问题是内存和序列化性能。我的解法有三个。第一所有节点和连线的数据都是纯 JSON 兼容对象没有函数、没有循环引用直接用JSON.stringify序列化。第二撤销栈深度控制在 50 步以内超过就丢弃最老的快照。第三对大图场景做了一个简单优化只在用户的连续操作停止 300ms 后才生成快照而不是每次 mousedown 都压栈。拖拽一个节点从开始到松开整个过程算一步操作最终只保存一次快照。这个时间窗口的实现方式也简单每次操作开始时设置一个 timer操作过程中 timer 不断重置操作结束后 300ms 快照才会真正生成。代码看起来不多但在实际上手体验中这个细节决定了一个操作算一步还是算一百步。4. 实测中踩过的坑问题排查与优化实录4.1 坐标换算为什么总是差一截我在开发初期遇到一个非常诡异的现象拖拽节点时节点总是“慢半拍”或者“偏一段距离”。排查了很久最后发现问题出在获取 canvas 偏移坐标时用了错误的接口。有人会下意识用getBoundingClientRect()返回的值直接做减法但在 SVG 内部元素上有getScreenCTM()这个方法它返回当前元素到屏幕坐标系的变换矩阵在缩放平移场景下比手动计算可靠得多。坐标换算的稳定写法是这样的function screenToWorld(clientX, clientY) { const svgRoot diagramSvgRef.current; const pt svgRoot.createSVGPoint(); pt.x clientX; pt.y clientY; const inverted svgRoot.getScreenCTM().inverse(); const worldPt pt.matrixTransform(inverted); return { x: worldPt.x, y: worldPt.y }; }这个方案有三个好处缩放、平移、SVG 自身的偏移量全部由浏览器矩阵运算处理不需要你手动去减 panX、减 canvas 偏移、再除 scale逻辑上完全不重。而且即使未来 SVG 结构变了只要根节点上的 viewport transform 不变这套换算仍然成立。强烈建议所有坐标换算都走这个函数不要在事件处理器里到处手写加减乘除。4.2 锚点不好点中的问题锚点连线的第一个版本上线后用户普遍反馈“连不上线太难聚焦了”。问题根源在于锚点的可视化尺寸只有 6 像素鼠标稍微偏一点就点不中。我知道不能用“把锚点做更大”这种粗暴方式解决因为太大锚点会遮挡节点内容。最终的解决方案是“视觉尺寸和命中尺寸分离”。视觉上锚点仍然显示为 6 像素的小圆点但命中区域扩大到 12 像素。做命中测试时不是检测鼠标是否精确落在圆内而是计算圆心的距离是否小于命中半径。更进一步鼠标靠近目标锚点时给锚点增加一个放大的 hover 样式等于做了一个隐式的交互反馈告诉用户“你可以在这里松手连上”。这个体验优化让连线成功率几乎提升了百分之四十。4.3 拖动时卡顿与事件丢失拖动卡顿分两种。一种是连续的 mousemove 触发太频繁导致渲染压力过大另一种是每次鼠标移动都在触发重渲染和重算所有连线。第一个问题的解法我在前面说过用 requestAnimationFrame 节流。但有一点要补充的是这个节流不能作用在事件监听的注册上mousemove 监听每一次都要执行但只有最后一次位置被记录下来真正触发渲染的是一个独立循环。也就是说事件处理函数里只做赋值操作不做任何计算和渲染。这个“读事件、写变量、帧渲染”的模式在交互密集场景下是核心原则。第二个问题的解法是“脏标记机制”。store 里维护一个dirtyFlag当拖拽节点、移动连线等操作发生时先标记脏再通知渲染层按需刷新。如果没有任何操作发生mousemove 就是不产生任何计算的“空转”。另外还有一个细节拖拽过程中不重算关联连线的完整路由只先用一条临时的近似曲线把连接关系表示出来拖拽结束时再统一重算路由。视觉上用户不会在意连线路径在松手前是精确的还是近似的但性能上这个节省非常可观。4.4 撤销重做吃内存、大图卡的问题快照模式做撤销重做图一旦大起来内存飙升是个很现实的问题。几十个节点的时候无所谓几百个节点每次快照带上完整的路由信息、样式属性一串 JSON 序列化出来轻松达到几兆字节。50 步历史就是几百兆页面直接崩。我做了三件事来解决。第一深层冻结和浅拷贝分开nodes 数组用新的数组对象但里面的节点对象保证不可变immutable快照只是保存一个对旧引用集合的引用而不是把所有数据复制一遍。这个对内存的节省是数量级的。第二序列化时去掉非必要字段比如实时计算的 points 不需要保存路由可以在恢复时重新计算。第三快照延迟生成和上限控制前面说过的 300ms 等待和 50 步上限这两个值要根据实际图规模调整。如果你用量测试发现还是扛不住几百个节点的快照可以考虑把撤销策略降级为只保存操作命令这是比较后期的优化方向但模型和交互层完全不用动。4.5 一个容易忽略的小细节连线跟随移动画布上拖动节点它的所有连线必须同步改变端点。在我第一版实现里节点错位、连线弯折得非常难看原因是我只更新了连线的 source 和 target 引用但没有重新计算中间转折点。直角折线路径全部变成了僵硬的斜线。修正方案是在拖拽结束时统一重算所有关联连线的路由。具体会遍历所有以这个节点为 source 或 target 的连线调用一个routeEdge函数根据最新的锚点坐标重新计算中间转折点再更新到模型里。为了性能拖拽过程中我只让连线端点实时跟随转折点保持不变拖拽结束才整体重路由。这个折衷策略让视觉连续性和性能都得到了保证。5. 一些实操中不太会被写进文档的细节整个项目做完再回头看真正拉开体验差距的往往不是某个高深算法而是一些平凡的细节策略。第一个是“数据先行”的纪律。不管交互多复杂所有状态都要围绕同一份 model 数据来组织不要为了快速实现某个拖拽效果而临时造一个平行数据源。我见过很多人写拖拽直接在 DOM 上改 left/top看起来功能正常但一旦要做缩放、撤销、远程同步所有逻辑都要推翻重写。diagram-design 从第一天起就规定任何交互的结果最终都必须以 model 数据的变更来体现视图只是 model 的投影。第二个是“可持续性”的节奏感。一个图编辑器很容易写着写着就在局部交互里加各种补丁。我的建议是每实现一个完整功能后花时间跑一遍通用操作路径创建、连线、框选、删除、撤销任何一环断了立刻修。要做高复现效率的 bug 报告最好的方式是自己先写一个小型的自动化回归脚本覆盖核心操作后面改代码时直接跑一遍。第三个是“边界条件优先测试”。我踩过的新手坑大多都和数据边界相关空画布时删除节点、一条连线连到自己身上、两个节点完全重叠时框选命中谁、撤销到底之后继续执行任意操作。这些问题在普通路径下不会出现但一旦出现就是很难排查的杂症。建议在开发阶段就给这些边界场景建测试用例越早越好后期加功能时你会感谢当初自己做的这个决定。如果后续要扩展 diagram-design我会优先补两块。一块是节点的样式面板让用户能改填充色、边框、字体而不只是系统默认样式。第二块是导出功能把画布内容无损导出为 SVG 或者图片。这两块都不涉及底层架构改动说明当时的数据模型和交互基座留的扩展余量是够的。也许等这两个功能落地之后我还会再写一篇补充文章把样式系统和导出链路的实现经验也沉淀出来。
