从零构建图编辑器核心：diagram-design的数据结构与Canvas渲染实践

如果你做过前端可视化，或者帮团队搭过内部工具平台，大概率会有这种感受：画一个静态图表不难，难的是做一个“能拖、能连、能缩放、能撤销、能导出”的 diagram-design 系统。这个标题听起来像是一个普通的设计稿命名，但落到工程里，它就是一套完整的图编辑器的核心抽象。我前阵子正好用业余时间把这样一套轻量图表设计系统从头拾了一遍，从数据结构到交互、从渲染到性能踩了个遍，这篇就当作是踩坑总结，把这套 diagram-design 的核心设计思路拆开讲清楚。内容不偏理论，全部是可落地的实操经验，适合正在做图形化编辑器、低代码画布、流程图设计器、拓扑图工具的前端同学参考。

1. 项目定位与整体设计思路拆解

1.1 先搞清楚 diagram-design 到底要做什么

很多团队一开始只是想画一张架构图，于是直接找现成的图表库；做着做着发现产品需要自定义节点样式、自定义连线规则、自定义快捷键，甚至需要多人协作，于是开始思考是不是应该自己维护一套图表设计底层。diagram-design 这个项目定位，就是一个“可嵌入业务系统的图表设计器内核”，它不是给别人用的独立软件，而是提供一整套图形化建模能力的基础模块。

它的核心能力边界大概是这样：

• 支持在画布上创建节点、编辑节点、删除节点
• 支持从锚点拉出连线，连线可吸附到另一个节点的锚点
• 支持画布平移、缩放、框选、多选
• 支持撤销重做、复制粘贴、删除快捷操作
• 支持将当前画布内容导出为图片或 JSON 数据
• 支持主题切换，节点样式随主题变化

这些能力听起来很常规，但每一项拆开都能牵扯出不少复杂度。比如“缩放”不是简单改一下 CSS transform 就完事了，它涉及到坐标系的换算、网格对齐、命中检测的修正、渲染清晰度等多个层面。再比如“连线”，节点拖动之后连线要跟着动，如果节点是圆角矩形，连线起止点还要避开节点的边界，不然线会穿到框里面去。这个项目的前期设计，最不能省的就是花时间梳理能力边界和数据模型。

我在设计的时候，第一步做的不是画 UI 原型，而是画数据模型。因为交互可以后续迭代，数据模型一旦定错，后面所有模块都要返工。

1.2 为什么选择从零构建，而不是直接套用现成方案

遇到 diagram-design 需求，第一反应肯定是找现成的解决方案。市面上的开源流程图工具其实已经很成熟，开箱即用，功能甚至超出预期。但我最后还是选择了自己实现一套核心层，主要原因是定制成本和运行时体积。成熟工具往往是一整套应用，内部有自己的一套数据格式、渲染方式、插件机制，如果只是嵌入到某个页面里用其中一小部分，你得接受它的体积和交互习惯，同时做深度定制也得先啃完它那一层抽象。

自研方案则可以把核心做得非常薄：一个数据模型、一个渲染器、一套交互事件处理。业务方想要什么样的节点外观、按钮排布、辅助面板，都可以直接长在自己的业务代码里，不需要通过某些内部抽象来间接实现。

当然，自研也有代价，就是最基础的渲染、坐标换算、命中检测这些都要自己写。我的建议是，如果业务只需要静态展示图表，千万别自研，直接用现成的图表库，成本最低；但如果你要做的是一个长线产品，需要持续演进交互形式、节点类型、业务语义，那投入自研核心层是值得的。diagram-design 这个项目就属于后者，所以我选择用一套精简的自研内核，把渲染层做得足够扁，交互层通过事件驱动来扩展。

1.3 核心技术选型：Canvas、SVG 还是 WebGL

渲染方案是 diagram-design 最核心的技术选型。我基于这个标题做技术调研时，发现最常见的三种路线是 Canvas 2D、SVG 和 WebGL。

