企业官网建设流程全解析

diagram-design 这个项目，说起来其实是被实际业务逼出来的。当时我们团队在做一款业务中台类的产品，开发和交付过程中需要大量绘制架构图、流程图、部署拓扑图，但工具散落在各处：有人用通用绘图软件，有人直接在文档里用文本拼，还有人临时用协作白板画完截图贴进文档。结果就是图跟代码严重脱节，一改需求就要重画，线上文档里的图和实际系统架构经常对不上，维护成本越来越高。

所以这个项目的目标从一开始就很明确：做一个能嵌入业务系统的绘图组件，让用户直接在页面上拖拽节点、画连线、导出图片，同时能把图的数据结构序列化存储下来，下次打开还能完整还原。它不是一个独立的绘图软件，而是可以被其他业务模块复用的"绘图能力"。这篇文章我会把整个 diagram-design 项目的拆解思路、技术选型、核心实现和踩坑记录完整写一遍。如果你正准备做类似的绘图工具、流程图编辑器、拓扑图面板，或者只是对这类前端交互密集型项目感兴趣，这篇文章应该能给你一些可以直接抄作业的参考。

1. 项目背景与需求拆解

1.1 先把"绘图工具"这个词拆开看

diagram-design 听起来像是一个偏设计感的项目，但实际上它要构建的是一个可交互的图形编辑器，核心能力拆成三块：画布、图形、交互。

画布负责承载所有图形元素，负责缩放、平移、坐标系转换；图形指节点（矩形、圆形、菱形、自定义组件）、连线（直线、折线、曲线）、分组容器这些可绘制对象；交互则包含拖拽移动、框选、缩放节点、连接锚点、撤销重做这套操作体系。

这三块不是并列关系，而是有清晰依赖的：交互层依赖图形层的几何信息，图形层依赖画布层的坐标系统，数据层则独立于渲染层存在。把这条依赖链理清楚，整个项目的架构就成功了一半。我们后期所有新功能的扩展速度，都取决于当初这条链路划分得干不干净。

1.2 需求边界：什么该做，什么坚决不做

立项时的第一件事不是列功能，而是划边界。我们当时明确了两条原则。

第一，不做复杂的自动布局算法。自动布局（树形布局、力导向布局）听起来很酷，但需求调研发现，绝大多数用户在使用绘图工具时，对布局有很强的主观控制欲——他们希望自己摆位置，而不是让算法替他们决定。自动布局可以作为后续的加分项，但绝不能作为核心依赖，否则项目一开始就会陷入算法地狱。

第二，不追求 PPT 级别的炫酷渲染。绘图组件的核心价值是"准确表达关系和结构"，而不是"好看"。所以我们把大量精力花在坐标计算、连线路径、命中检测这些硬核功能上，而不是做光影、渐变、粒子效果。这个判断在后面被证实是划算的：很多用户反馈里提到的都是"连线对不对齐""缩放会不会卡"，没有一个人说"节点阴影不够柔和"。

这样划完边界之后，功能清单就清晰了：

• 基础画布：无限画布、缩放（0.2x 到 4x）、平移、网格吸附
• 节点系统：矩形/圆形/菱形/图片节点、自定义节点尺寸、文字标签、边框样式
• 连线系统：直线、直角折线、曲线贝塞尔、锚点自动吸附、连线标签
• 交互系统：拖拽、框选、多选、右键菜单、快捷键（Delete、Ctrl+C/V、Ctrl+Z/Y）
• 数据能力：JSON 序列化反序列化、导入导出
• 对外接口：事件回调（选中变化、元素变更）、只读模式、自定义渲染插槽

2. 核心技术选型：每一步都是取舍

2.1 渲染方案：SVG、Canvas 还是 DOM

这是绘图工具类项目必须回答的第一个问题。我见过不少项目在这里拍脑袋做了决定，后期想改已经来不及了。

我们当时做了三轮方案评估，分别用三种技术各写了一个最小原型，跑了同样的压力测试。结论如下：

