企业官网建设流程全解析

写这个diagram-design项目的时候，我其实是带着这几年画架构图、流程图、ER 图积攒下来的一肚子"怨气"开始的。市面上不是没有工具，Visio、draw.io、Excalidraw 都各有拥趸，但真放到团队协作或嵌入到自有产品里，要么太重，要么太飘逸，要么就是私有的数据格式，想二次开发几乎是跟别人的代码搏斗。所以这个项目从一开始就没打算做成一个"大而全"的在线绘图软件，而是想打磨一个核心足够稳、扩展足够容易的图表设计基础引擎——说白了，就是给那些想在 Web 端拖拽画图、但又不想从零写 canvas 交互的团队，提供一个可以"抄作业"的参考实现。

这篇文章想把整个项目的来龙去脉、技术选型、核心实现和踩坑记录都摊开讲清楚。内容会比较长，适合三类人看：一是准备在项目里集成绘图功能的同学，可以拿这里面的架构思路当参照；二是对 Canvas 交互、图编辑这类技术有好奇心的前端开发者，里面有不少坐标系换算、性能优化、连线路由的细节；三是自己正在做类似工具，想找一份"避坑清单"的朋友——我把自己掉进去过的坑都尽量写得直白一点。文章不会讲太多空泛的"设计思想"，更多是实打实的代码路径和决策过程。

1. 项目定位：它到底解决什么问题

1.1 市面工具的共性短板

先说结论：通用工具软件和嵌入式绘图组件之间，存在一条很深的鸿沟。

像 draw.io 这种成熟工具，功能确实全面，但它是个完整的应用，不是组件。你要把它嵌入到自己的 SaaS 系统里，要么走 iframe 方案，要么就得在它的源码基础上二次开发。iframe 方案天真地隔离了样式和脚本，但一旦涉及数据互通（比如点击图形回传业务数据、从后台动态加载节点），交互就会变得非常别扭，而且在多文档协同编辑场景下，iframe 的通信成本会直接让你怀疑人生。

Excalidraw 是另一个极端。它的手绘风格确实有魅力，也容易让人上头，但它对于"技术性图示"的支持，比如精确的尺寸对齐、严格的端口连接、复杂的正交布线、灵活的样式定制，就不够用了。手绘风和工程图本来就是两个方向。

还有一个痛点是企业里常见的：数据结构和渲染解耦不力。很多工具的图数据模型绑定了 UI 细节，节点坐标、颜色、尺寸、层级关系全堆在一起，导致迁移数据难、用脚本批量生成图难、做数据驱动场景几乎不可能。而实际业务里，用 JSON 生成一张拓扑图或者流程图，是很常见的需求。

1.2 diagram-design 的差异化路线

当时给这个项目定的基调就三条：

第一，数据优先。画布上的所有元素（节点、连线、锚点、分组）都映射到一个干净的 JSON 数据模型上，这个模型不依赖任何 UI 框架，也不包含任何 Canvas 渲染状态。这样设计带来的直接好处是：你可以从后端接口拿数据直接渲染出图；可以做程序化生成；可以接入任意状态管理库；以后如果要换渲染方案，数据层完全不用动。

第二，交互可定制。拖拽、框选、缩放这些基础交互行为是内置的，但每一步都留了事件钩子。比如说，节点拖拽结束的时候触发onNodeDrop，连线创建过程可以拦截并校验连接合法性——这些钩子才是把一个绘图组件变成业务产品的关键。

第三，性能有底线。不求支持上万节点同时编辑（那是图可视化库的领地），但在几千节点、数万条连线的规模下，交互必须保持流畅，不能出现明显卡顿。为此，渲染层选择了 Canvas 而不是 SVG，后面会详细讲原因。

1.3 适合谁用、不适合谁用

我把这个项目定位成"可嵌入的图表设计核心"，不是"又一个绘图工具"。它适合你用在自己的产品里，比如工单流程设计器、网络拓扑编辑器、数据血缘关系图、低代码平台的表单布局器，这些场景需要的是"可拖拽的画布 + 图纸数据"。