SVG 的特点是 DOM 化，每个节点都是一个真实元素，样式可以用 CSS 控制，事件绑定天然支持，开发体验很好。但它的问题也在这里，节点一旦上千，DOM 数量就会拖垮性能；并且如果要实现复杂的编辑交互，比如框选、拉橡皮筋、临时预览连线，需要在多个 DOM 节点之间做状态同步，状态一多就乱。

Canvas 2D 的特点是一块画布一个上下文，所有图形都在同一个绘制表面完成。它的性能上限比 SVG 高很多，节点数量过千也能保持流畅；交互命中检测虽然要自己写，但只要数据模型清晰，命中检测并不复杂。diagram-design 的核心渲染选型我最终定了 Canvas 2D，原因就是它兼顾了性能与工程复杂度。

WebGL 适合海量节点场景，上万甚至几十万节点，但工程难度明显递增，而且图形编辑器里大量交互是低频的拖拽、选中、框选，不是每帧都需要重绘所有图形，WebGL 的优势并不总能发挥出来。用生活化类比来说：SVG 像是用积木搭模型，拼装直观，但积木太多就堆不下；Canvas 像是直接在一块画布上作画，效率高，但得自己控制画笔的顺序和范围；WebGL 则像是在 GPU 上开了一个巨型画室，画得再快也用不上普通场景。

所以技术选型的核心结论是：如果节点量级在 500 以下，交互频率中等，三种方案随便选；如果目标是做一个具备协作能力、节点量大、交互形式复杂的长线产品，Canvas 2D 是性价比最高的起点。

还有一个细节需要注意：不要一开始就想着“解决所有场景”，比如既要富文本节点又要海量节点又要流程图自动布局。一个 diagram-design 内核只解决“把图数据结构变成可交互画布”这件事，其他增值能力全部通过插件或上层模块扩展。

2. 核心数据结构设计：一切交互的地基

2.1 节点、连线和画布的抽象模型

diagram-design 的底层数据结构，本质上是一个图模型。图模型里的两个核心要素就是节点（Node）和连线（Edge），这也是大部分图表设计系统的通用抽象。

我在设计数据模型时，节点对象至少包含这些字段：

• id：全局唯一标识
• type：节点类型，因为不同类型可能对应不同的渲染样式
• x、y：节点在画布坐标系中的位置
• width、height：节点尺寸
• data：业务自定义数据，比如文本内容、图标名称、状态色等

节点位置我统一使用画布逻辑坐标，而不是屏幕坐标。这个区分很多人会忽略。所谓画布逻辑坐标，就是不管当前画布被放大还是缩小，节点存的位置都是它在一个无限大的二维平面里的真实位置；屏幕坐标只是通过“视野中心点 + 缩放值”换算出来的临时结果。这样设计的好处是缩放、平移不会污染数据，导出数据时也不会因为视图状态不一致导致错位。

连线对象需要保存的是：

• id：唯一标识
• sourceNodeId、targetNodeId：起止节点
• sourceAnchor、targetAnchor：起止锚点的索引或名称
• points：如果有折线或自定义路径，需要额外记录途经点
• data：业务数据

很多图表设计系统的连线坑都出在“锚点”抽象上。一个节点可能有多个锚点，比如矩形节点的上下左右中点，连线不仅要知道从哪个节点出发，还要知道从该节点的哪个锚点出发。如果没有锚点概念，连线只能默认连到中心点，画出来的图会很丑，用户手动调线也会很不方便。

画布对象则可以看作一个最外层容器，包含的字段有：

• nodes：所有节点
• edges：所有连线
• viewport：当前视野对象，包含 centerX、centerY、scale
• version：数据版本号，用于导入兼容和增量同步

这个画布模型是整个 diagram-design 的状态中心，所有操作最终都是对这个画布对象做修改，然后触发渲染层更新。

2.2 状态管理与撤销重做机制

撤销重做是图表设计系统的“隐形刚需”，没有它的编辑器几乎不可用。我在做 diagram-design 的撤销机制时，最开始尝试的是“快照全量备份”，每次操作后把整个画布数据深拷贝一份，撤销就直接回退到上一个快照。但实践证明，节点量一大，比如 500 个节点加 800 条连线，深拷贝一次的成本很高，操作多了内存占用也很吓人。