最终我们选了 SVG 为主渲染方案，原因有三个。第一，我们需要支持用户在图上直接编辑文本，SVG 的 text 元素配合 DOM 事件做起来最顺手。第二，节点数量在绝大多数真实场景下不会超过两三百个，SVG 的性能完全够用。第三，SVG 天然支持事件委托，可以在根节点上统一监听所有子元素的事件，不用像 Canvas 那样自己维护事件队列和命中检测逻辑。

但这里有一个很重要的补充：如果你确定业务场景里会出现单画布超过 1000 个节点的情况，建议直接用 Canvas。我们后续在做性能优化时发现，SVG 的瓶颈不在于绘制本身，而在于 DOM 事件绑定数量和重绘成本的不可控。方案没有绝对的好坏，只有适不适合你的真实场景。

2.2 状态管理：数据与渲染必须分离

绘图工具的复杂度很大一部分来自状态管理。节点位置变了、缩放比例变了、选中了哪些元素、当前拖拽的是谁……这些状态如果散落在各处全局变量里，项目很快会变成一团乱麻。

我们采用了"单一数据源 + 发布订阅"的模式。整个画布的状态收敛为一个 JSON 对象，结构大致如下：

{ "canvas": { "zoom": 1, "offsetX": 100, "offsetY": 50 }, "nodes": [ { "id": "node_1", "type": "rect", "x": 120, "y": 80, "width": 160, "height": 60, "style": { "fill": "#ffffff", "stroke": "#333333" }, "text": "订单服务" } ], "edges": [ { "id": "edge_1", "source": "node_1", "target": "node_2", "sourceAnchor": "right", "targetAnchor": "left" } ] }

任何操作（移动、缩放、删除、编辑文本）都通过统一的 action 修改这个数据源，然后由渲染层根据数据源的变化增量更新 SVG。这样做的收益是整个项目期都在持续兑现的：撤销重做只需要保存操作前后的数据快照或者操作日志；序列化和反序列化就是 JSON 的 stringify 和 parse；调试时可以随时打印出整个画布的状态；未来做多人协作也只需要同步这一个数据源。

2.3 交互状态机：拖拽、缩放不打架

交互是绘图工具最容易出 bug 的地方。节点拖拽和画布拖拽冲突、框选和节点拖拽冲突、双击编辑和单击选中的区分……这些问题如果不从架构层面解决，写出来的代码会是一堆 if-else 补丁，而且每加一个交互就会把之前的逻辑弄坏。

我们的做法是引入了一个简单的交互状态机。每次鼠标按下时，根据按下的位置和当前的工具模式，决定进入哪个状态：

• idle：无操作状态
• draggingNode：拖拽单个或多个节点
• panning：平移画布
• rubberBand：框选
• resizing：调整节点尺寸
• connecting：从锚点拖出连线

每个状态对应一个独立的处理器，鼠标移动和鼠标抬起的事件由当前状态的处理器接管。状态切换有明确的条件，比如"按下时点中的是节点空白区域且当前工具是选择工具"才进入 rubberBand，"点中的是节点本体"才进入 draggingNode。这个设计直接让代码的可维护性提升了一个档次，后面加橡皮筋框选、自由绘制工具，都只是新增一个状态，不用改动已有逻辑。

3. 核心机制剖析：数据、渲染与交互三层分离

3.1 数据层：元素模型的通用化设计

绘图工具里的元素形态各异：矩形、圆形、菱形、文本、图片，甚至未来的自定义组件。如果我们为每种元素单独写一套数据结构，代码会大量重复，每加一个类型就要动一遍主逻辑。所以数据层做了一个通用化的设计。

所有元素共享一个基础结构：