但它不适合的场景也很明确：如果你需要的是在线白板那种像素级的自由笔迹、多人实时光标、语音批注，那就该去看专门的协作白板方案。如果你只是想画一张图然后导出图片发给别人，直接用现成软件就完了，不需要自己写代码。

2. 技术选型与整体架构

2.1 渲染方案：为什么最终选了 Canvas

这是最先要敲定的决策，直接决定后面所有代码的写法。当时做了几组简单测试，对比 Canvas、SVG 和 DOM 三种方案在图形渲染和交互上的表现，结论如下。

DOM 方案在节点数少、样式复杂的情况下很舒服，因为整个前端生态的开发效率就摆在那里。但它撑不了规模：一千个节点就是一千多个 DOM 元素，再加上连线元素，浏览器直接喘不过气。还有缩放问题，整体用 CSS 缩放下文字和边框会一起变形，这在架构图场景里经常是不能接受的。

SVG 是很多人会推荐的选择，因为它既保留了矢量放大不失真的特性，又能用 DOM API 绑定事件，开发心智负担低。但 SVG 在节点密集场景有一个绕不过去的瓶颈：每个图形都是 DOM 节点。节点一多，创建、销毁、属性更新的开销会线性增长，尤其是在拖拽过程中所有相邻连线都要更新路径时，浏览器同步布局会卡到你怀疑人生。

Canvas 的优缺点非常鲜明。优点就是渲染性能：它是自绘的，图形数量多、更新频繁对它来说就是"重绘一整帧"，不存在单个元素的操作开销，而且可以很方便地配合 requestAnimationFrame 做局部重绘，把性能潜力压榨得很充分。缺点也明显：所有元素的点击命中都得自己算，拖拽过程中要自己维护坐标系，文字排版、事件边界、光标样式都要一层层写。说白了，Canvas 给了你更大的自由，但自由是有代价的。

权衡之下，我还是选择了 Canvas。核心原因在于：图表设计工具的瓶颈永远在交互时的帧率，而不是首次渲染。拖拽一个节点时，它周围的连线可能需要实时重新计算路径，SVG 在不断修改 path 属性时容易触发布局抖动，而 Canvas 只需要重绘一个图层，帧率稳定得多。后来我们又把整个场景拆分成了四个画布层（连线层、节点层、临时交互层、背景网格层），这样在不同操作场景下只需重绘对应层，性能进一步提升。

2.2 模块划分：别再只想着"画布"这个类

项目形态是一颗前端的规模不大不小的库，模块划分做得太粗会乱，太细了会碎。最终按照以下结构进行组织：

src/ core/ // 数据模型、事件总线、命令栈 canvas/ // 画布引擎：分层渲染、坐标变换、调度 render/ // 各图形类型的绘制函数（纯函数） interact/ // 拖拽、框选、缩放、连线等交互逻辑 style/ // 样式解析与主题系统 utils/ // 几何计算、路径计算、通用工具 index.ts // 对外入口

core层不依赖任何 DOM 或 Canvas 代码，它是纯数据层，用来管理图和所有历史记录。canvas层负责将数据翻译成画面，并处理所有输入事件的坐标系换算。render层其实只是一堆绘图函数：你给我节点对象和 Canvas 上下文，我给你画出来。interact层是核心业务逻辑，处理各种用户操作对数据模型的影响。

这个拆分最关键的地方在于，把"数据"和"画面"之间的依赖做了严格的方向约束：数据层不知道有渲染层存在，渲染层通过订阅数据变化来驱动重绘。这意味着你可以写单测直接测数据模型和交互逻辑，而不需要打开浏览器。

2.3 数据模型：一张图的骨架

数据结构的设计决定了扩展性的上限。我参考了图编辑器的通用做法，定义了三类核心元素：Node（节点）、Edge（连线）、Group（分组），所有元素共享一个BaseEntity基类，包含 id、type、坐标、尺寸、样式引用等基础属性。

节点是图的最小单元，它不仅是矩形，还可能是圆形、菱形、图片、自定义组件。所以在设计上，所有节点的数据都收敛到通用的NodeData结构：