后来我换成了“操作命令栈”模式。每个用户行为都被封装成一个命令对象，命令对象里保存了执行这个操作所需的上下文，比如节点原来的位置、连线原来的终点锚点、新增节点的完整数据。执行操作时推入 undo 栈，撤销时从 undo 栈弹出并执行反操作；同时把反向操作推入 redo 栈。

这种做法的好处是，撤销重做不需要复制整份数据，只记录操作前后的关键差异，内存开销小，性能也能稳定在毫秒级。它还顺带带来一个额外能力：命令对象可以记录业务信息，比如操作人、操作时间，后面如果要接审计日志或者协作同步，底子已经打好了。

当然，命令模式也有复杂的场景需要处理：比如拖拽节点的时候，pointermove 可能触发几十次位置更新，不能每次移动都生成一条命令。我的经验是在 pointerdown 时记录操作起始快照，pointerup 时统一生成一条“移动节点”命令，命令里包含移动前后位置数组。这样才能保证用户一次拖拽只占一个撤销步。

2.3 数据序列化与格式兼容

diagram-design 的数据最终要能够导出、导入、持久化，所以序列化格式的稳定性至关重要。我采用的方案是顶层一个 schemaVersion 字段，后续每次数据结构变更都升级这个版本号，并且在导入时做版本判断。不同版本之间写一层适配器做数据迁移，而不是让旧数据直接崩溃。

序列化时要注意几个坑：第一，不要直接序列化 DOM 引用或渲染上下文，只序列化纯数据对象；第二，所有涉及坐标的字段统一以画布逻辑坐标为准，不要把屏幕坐标混进去；第三，时间为非必须字段，但如果要支持协同，建议增加 updatedAt 字段，用于冲突判断。

我提到的 JSON 格式大致是这样的层次：根对象包含 version、viewport、nodes 数组、edges 数组、业务字段。这套结构简单、可扩展，而且面对未来的多人协作需求，也能比较容易地接入增量同步协议。

3. 画布编辑器交互实现：从拖拽到连线

3.1 拖拽节点与位置更新流程

diagram-design 里最基本的交互是拖拽节点。这个功能看似简单，但实现细节里面藏着不少坑。

我采用的事件绑定方式是：在画布最外层容器上监听 pointerdown、pointermove、pointerup，而不是在每个节点元素上单独绑定事件。这是典型的“事件委托”策略。因为 Canvas 渲染出来的节点本来就不是实体 DOM，每个节点都要单独绑事件也不可能。事件委托的好处还有一点：不管后续新增多少节点类型，都不用重复绑定事件，只需要让不同节点类型在“命中检测”阶段返回正确结果即可。

拖拽的完整流程是：

• pointerdown：通过命中检测找到当前点击的节点，记录节点初始位置，记录当前鼠标在画布坐标系里的坐标
• pointermove：实时计算鼠标位置偏移，把这个偏移加到节点初始位置上，更新数据模型，请求重绘
• pointerup：回收事件，生成一条移动命令压入撤销栈

坐标换算这个环节最容易出错。画布上监听到的鼠标坐标是浏览器屏幕坐标，而节点位置是画布逻辑坐标。如果当前画布发生了缩放和平移，直接拿屏幕偏移去改节点坐标就会导致拖拽速度跟缩放比例不匹配。正确做法是维护一个坐标变换函数：屏幕坐标先减去视野偏移，再除以缩放比例，得到画布坐标。每次操作都统一走这个函数，不要在业务代码里临时手算。

我在这个模块里踩过最深的一个坑是连续拖拽时累加误差。第一次拖拽结束后，下一轮 pointerdown 时要用最新状态重新记录初始位置，但这时候如果初始位置获取逻辑写错了，比如读取的是上一次最终屏幕坐标，节点就会越拖越偏。解决方法是：任何一次拖拽开始时，强制从数据模型重新读取节点当前坐标，绝不沿用上一次移动的中间状态。