class ElementModel { id = uuid(); type = 'base'; x = 0; y = 0; zIndex = 0; selected = false; attrs = {}; // 尺寸、半径等几何属性 style = {}; // 描边、填充、字号等样式属性 data = {}; // 业务自定义数据，永远不参与渲染 toJSON() { ... } static fromJSON(json) { ... } }

type 字段用来区分具体类型，每种类型注册自己的渲染函数、几何计算函数、属性面板配置。这样新增一种节点类型时，不需要动主框架，只需要注册一个新的 type。这个模式在后期接入业务方自定义节点时立了大功——业务方甚至不需要理解整个框架，只需要按约定的接口实现一个渲染函数，节点就能在画布上正常工作。

这里有一个实践要点：data 字段和 attrs 字段必须严格分开。data 存放业务数据，比如节点代表的服务器 IP、进程名、监控指标；attrs 只负责几何信息。如果混在一起，后期做数据联动和序列化兼容时会非常痛苦。你永远不希望因为某个业务数据变了，导致整个画布重新渲染，或者因为渲染参数混进了业务数据，连线的样式被莫名改掉。

3.2 渲染层：增量更新与批量调度

SVG 的渲染层核心是"如何把数据源的变化映射到 DOM 变更"。最粗暴的做法是每次数据变化都把整个 SVG 重新生成一遍，但这样在大画布上会造成明显的卡顿和闪烁，点击一个节点整个画布都重绘，视觉上非常不稳。

我们采用的是"元素级增量更新"策略。每一个元素模型对应一个 SVG 节点，渲染层维护一个映射表：

const svgElementMap = { 'node_1': <rect ...>, 'node_2': <g>...</g> }

当数据变化时，不是重绘整个画布，而是找到变化的元素，只更新那个元素的 SVG 属性。移动一个节点，只改它的 x/y 属性；缩放一个节点，只改它的 width/height；删除元素时，只 remove 对应的 SVG 节点。这个思路跟浏览器渲染里的脏矩形检查异曲同工：只重绘变化的部分，而不是全部。

配合这个机制，还需要一个调度器。当一个操作（比如拖拽移动）会高频触发数据变化时，不要每次数据变化都立刻操作 DOM，而是用一个 requestAnimationFrame 批量处理。实测下来，50 个节点同时拖拽时，帧率从 30fps 提升到了稳定的 60fps。批量调度这块是整个渲染层性能优化的最大单项收益，一定要做。

3.3 交互层：坐标转换是核心中的核心

画布有缩放和平移，意味着屏幕坐标和画布坐标之间永远存在一层转换。这个转换做错了，所有交互都会出问题。而且这类 bug 有个特点：早期功能简单时不容易暴露，等节点多了、缩放频繁了，各种错位问题会集中爆发。

核心公式其实只有两个：

// 屏幕坐标转画布坐标（鼠标在某元素上的位置） const canvasX = (clientX - rect.left - offsetX) / zoom; const canvasY = (clientY - rect.top - offsetY) / zoom; // 画布坐标转屏幕坐标（渲染元素时） const screenX = canvasX * zoom + offsetX; const screenY = canvasY * zoom + offsetY;

offsetX/offsetY 是画布在当前视口中的偏移量，zoom 是缩放比例。看起来简单，但实际工程里有三个容易踩的坑。

第一，鼠标事件里拿到的 clientX/clientY 是视口坐标，必须先减去 SVG 元素相对视口的 offsetLeft/offsetTop，再进入坐标转换。第二，缩放时如果以鼠标为中心缩放，需要在缩放前后重新计算 offsetX/offsetY，保证鼠标下的那个画布点不漂移。第三，所有命中检测（点击选中的是哪个节点）都必须基于画布坐标，不能用屏幕坐标直接判断，否则缩放后点击区域会错位。我们有个线上 bug 就是这三个坑里的第一个引起的，排查了整整两天，最后发现就是差了一个 rect.left。

3.4 命中检测：看不见的底层能力

命中检测是绘图工具里最容易被忽略、但做不好就处处难受的功能。SVG 虽然自带事件命中，但是在缩放极小、节点密集、图形重叠的场景下，默认命中表现并不符合预期。

我们的命中检测框架是这样的：每个元素类型注册一个 hitTest 函数，输入画布坐标，输出是否命中以及命中的具体位置（是本体、是锚点、是缩放手柄）。对于矩形用 AABB 检测：x >= node.x && x <= node.x + width；圆形用距离检测：点到圆心的距离小于半径；文字用 bbox 检测。

这里有一个经验细节：所有命中检测都基于画布坐标，而不是屏幕坐标。因为画布坐标不随缩放变化，在这个坐标系里做几何运算最简单、最稳定。而且我们要求所有元素的命中检测函数必须注册到同一个表里，交互层只负责遍历顺序（从顶层往下），这样新增元素类型时命中检测天然可用，不会出现"画得出来但点不中"的尴尬。

4. 实操落地：核心功能的完整实现步骤

4.1 第一步：搭建画布骨架

画布容器我建议用两层结构：外层 div 负责滚动和事件捕获，内层 SVG 负责渲染。这样滚动条和绘图区互不干扰，后续做事件委托也只挂在 SVG 根节点上。

初始化时，需要设置 SVG 的 viewBox 和尺寸。我们的实现里，SVG 的宽度和高度等于视口大小，画布的"无限延伸"通过修改 offsetX/offsetY 和 zoom 来实现，而不是给 SVG 设一个巨大的宽高。这个设计的优势是：无论画布内容有多少，浏览器只需要维护一个视口大小的 SVG 节点，性能开销非常小。如果给 SVG 设一个 10000x10000 的宽高，虽然可以容纳更多内容，但每个像素都有布局计算成本，卡顿是必然的。

事件监听上，我们把 mousedown 挂在 SVG 根节点上，mousemove 和 mouseup 挂在 window 上。这样即使鼠标拖拽速度太快移出了 SVG 区域，松手的事件也不会丢，避免出现"拖出去了就卡住"的经典问题。

4.2 第二步：实现节点的渲染与选中

渲染一个矩形节点，核心是生成一段 SVG 并绑定事件。我们封装了一个渲染函数，接收元素模型，输出 SVG DOM。这里直接上一个简化后的核心代码：

function renderNode(model) { const g = createSvgElement('g'); g.setAttribute('data-id', model.id); g.setAttribute('data-type', 'node'); const rect = createSvgElement('rect'); rect.setAttribute('x', model.x); rect.setAttribute('y', model.y); rect.setAttribute('width', model.attrs.width); rect.setAttribute('height', model.attrs.height); rect.setAttribute('fill', model.style.fill); rect.setAttribute('stroke', model.style.stroke); g.appendChild(rect); const text = createSvgElement('text'); text.setAttribute('x', model.x + model.attrs.width / 2); text.setAttribute('y', model.y + model.attrs.height / 2); text.setAttribute('text-anchor', 'middle'); text.setAttribute('dominant-baseline', 'central'); text.textContent = model.text; g.appendChild(text); return g; }

值得展开讲一下的是选中态的处理。选中一个节点后，通常要显示四个角上的缩放手柄和一个虚线边框。我们的做法是：每个节点渲染成一组<g>元素，里面包含主图形、文字、选中态的手柄元素。选中态默认隐藏，只有在 selected 为 true 时才显示。

这里有个性能细节：手柄元素不能滥用 CSS 的 display 切换，因为每次切换都会触发重排。我们直接使用 SVG 的 visibility 属性来隐藏和显示手柄，实测在快速连续点击多个节点时，闪烁问题明显减少。而且缩放手柄的渲染也是动态的：只有节点宽度和高度大于一定阈值时才显示四角手柄，节点小到没必要缩放时就隐藏，避免误操作。

4.3 第三步：连线的锚点与路径计算

连线是绘图工具里最容易出 bug 的部分，没有之一。节点可以移动，线必须跟着动；节点有多个锚点，线要连到最近的锚点；线的路径有直线、折线、曲线三种模式。而且连线出问题时往往很隐蔽——不是不能用，而是路径看起来别扭、拐弯角度怪异、缩放后锚点错位。

锚点系统我们第一版做的是固定锚点方案：矩形的四边中点各有一个锚点，圆形有上下左右四个锚点。连线时，记录 sourceAnchor 和 targetAnchor，当节点移动时，重新计算锚点的坐标并更新路径。这个过程必须走纯函数，方便测试。

路径计算上，曲线连线用的是三次贝塞尔，控制点的计算规则是：从 source 锚点出发，控制点沿着锚点法线方向延伸一段距离，距离等于两个节点距离的一半（限制在 40 到 200 之间）。直角折线则是先水平走一段，再垂直走一段，再水平走到目标锚点。这个规则写出来不难，难点在边界条件：两个节点重叠时距离为 0，控制点距离要兜底到 40；两个节点水平对齐时，垂直段长度为 0，要避免产生 0 长度的无效路径。

这里有一个非常实用的经验：连线的路径更新不要直接改 SVG 的 d 属性，而是把 d 的计算封装成纯函数并单独维护。我们把 path 生成函数单独拎出来测了几十个场景，确保锚点位置、节点尺寸、缩放比例的各种组合下，路径都不会出现明显的断点、回折或交叉。这类几何计算函数是最适合单测的，一次跑通以后就基本不用管了。

4.4 第四步：缩放与平移

缩放功能的体验细节比想象中多。我们用的是"以鼠标位置为中心"的缩放方式，也就是鼠标指到哪里，哪里就保持不动，画布围绕这个点缩放。这是主流绘图工具的基本交互习惯，用户从其他工具迁移过来不需要重新学习。

实现公式为：

function zoomAt(clientX, clientY, newZoom) { const rect = container.getBoundingClientRect(); const prevZoom = state.canvas.zoom; // 先计算鼠标所指的画布坐标 const wx = (clientX - rect.left - state.canvas.offsetX) / prevZoom; const wy = (clientY - rect.top - state.canvas.offsetY) / prevZoom; // 应用新的缩放比例 state.canvas.zoom = clamp(newZoom, 0.2, 4); // 反解偏移量，保证 wx/wy 位置不动 state.canvas.offsetX = clientX - rect.left - wx * state.canvas.zoom; state.canvas.offsetY = clientY - rect.top - wy * state.canvas.zoom; }

wx/wy 是缩放前鼠标所指的画布坐标，缩放后反解 offset，保证鼠标位置下的画布点坐标不变。缩放范围我们限制在 0.2 到 4 倍，低于 0.2 时节点会太小无法操作，高于 4 倍时边缘模糊没有意义。

平移的实现用鼠标中键按住拖动，或者按住空格键切换到临时手形工具再左键拖动。注意两个细节：中键拖拽的过程中要阻止默认行为和文本选择，否则会出现滚动条跳动和文字选中的问题；光标样式也要跟着状态切换，拖拽时显示 grabbing，让用户明确感知当前处于平移模式。

4.5 第五步：撤销重做

撤销重做我们用了一个很朴素却很稳定的实现——命令模式。每次用户的操作（移动、新增、删除、改样式）都会生成一个命令对象：

class Command { constructor(label, doFn, undoFn) { this.label = label; this.doFn = doFn; this.undoFn = undoFn; } execute() { this.doFn(); } undo() { this.undoFn(); } }

操作发生时：执行 doFn，并把命令压入 undoStack，同时清空 redoStack。撤销时：弹出最后一条命令执行 undoFn，压入 redoStack。重做时反向操作。这个模式看起来简单，但有一个隐蔽的坑：命令对象里捕获的变量必须是操作前的快照值。

举个例子，移动节点时 doFn 把节点从 (x1,y1) 移到 (x2,y2)，undoFn 需要把节点移回 (x1,y1)。如果 undoFn 里写的是"读取当前坐标再减 delta"，第二次撤销就会出错。正确做法是让 undoFn 直接闭包捕获 (x1,y1) 和 (x2,y2)，每次撤销都设置到固定值，而不是做增量计算。

相比直接保存 JSON 快照，命令模式的优点是内存占用小、支持细粒度撤销（用户不想因为移动了 20 个像素就撤销掉整轮操作），而且可以为每条命令记录一个友好的描述文本，用于在撤销面板里展示"已撤销：移动节点"。我们后期还基于这套命令体系做了一个操作历史时间线，几乎零成本实现。

5. 踩坑记录与排查清单

5.1 高频问题：画布拖动和节点拖动打架

开发过程中遇到的第一个高频问题，是在节点上按下鼠标时，既想选中节点，又不想让画布跟着平移。解决方式是事件触发顺序判断：在 mousedown 时先做命中检测，如果点中了节点，则本次交互状态是 draggingNode，画布平移相关的监听器不再响应；如果点中的是画布空白区域，则进入 rubberBand 或 panning。

这里还要处理一个边界：节点很小的时候（比如缩放低于 0.3），用户很难点中，体验很差。我们的方案是对命中检测做了扩界处理——对节点实际尺寸至少增加 8 像素的命中半径，让节点在缩小后依然容易被选中。但扩界只影响选中，不影响拖拽后的贴边视觉效果，否则看着都点中了，拖起来却对不齐，反而更难受。

5.2 高频问题：缩放后导出图片模糊

导图功能上线后，有用户反馈导出的 PNG 在高分屏上模糊。原因很简单：导出时没有考虑 devicePixelRatio。修复方案是导出前临时把 SVG 的宽高放大 dpr 倍，渲染后再缩放回来。但要注意，这样做会触发一次额外的重绘，大画布导出时可能会有短暂的画面跳动，建议导出期间加一个 loading 遮罩。

这个问题的另一个教训是：任何涉及图片导出的绘图工具，建议一开始就把 dpr 纳入设计，否则后期改导出逻辑时，会影响一大批依赖导出结果的周边功能（比如分享图生成、文档嵌入）。

5.3 性能笔记：大数据量下的卡顿优化

一次客户压测，单画布塞入了 1200 个节点、1500 条连线，卡顿明显。我们做了三轮优化。

第一轮：把所有事件监听器从每个 SVG 节点上移除，改成在根 SVG 上做事件委托，用 closest 找到目标元素。这一轮减少了约 60% 的监听器数量。之前每个节点都绑了自己的 click、mousedown、mouseenter 等五六个事件，1200 个节点就是六千多个监听器，光是注册和销毁就是一笔大开销。

第二轮：优化连线的路径更新。原来每条线的路径变化都会立刻更新 DOM，我们加了一个批量更新队列，把同一帧内的多次路径更新合并为一次。因为拖拽一个节点会同时触发几十条连线重算，如果每条线各自更新，一帧内会有几十次 DOM 写入，合并后只有一次。

第三轮：降低网格吸附的计算频率。原来每次 mousemove 都做网格吸附计算，我们改成每 16ms 只计算一次，吸附的"磁性"手感几乎不受影响，但 CPU 占用明显下降。网格吸附这块是典型的"高频低变化"操作，非常适合做节流处理。

5.4 常见问题速查表

6. 个人体会：绘图项目的工程复杂度比想象中高

整个 diagram-design 项目从立项到第一个可用的版本，我们用了大概六周，但这六周里最耗时间的不是写渲染代码，而是处理交互细节。绘图工具这种项目，看起来就是个"画框框、连箭头"，实际做下来你会发现，坐标转换、命中检测、状态切换、事件优先级，每一个环节都是一个独立的微型工程，任何一个环节的粗糙处理，都会在用户的高频操作里被无限放大。

我最大的体会是：这类项目一定要把数据层和渲染层彻底分开。凡是图形编辑类项目，最终都会遇到"同一个数据多种视图"的需求——可能是缩略图、只读预览、打印视图，也可能是协作时的远程光标。如果渲染逻辑和业务数据耦合在一起，这些需求每一个都会让你改到崩溃。我们因为提前做了数据驱动渲染，后面加只读模式和缩略图功能时，几乎没动主框架，只是加了两个新的视图订阅者而已。

另外一个建议是：如果你要做类似的项目，先把坐标系转换和命中检测这两个基础模块吃透，然后立刻写单元测试。这两个模块是整个系统的地基，地基稳了，上面盖什么楼都踏实。我们后期修的绝大多数 bug，最后定位到的根因都在坐标转换的边界条件上。不是其他模块没问题，而是其他模块出问题一眼就能看出来，坐标转换出问题却常常表现为"点击位置差一点""拖拽有点歪"这类很难描述的玄学问题，排查成本极高。

最后分享一个小技巧：开发阶段在调试面板里把"当前坐标、当前缩放、命中元素 ID"实时显示出来，排查问题的速度会快非常多。这个看似不起眼的调试信息，帮我们省下了大量反复 console.log 的时间。如果你也在做类似的工具项目，强烈建议从第一天就加上这个调试面板，等出了问题再加就有点晚了。