interface NodeData { id: string; geometry: { x: number; y: number; width: number; height: number; }; type: string; // 节点类型，对应渲染层的一个绘制函数 attrs: Record<string, unknown>; // 业务属性，由具体节点类型解释 style?: NodeStyle; ports?: Port[]; // 连接锚点 data?: Record<string, unknown>; // 用户自定义数据，原样保留 }

attrs和data的区别很有讲究：attrs是几何层需要理解的属性（如圆形的半径、菱形的角点比例），而data是业务层需要理解的属性（如设备名称、IP 地址），两者严格分离。

连线结构稍微复杂一点，因为它不仅要记录从哪个节点到哪个节点，还要记录路径本身。

interface EdgeData { id: string; // 连接两端：既可以是节点端口，也可以是绝对坐标锚点 source: { nodeId?: string; portId?: string; x?: number; y?: number }; target: { nodeId?: string; portId?: string; x?: number; y?: number }; type: 'straight' | 'orthogonal' | 'bezier'; routing?: Point[]; // 手动加点，用于绕障或强制走线 attrs?: Record<string, unknown>; style?: EdgeStyle; }

图本身则是一个GraphData对象，包含节点数组、连线数组、分组数组和视口信息。这里有一个值得注意的小设计：把视口信息（缩放比、平移距离、当前选中项）也扔在了数据对象里，而不是存在 Canvas 引擎的模块级变量中。这样做的好处是状态可序列化——把整个图保存到后端时，连视图状态也一并存下来，下次打开还能恢复到用户上次的浏览位置，体验非常顺滑。

3. 核心功能实现与实操细节

3.1 坐标系的秘密：屏幕坐标 vs 世界坐标

这是所有画布类应用的第一个大坑，几乎每个新来的同学都会在这栽一次跟头，我得把它讲透。

当你在 Canvas 里画一个节点，你通常会调用ctx.fillRect(x, y, width, height)，这个 x 和 y 是 Canvas 的坐标空间。当用户拖动鼠标时，事件回调里的clientX和clientY是浏览器窗口坐标。如果把这两个坐标混在一起用，映射关系就会错乱：一旦 Canvas 元素在页面中发生了滚动、或者画布做了缩放平移，你的拖拽逻辑就崩了。

正确的姿势是维护两个坐标系，并建立明确的转换关系：

屏幕坐标（Viewport 坐标）：Canvas 元素左上角为原点，单位是 CSS 像素，也就是鼠标事件拿到的坐标经过getBoundingClientRect()校正后的结果。

世界坐标（Model 坐标）：图纸的坐标空间，节点数据里的 x、y 都存放在这个空间。这个坐标不受缩放和平移影响，是稳定的表意坐标。

两者的转换关系很简单：

export function screenToWorld(screenPt: Point, viewport: Viewport): Point { return { x: (screenPt.x - viewport.x) / viewport.zoom, y: (screenPt.y - viewport.y) / viewport.zoom, }; } export function worldToScreen(worldPt: Point, viewport: Viewport): Point { return { x: worldPt.x * viewport.zoom + viewport.x, y: worldPt.y * viewport.zoom + viewport.y, }; }

这里的viewport.x和viewport.y表示世界坐标原点对应在 Canvas 像素坐标上的位置。缩放时，我们只需要更新viewport.zoom，平移时更新viewport.x/y，所有节点在世界坐标里一动不动，变的只是渲染时的转换参数。

实际操作中，每次收到鼠标事件，第一时间把屏幕坐标转成世界坐标，再对数据模型进行操作。等操作结束后渲染层会用当前视口把整个场景画出来。这个流程是单向的：事件 -> 世界坐标 -> 操作数据 -> 重绘。中间不经过屏幕坐标，能避免大量隐形 bug。

3.2 图形的拖拽、框选与对齐吸附逻辑

拖拽是图表编辑器最基本的交互，但我想说的是它的实现方式。如果你直接监听mousemove，然后在回调里修改节点坐标，会遇到两个问题：一是事件太频繁会导致抖动；二是偏移量的计算容易写错，尤其是缩放比例不为 1 时。

我的做法是按下鼠标时记录"起始点"（世界坐标）和所有被拖动节点的初始位置，然后在移动时计算总位移，再给所有拖拽节点设置新坐标。注意，是所有被拖拽的节点共享同一个位移量，这样它们的相对位置就不会变。

@interact('node:drag') function onNodeDragStart(e: DragStartEvent) { const { nodeId, screenPos } = e; const worldPos = screenToWorld(screenPos, viewport); dragState = { startWorld: worldPos, nodes: selectedNodeIds.map(id => ({ id, origX: nodeMap.get(id).geometry.x, origY: nodeMap.get(id).geometry.y, })), }; } @interact('node:drag') function onNodeDragMove(e: DragMoveEvent) { const worldPos = screenToWorld(e.screenPos, viewport); const dx = worldPos.x - dragState.startWorld.x; const dy = worldPos.y - dragState.startWorld.y; // 对每个拖拽节点设置新坐标 for (const item of dragState.nodes) { updateNodePosition(item.id, item.origX + dx, item.origY + dy); } computeMagneticGuide(); // 计算磁吸对齐参考线 requestRender(); }

这里有个容易被忽略的细节：requestRender()并不是立刻重绘，而是把重绘任务合并到requestAnimationFrame里。这样一秒钟最多画 60 次，而不是鼠标移动多少次就画多少次，性能是完全不同的量级。

框选是另一个高频交互。实现思路是记录鼠标按下的起始世界坐标和当前世界坐标，实时绘制一个半透明矩形，同时每一帧检查所有节点与这个矩形是否相交。节点是否被选中，不是靠 Canvas 的像素级检测，而是直接做 AABB（轴对齐包围盒）相交测试，这非常简单高效。多选时用 Shift 可以切换选中状态，也算标配了。

对齐吸附这个功能，一开始我以为是加分项，后来发现它是刚需。画架构图时，如果节点之间总是差那么几个像素对不齐，视觉上会非常难受。实现方法不复杂：在拖拽过程中实时计算其他节点和当前节点的"关键边缘"（左/右/中/上/下/中），找出距离小于某个阈值（比如 5px）的边，然后在渲染层绘制一条参考线，并把拖拽位置自动吸附到对齐位置。

这个功能的关键在于效率。每个节点有 6 条关键边（水平和垂直各 3 条），n 个节点就是 n×6 条边，互相比较是 O(n²) 的复杂度。当画面里有几百个节点时，这个计算量会拖慢拖拽帧率。我最后用了一个简单的优化：只对当前视口内的可见节点进行计算，而且只在拖拽的节流帧里执行，不阻塞主流程。对于一般场景，这个复杂度完全可以接受。

3.3 连线路由：从"直线"到"正交避障"的进化

连线是图表编辑器的另一个硬骨头。一开始只做了直线连线和贝塞尔曲线，但这在流程图里够用，在架构图里就露怯了——尤其是网络拓扑图、系统架构图这类场景，用户几乎默认需要的是横平竖直的正交连线。

正交连线的路径计算，业界最常用的是曼哈顿路由算法。基本思路是：从起点出发先沿水平还是垂直方向，中间经过若干转折点，最后到达目标节点。如果起点和终点之间没有障碍物，可以简单计算出一条"先出起点、再入终点"的折线。

伪代码思路：

1. 确定起点端口方向（例如右侧）和终点端口方向（例如左侧） 2. 计算起点端口坐标 startPt 和终点端口坐标 endPt 3. 初步路径：从 startPt 按出口方向延伸一段（如 20px）， 再从该点画水平/垂直线到 endPt 的延伸点，再进入 endPt 4. 如果该路径与障碍物（其他节点）相交，则寻找可绕行的中间点

我这里实现的是简化版，没有做完整的 A* 寻路（完整版对 JS 来说性能太吃紧了），而是基于"优先走中点绕障"的启发式。效果是：90% 的情况都能给出合理的连线路径，剩下少见的情况可以允许用户手动拖动连线中点来增加自定义路由点。

在 Canvas 上平滑绘制正交连线还有一个细节：不要填满直角。现代 UI 的审美倾向于在转角处加一个小圆角，视觉上柔和很多。实现方式是遍历路径点，在两个方向改变的位置插入一个二次贝塞尔曲线，弧度设置为 4~5px。

连线的命中检测也很有意思。因为 Canvas 没有"这条 path 是否被点击"的 API，你只能自己做。我的方案是连接线的路径被拆解为多个线段，然后用"点在线段上"的距离检测来判断。当鼠标光标距离任意线段小于一定阈值时，就认为命中。为了防止用户"看不见瞄不准"，我还给每条连线设置了一个 8px 的"命中加宽"，相当于把检测区域扩充到 8px 宽。这在体验上带来的提升非常明显。

3.4 节点的端口与连接规则

端口（Port）是表示连线端点在图元上的位置。常见的方案有静态端口（4 个固定方向点）和动态端口（跟随图元边缘自动定位）。我做了两种都支持：静态端口适合那些有明确接口语义的节点（比如数据库、API 网关），动态端口适合常规图形。

动态端口的计算思路是：以节点中心为原点，根据目标节点的相对方位选择离目标最近的边缘点作为端口位置。比如目标节点在右下，那端口就取当前节点的 bottom-right 边缘附近，同时考虑导线的进入方向，避免连线穿过节点内部。

连接规则的必要性，我是在做 ER 图时意识到的。没有连接规则，用户想把一个节点的"输出端口"连到另一个节点的"输出端口"也拦不住，这在某些场景下不算错，但在流程图里这就是混乱的源头。所以我在数据模型里内置了portRule配置，允许定义端口类型和允许的连接方向。连线创建时会在交互层做校验，不满足规则就显示红色禁止光标，并且不产生任何数据变更。这个功能把工具的"给用户自由"和"防止用户乱来"平衡得比较好。

3.5 视口缩放、缩略图与坐标陷阱

视口缩放的手势交互很简单：监听wheel事件，当按住 Ctrl/Command 键时，将滚轮滚动转换为缩放操作。缩放的核心逻辑是保持鼠标所在位置为缩放中心——也就是说，鼠标下的那个世界坐标点，在缩放前后都停留在鼠标下方。这样用户体验最好，图形不会因为缩放而滑走。

数学变换是：

function zoomAt(screenCenter: Point, newZoom: number) { const worldCenter = screenToWorld(screenCenter, viewport); viewport.zoom = clamp(newZoom, 0.1, 4); viewport.x = screenCenter.x - worldCenter.x * viewport.zoom; viewport.y = screenCenter.y - worldCenter.y * viewport.zoom; }

看起来道理很简单，但实现过程中我遇到过一个隐蔽的问题：缩放值如果取整数倍增量，比如从 0.5 到 0.75 到 1 到 1.25，在多次缩放平移之后，viewport.x/y会积累浮点误差，导致图形轻微漂移。解决办法是在缩放结束后对坐标做一次修约，同时把浮点数运算尽量集中到一次计算里，减少中间态的精度损失。

缩略图（Minimap）是一个容易被低估的功能。画布一大，用户常常缩放得很深，这时候"当前视野在整张图中处在什么位置"完全凭感觉。缩略图可以解决这个问题。它的实现没多复杂：每一帧将整张图按比例绘制在一个小 canvas 上，再绘制一个矩形框表示当前视口范围。要注意的是，缩略图矩形框的宽高需要根据 viewport 和画布尺寸做等比换算，这个坐标换算是图编辑应用的基本功。

4. 性能优化的几个关键坎

4.1 图层分层：减少每次重绘的体积

很多人第一次把图形画上 Canvas 后，遇到性能问题就会尝试"优化代码逻辑"，怎么优化都不见效。实际上，最大的性能瓶颈往往在于重绘了不该重绘的内容。

我把整个 Canvas 分为四个图层，分别对应不同的绘制逻辑：

• GridLayer（背景层）：网格线和背景色。只在缩放结束或平移结束的时候重绘，平时不动。
• LinkLayer（连线层）：所有连线路径。拖拽节点时，与节点相连的连线才需要更新路径，其他连线不动。
• NodeLayer（节点层）：所有节点图形。拖拽时重绘被拖拽的节点和受影响的部分区域即可。
• OverlayLayer（交互层）：框选矩形、磁吸参考线、悬停高亮、端口提示等临时图形。交互结束后立即清空。

画布引擎维护一个 dirty 标记列表，比如DirtyFlag.Links | DirtyFlag.Nodes，在渲染循环中只重绘标记为脏的层。

这样做的收益立竿见影：当你在拖拽一个普通节点时，背景层不用动、大量无关连线不用动，渲染成本大大降低。对于一个几百甚至上千节点的图，拖拽时也能保持满帧。

4.2 批量重绘与增量更新的取舍

理论上，Canvas 支持"只重绘某个矩形区域"的局部更新能力——调用ctx.clearRect后再把该区域内的图形重新绘制，能极大提升性能。但这个能力在实际的图编辑器里很尴尬：因为图形之间往往有重叠，只重绘一个矩形会破坏其他图形的缓冲内容，导致闪烁或残影。

所以在实际项目里，我选择了**"分层 + 全层重绘"**的组合方案。每一层内不做局部重绘，而是如果该层被标记为 dirty，就整层 clear 后重新绘制。听起来感觉笨，但比起上一帧的重绘量，这已经少了很多了。对于常见的图编辑场景来说，全层重绘一帧的性能消耗在毫秒级别，完全可以接受。如果你确实需要超高帧率（比如实时协作时），可以考虑做脏矩形裁剪，但一般项目到这个优化层级已经能解决绝大多数性能问题了。

4.3 事件系统的节流与防抖

鼠标移动事件触发的频率极高，如果在mousemove里直接做节点坐标计算、连线路由重算、磁吸对齐判断、然后触发重绘，即使是高性能机器也会出现卡顿。

我采取了三层策略：

第一层是rust 层面的节流：鼠标事件回调里只记录最新的鼠标坐标，然后统一调度下一次 rAF 帧来处理。如果这一帧已经在队列里了，就不再重复排队。

第二层是分频处理：位置计算和渲染每帧都执行，但磁吸吸附这种计算量略高的逻辑只每 2 帧执行一次，即帧率减半。反正用户几乎感知不到参考线延迟 16ms 出现，但性能上却少了一半的计算负担。

第三层是结束时的收尾计算：在鼠标释放事件中执行精确的最终对齐和连线路由计算，并把修改后的节点坐标、连线路径严格同步到数据模型，然后触发一次全量重绘。这样保证最终效果是精确的，过程中的误差只是临时的视觉展示而已。

4.4 大数据量场景下的事件名命中优化

当画布里有几千个节点时，光靠简单的遍历来做鼠标命中检测（检查坐标是否在节点矩形内）就会变成性能瓶颈。这里我用了空间哈希网格：把整个画布划分成固定大小的格子（比如 64×64 像素），每个格子记录落在其中的节点 ID 列表。鼠标移动时，只需要检查鼠标所在格子及其相邻格子里的节点，不需要遍历全图。

这个结构实现起来不复杂，但它把节点命中检测从 O(n) 降到了接近于 O(1)。实际效果是：即使画布里有 3000 个节点，鼠标划过画布时依然没有任何停顿感。这个优化我认为是所有"节点数量可能超过几百"的图编辑器都必须做的。

5. 常见问题与避坑心得

5.1 坐标系换算错误：症状与排查

遇到的第一个常见问题：画布在页面中不是从 (0,0) 开始，节点头上总有一段偏移，鼠标点击后选中不了正确元素。这个大多数时候是坐标系换算里忘了减去元素本身的getBoundingClientRect().left/top。我建议把这段逻辑封装成一个getCanvasPointFromEvent函数，所有事件入口统一走它，不要在业务代码里到处手动算clientX - canvasLeft。

排查时可以先做一个验证：在画布正中心画一个 10×10 的测试点，然后用鼠标点在测试点正上方，看是否精确命中。如果偏了，多半是换算中某个步骤忘记除以viewport.zoom。

5.2 文字在不同缩放级别下的可读性

Canvas 里的文字和 SVG 不同，不会自动跟随缩放保持锐利。如果直接按世界坐标绘制文字，当viewport.zoom小于 1 时文字会变得很小，几乎看不清；放大到 2 倍时文字又会变大得离谱。

解决方案是：绘制文字时把字号除以viewport.zoom，然后把画布坐标换算到屏幕坐标再绘制。这样无论缩放多少倍，文字始终以固定的屏幕像素字号显示。

ctx.font = `${18 / viewport.zoom}px Inter, sans-serif`; ctx.fillText(node.label, screenPt.x, screenPt.y);

但这里还有一个隐藏的坑：文字的定位也要随着缩放进行补偿。需要计算文字的实际宽度（用ctx.measureText），然后根据对齐方式换算偏移量。如果文字水平居中，那就得在屏幕坐标基础上减去文字宽度的一半。这些细节不处理好，放大缩小之后文字的位置会和节点错位。

5.3 连线的更新时机与数据一致性

拖拽节点时，所有关联连线需要更新路径。如果更新不及时，视觉上会出现"线头悬空"的尴尬。这里的关键是建立节点和连线之间的依赖关系，并确保在渲染前调用更新函数。我的做法是维护一个linkMap，记录每个节点关联的所有连线。当节点 move 时，直接查表获取关联连线，更新它们的路径并标记连线层 dirty。这个查询必须是 O(1)，不能每次都在所有连线里遍历。

还有一个容易踩的坑：勾选了"手柄拖动连线的中间节点"功能时，用户手动添加的routing点不能被自动重算逻辑覆盖。所以EdgeData里我加了一个manualPoints数组，普通的自动路由计算只会在自动路径部分工作，手动指定的点永远保留。否则用户调节好的边线路径一拖动节点就被重置，这是一个非常让人抓狂的体验问题。

5.4 撤销重做设计：命令模式是标配

撤销重做如果只是简单地把整张图的快照存下来，在节点数量达到几百时内存消耗会非常惊人。我的实现是命令模式：每个操作（插入节点、删除连线、属性修改、批量移动）都是一个Command对象，包含execute和undo两个方法。

interface Command { name: string; execute(): void; undo(): void; redo(): void; }

比如移动节点命令，不需要保存整张图，只需要保存被移动节点的旧坐标和新坐标。撤销时把坐标改回去，重做时再改回来。这样即使执行一百次操作，占用的内存也极其有限。

这里有一个实际的细节：命令栈的容量要设上限，默认 100 条就够了。不要在用户连续框选拖动了几十个操作之后，让内存跟着爆掉。撤销列表超限时自动丢弃最旧命令，这符合用户心智模型。

5.5 缩放精度与锚点抖动

缩放到某个层级后，节点边缘会出现轻微抖动。这是浮点误差在连续变换中累积的表现。解决办法是在做图形绘制时，先把世界坐标转换为屏幕坐标，并对屏幕坐标做一次四舍五入。对于 1 像素以内的误差，人眼几乎感知不到；对于交互命中的计算，则使用未经取整的精确坐标。绘制和命中分离，两边都避免误差干扰。

5.6 浏览器兼容性

这个项目大量使用了PointerEvent（指针事件），它在现代浏览器中已经全面支持，但要注意的是旧版本 Safari 对部分属性支持不完整，尤其是pointerrawupdate这类高级事件。建议在挂载事件时做 capability detection，如果环境不支持，回退成mousedown/mousemove/mouseup的兼容方案。另外 DPR 适配是必须的：Canvas 是按物理像素渲染的，需要根据window.devicePixelRatio设置 canvas 的实际宽高，否则在 Retina 屏上画出来的图形会发虚。

6. 工程化与测试：别让代码库变成泥潭

6.1 数据层的单元测试

这个项目最有测试价值的部分是我之前说的core层——它与 UI 完全解耦，非常适合写单元测试。比如坐标转换、AABB 相交检测、连线路由算法、对齐吸附计算，全都用纯函数实现，直接在 Node 环境里跑测试就行。

选 Jest 还是 Vitest 都无所谓，能跑通就行。关键是给核心算法保证正确性：路由算法尤其需要完善的测试覆盖，因为正交连线的分支很多，起点和终点的相对位置、是否存在障碍物、端口方向，这些组合一多就非常容易出 bug。写测试的时候不要只写 happy path，边界情况（两个节点完全重叠、起点终点都非常接近、图元尺寸为零）都写一下，能提前暴露很多实现漏洞。

6.2 用 Playwright 做交互回归

Canvas 的交互用单元测试是很难覆盖的，所以我用了 Playwright 做端到端测试。测试用例可以模拟真实的鼠标拖拽、缩放、连线的完整操作流，然后断言画布上生成的 GraphData JSON 是否符合预期。这里有个技巧：让画布引擎暴露一个 debug 接口，直接在 window 上挂一个getGraphData()方法，测试脚本就能快速拿到当前图的数据快照。

这个方案比截图比对可靠得多，因为数据快照的语义是确定的，不受渲染差异影响。等数据层的行为稳定下来，再考虑加截图视觉回归测试。

6.3 定制化的侵入点

这个项目不是终点，它更像一个基线版本。我给它留下的扩展点包括：

• registerNodeType(type, drawFn, options)用于注册新的节点类型，这样用户能自己实现图形绘制函数，而不需要改动核心。
• registerInteraction(handler)用于注册自定义交互逻辑，比如双击编辑文本、右键弹出菜单。
• 事件钩子：onNodeMoved、onEdgeConnected、onSelectionChanged等，方便外部系统把图编辑器的行为与业务逻辑接在一起。

这些扩展点的价值在于：当你拿着这个项目去对接真实业务时，不需要为了加一个设备节点而改到核心代码。扩展开销被控制在最小范围，长期维护的压力也小很多。

7. 最后的经验沉淀

做这个项目最大的体会是，图编辑器表面上看起来是个"画板"，实际上它是"数据模型 + 渲染引擎 + 交互系统"三个系统的合体。任何一个环节只做到 60 分，整体体验就会崩掉。数据模型设计得好，后面无论是做服务端保存、JSON 导入导出、还是多人协作，都会省非常多的力气；渲染引擎只要保障"足够快的帧率"，功能做减法可以，流畅度不能妥协；交互系统是用户每天直接面对的东西，一点小的不顺畅都会让用户对产品产生不信任感。

我在开发过程中最大的教训是：不要过早陷入对"酷炫功能"的追逐。刚开始我给项目加了十几个动画效果：节点出现时弹跳、连线绘制时流光、删除时的缩放消失……当时觉得极大提升体验，后来发现这些动画不仅拖慢帧率，还在频繁操作时让界面显得"飘"，非常影响专注。后来砍掉了绝大多数非必要动画，只保留了两处——框选完成时的高亮闪烁和连线创建成功时的小圆点生长，反而整体质感提升明显。

如果接下来你想在这个项目上继续迭代，我建议优先考虑三个方向：一是接入 Web Workers 做连线路由的并行计算，这样可以支撑更大的图规模而不阻塞主线程；二是把数据模型对齐到常见的可视化标准格式，比如导入导出 Graphviz 或 JSON Graph Format，互通能力是很多用户愿意迁移的门槛；三是做一个小而美的插件系统，让第三方开发者可以贡献节点库、图标库和样式主题——只有生态活了，一个绘图引擎才能变成一个真正的工具平台。

最后再分享一个实操中的小技巧：画布初始化时，把默认视口设置成"刚好居中并完全显示整张图"的缩放级别，用户进来不会面对一片空白无所适从。这个看似微不足道的细节，能在很大程度上降低第一次使用的陌生感。写到这里，这个项目的核心路径几乎都摊开在纸面上了。图纸本身也是代码，代码本身也是图纸——一个能优雅地在这两者之间来回转换的工具，就是我最终想做的事。