3.2 连线创建与锚点吸附机制

连线交互是 diagram-design 最能体现“编辑器手感”的部分。如果只是拖一条线出来，谁都能做；但要做到“线跟着鼠标走、靠近目标锚点自动吸附、松手后落点精确”，就需要一套完整的锚点体系。

连线创建流程我分为三个阶段：

• 阶段一：从某个节点的锚点按住鼠标开始拖，此时创建一条临时连线，起点固定在该锚点的坐标，终点跟随鼠标位置
• 阶段二：临时连线持续重绘，同时实时检测鼠标当前位置附近有没有其他节点的锚点，如果有且距离小于阈值，就把终点吸附到那个锚点上，并高亮目标锚点
• 阶段三：鼠标松开，如果终点有效命中了一个目标锚点，则正式创建连线记录；如果终点没有命中任何锚点，则取消连线操作

关于吸附阈值，我需要特别提一下。阈值不宜固定为一个屏幕像素值，因为画布缩放后，同样的屏幕距离在画布逻辑坐标里大小不同。建议将阈值定义为一个逻辑单位，比如 16 个逻辑像素，在检测时乘以当前缩放系数换算成屏幕距离。这样用户在放大画布时依旧能比较容易地把线连到锚点，缩小画布时也不会出现“隔很远就吸附”的怪异体验。

临时连线绘制的时候还有一个视觉细节：线的端点不能直接画在鼠标位置，而要画在一个和锚点对应的位置。因为目标是“从这里拉出一条线到那里”，所以起点要画在源锚点的中心，终点要画在鼠标位置，这样用户能清楚感知连线从哪个点出发、正在通向哪里。

连线路径我用的是贝塞尔曲线，控制点根据起止锚点的方向算出来。比如起点在节点右侧、终点在左侧，那么控制点就分别在起点的右边方向和终点的左边方向延伸一段距离。这样出来的曲线有方向感，看起来更自然。

3.3 框选、多选与快捷键联动

框选是图表编辑器里非常常用的一个操作，也是对命中检测的补充。它要解决的核心问题是：如何快速判断哪些节点落在了用户画出的矩形范围内。

我的实现步骤是：

• 用户按住空白区域开始拖拽，记录起始画布坐标
• 拖拽过程中动态更新矩形范围，画出一个半透明的选框图形
• 每次选框变化时，遍历所有节点，判断节点矩形是否与选框矩形相交
• 将被选中的节点标记为选中状态，触发重绘

判断节点矩形与选框矩形相交的逻辑很简单，就是两个矩形的边界比较。但这里有性能隐患：如果每次 pointermove 都遍历几千个节点做相交判断，会有明显卡顿。所以我在项目里加了这个优化：节点数据在内存中维护一份空间索引，或者简单地说，把节点按 x 坐标和 y 坐标分别排序，框选时先用二分查找缩小候选集，然后再做精确相交判断。如果节点量在 500 以下，其实直接遍历也问题不大，但我仍然建议排序，因为后面扩展协作和大数据量时不用重写。

多选状态要联动快捷键：方向键微移、Delete 删除、Ctrl+C 复制、Ctrl+V 粘贴。复制粘贴的时候有一个最容易犯的错：节点 id 必须重新生成，连线的 sourceNodeId 和 targetNodeId 也要映射到新节点的新 id。如果不做 id 映射，粘贴出来的节点和连线可能还指向旧的节点，数据一进入严格模式就报错。我一开始就吃过这个亏，后来写了一个 cloneSelection 方法，专门处理“选中节点集 + 与之相关的连线集”的复制，并维护新旧 id 映射表。

4. 渲染层设计与视觉打磨

4.1 渲染更新策略：局部重绘与全量重绘

diagram-design 的渲染是一个需要认真设计性能的模块。我用 Canvas 绘制时，最容易犯的错误是每次交互都整画布清空重绘，比如拖动一个节点，就把全部节点和连线都重画一遍。如果节点只有几十个，完全没问题；节点上千之后，全量重绘的耗时就会影响交互帧率。

我最后采用的策略是分场景决策：

• 单节点拖动、临时连线绘制、锚点高亮这种高频场景，采用局部重绘，只清空并重绘变化区域
• 画布缩放、平移这种整体视图变化场景，采用全量重绘，因为此时视口内几乎所有图形位置都变了
• 节点数量不多且硬件条件一般的环境，直接全量重绘反而更简单，不需要维护复杂脏矩形

局部重绘中最关键的概念是“脏矩形”。每次交互时，计算出发生变化的最小矩形区域，用 canvas 的 clearRect 清空这块区域，然后把和这个区域相关的节点和连线重新绘制一遍。听起来简单，但实际维护脏矩形集合会有不少边界情况：比如一条连线很长，横跨了整个画布，那么任何一处变化都可能让这条连线需要重绘。

针对这个问题，我做了妥协：对于连线这样的长跨度图形，脏矩形检测时把线条的边界框纳入考量，只要线条的边界框和脏矩形相交，就重绘这条线。因为线条重绘本身成本不高，但如果不重绘，画面上会留下残影，体验更差。

4.2 节点样式绘制与连线路径计算

节点样式的美观度直接影响 diagram-design 给人的专业感。我实现的节点渲染抽象是“按类型分发绘制函数”，每种节点类型对应一个 drawNode 方法，方法内部通过 Canvas 上下文绘制背景、边框、图标、文本。这样的抽象让新增节点类型变得非常容易，而且不同类型的节点可以有完全不同的绘制逻辑。

绘制圆角矩形是我写得最多的基础方法。Canvas 自带 roundRect 方法，但现代浏览器兼容性虽然已经够了，如果是旧环境你仍然需要手动绘制。手动绘制也不复杂，思路是用 arcTo 在四个角生成圆弧，然后闭合路径。

连线路径的计算我走了从简到繁的过程。最开始只是简单地计算两个节点中心点之间的贝塞尔曲线，后来发现线头和线尾会被节点矩形盖住，视觉上很别扭。于是改成“从源锚点连到目标锚点”，但锚点坐标是节点边界上的点，所以不会有遮挡问题。如果锚点位于节点中心，需要把终点坐标向外偏移到节点边界交点，算法上就是“从节点中心沿着锚点方向做射线，与节点边界求交点”。

连线样式的设计上，我建议支持基础线型（实线、虚线、点线）和多档线宽。如果要做选中态高亮，可以让选中的连线和普通连线的颜色、线宽区分开，同时稍微加粗。这些视觉反馈对交互操作很重要，否则用户分不清当前选中的是哪一条线。

4.3 网格系统与主题定制

网格是图表编辑器视觉系统里不可忽视的一环。diagram-design 里的网格不是为了好看，而是给用户提供“对齐感知”。用户拖动节点时，网格能让节点移动感更平滑，更方便对齐其他节点。

我实现的网格分为两层：主网格和次网格。次网格间距小，颜色浅；主网格间距大，颜色稍深。当画布缩放级数改变时，网格间距要做自适应。比如初始逻辑网格间距是 20，当缩放比例变大到一屏只能看到少量节点时，如果还按 20 像素去绘制网格，网格会密得像一张灰布；此时应该按比例把网格间距跳级到 50 或 100。这个逻辑和地图缩放时不同级别显示不同路网密度的思路类似。

主题定制方面，我的做法是维护一个 theme 对象，包含背景色、网格线颜色、节点默认填充色、节点边框色、文本颜色、连线颜色、选中态颜色等。所有绘制函数都只从 theme 对象取颜色，不直接写死颜色值。这样用户切换到暗色主题时，只需要替换一个 theme 对象，所有图形都会跟着变化，不需要修改绘制逻辑。

还有一个小细节：暗色主题下网格线颜色要比亮色主题更微弱，否则暗色背景上的网格线会过度刺眼。同时节点阴影的透明度也要调低，因为暗色背景对阴影的感知能力更敏感。

5. 性能优化与工程化实践

5.1 大数据量节点下的渲染优化

当 diagram-design 里的节点数量上升到几百上千时，渲染性能就会开始成为核心矛盾。我在压测阶段导入过一个包含 800 个节点、1200 条连线的初始化数据，直观感受是：不做优化时拖拽明显掉帧，重绘一次要几十毫秒；优化之后能稳定在 60 帧附近。

第一层优化是视口剔除。画布是无限大的，但用户能看到的区域只是视口那一块。渲染时遍历所有节点，只绘制那些与当前视口矩形相交的节点；连线也做同样的剔除，线条边界框和视口不相交就直接跳过。这样无论是 800 个节点还是 2000 个节点，每帧实际绘制的数量只和视口内的节点数相关。

第二层优化是减少上下文状态切换。Canvas 的性能杀手之一是 fillStyle、strokeStyle、lineWidth 这些状态被频繁切换。同一个颜色属性的图形尽量连续绘制，比如先绘制所有普通节点，再绘制所有选中节点，最后绘制所有连线。这比“画一个节点、画一条线、再画一个节点”这种穿插顺序快得多。我在绘制循环里把所有图元先按类型和状态分组，再逐组绘制。

第三层优化是离屏 Canvas 缓存。对于完全不常变的静态背景，比如网格、水印、底图，可以先绘制到一个离屏 Canvas，主画布绘制时用 drawImage 直接把离屏内容贴上去。这样就不用每帧重新计算和绘制网格线条。这个优化对网格这种高频重绘元素效果尤其明显。

5.2 高 DPI 适配与缩放坐标精度问题

diagram-design 在 Retina 屏幕上会遇到一个经典问题：画布模糊。原因是 Canvas 的 CSS 尺寸和物理像素尺寸不一致。解决办法是通过 devicePixelRatio 缩放 Canvas 的实际宽高，同时设置 ctx.scale(dpr, dpr)，保证绘制时所有的坐标仍然是逻辑像素。

我在项目里封装了一个 resize 方法，在画布容器尺寸变化或 dpr 变化时重新设置 Canvas 的 width、height 和 style.width、style.height，然后调用 ctx.scale(dpr, dpr)。这样文本、线条在 Retina 屏上会清晰很多。

缩放坐标精度也是一个容易出问题的点。用户把画布放大到 200% 后移动节点，鼠标位移 1 个像素，对应逻辑坐标位移是 0.5 个逻辑单位。如果直接使用浮点数存储节点坐标，时间久了可能会出现小数点后很多位的情况，JSON 导出时数据会变得不干净。我的处理是在每次修改坐标时做四舍五入或按网格吸附：如果开启了网格对齐，坐标强制吸附到网格整数倍；如果没有开启，保留一位小数即可。这样数据干净、可读性好，也不会出现因为浮点误差导致的图形轻微抖动。

5.3 模块化构建与插件化扩展

diagram-design 不只是一个单一页面项目，它是可以被多个业务复用的内核模块。所以我把代码按能力拆成几个层次：

• core：数据模型、坐标变换、序列化
• render：Canvas 渲染器、节点绘制、连线绘制
• interaction：拖拽、连线、框选等交互控制器
• plugins：额外扩展能力，比如小地图、对齐辅助线、导出图片

这样的分层也带来了一个好处：渲染器和交互层彼此解耦。未来如果想从 Canvas 切换到 WebGL，只要 render 层提供同样的接口，上层交互不需要改动。虽然我目前没有计划迁移，但架构上保留了这个可能性，让后续技术演进不必重构全部代码。

导出图片功能也算在工程化能力里。纯前端导出 Canvas 内容到 PNG 很简单，直接调用 canvas.toDataURL。但有一个细节：如果画布内容超出当前视口，导出时要创建一个离屏 Canvas，设置它的大小为整个图数据的内容边界，然后把所有节点和连线重新绘制到这个离屏 Canvas 上再导出。否则导出的图片只有当前视口那一小块，不符合用户预期。

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

6.1 坐标错位与拖拽不跟手

这是我在 diagram-design 开发中遇到最多的问题。现象是拖动节点时节点跟不上鼠标，或者越拖越偏。最常见的原因就是没有正确区分屏幕坐标和画布逻辑坐标。

我提供一套排查方法：在 pointermove 里加日志，同时打印鼠标屏幕坐标和经过坐标变换后的画布坐标，然后手动移动画布到一个位置，重新拖拽，观察两次日志的逻辑坐标是否和预期一致。如果逻辑坐标随画布平移而变化，说明坐标变换函数里忘了减去视野中心偏移；如果缩放后拖拽距离和鼠标距离不一致，说明没有除以缩放系数。

6.2 缩放时图形模糊

图形模糊通常有两个原因。一个是高 DPI 没有适配，Canvas 的实际像素和 CSS 像素不一致；另一个是缩放时直接用 ctx.scale 在浮点数状态下反复绘制，导致边缘锯齿被放大。适配高 DPI 是必修课；此外，缩放级别比较大的时候，可以考虑在绘制文字时使用整数坐标，因为文本在非整数坐标下更容易渲染模糊。我的方式是绘制文本前先对坐标做 round 处理，实测下来清晰度提升明显。

6.3 连线命中困难

用户想选中一条连线时，经常发现很难点到。这是因为连线本身很细，直线只有 2 像素宽，鼠标稍微偏离就不可见。我的做法是：在命中检测时，对线段做“加宽命中”，也就是把线段的命中阈值扩大到 8 到 10 个像素的逻辑距离。检测算法是用鼠标点到线段的最短距离，如果小于阈值就算命中。

如果图形里包含贝塞尔曲线，命中检测不能直接用直线距离，需要把曲线按步长采样成多个点，然后计算鼠标到采样点线段的最短距离。步长取 8 到 12 个像素比较合适，太长不准，太短性能开销大。建议只在鼠标按下时做一次全量曲线的命中检测，不要在 mouse move 时反复计算。

6.4 内存泄漏问题

图表编辑器是长时间驻留页面的模块，内存泄漏会见鬼般得顽固。我遇到过两个泄漏来源：

第一个是全局事件监听未移除。因为交互采用事件委托，监听了 window 的 pointermove 和 pointerup，组件销毁时如果只移除了画布容器上的 pointerdown，没有移除 window 上的两个监听，页面每次创建和销毁编辑器都会多一个幽灵监听。解决方式是提供一个 destroy 方法，统一移除所有事件监听、取消动画帧、释放离屏 Canvas。

第二个是撤销栈不断增长。如果一次拖拽生成一条命令，但命令内部的节点坐标数组保存了大量中间态数据，内存会增长得很快。我后来限制了 undo 栈的深度，例如最多保留 100 步，超过后丢弃最早的操作。这个限制对用户体验影响很小，但能让内存保持在一个稳定的水位。

6.5 常见问题速查表

以上这些问题，基本都是把代码写到一个阶段后必然遇到的。踩一次坑，记录下来，后续就能快速定位。

7. 最后的实操心得分享

我个人在实际开发 diagram-design 这类系统时，最大的体会是：核心工作不是写画面，而是维护一套自洽的“数据 + 坐标 + 事件”心智模型。只要这个模型想清楚了，代码就是按部就班地填。

最后再分享一个小技巧。调试画布缩放平移和坐标变换时，一定要在画布左上角打一个调试信息面板，实时显示当前鼠标的屏幕坐标、画布逻辑坐标和当前缩放比例。这个信息面板能让你在一分钟之内定位大部分坐标类问题，比加日志循环验证要高效得多。我在整个开发期一直保留着这个面板，直到交互稳定后才把它收起，只留一个快捷键控制开关。

还有一个容易被忽略的体验细节：所有交互都应该有视觉反馈。鼠标悬停在节点上时，节点边框变亮；拖动节点时，节点加阴影；连线吸附成功时，锚点高亮。这些反馈看似简单，却能极大提升编辑器的专业感和用户信任度。做 diagram-design 这类工具，功能完整很重要，但“手感”才是决定用户爱不爱用的关键。