diagram-design 是我给一个自研图表设计工具起的项目代号，它解决的核心问题很直接：在没有专业绘图软件的基础上，让用户通过拖拽和连线，快速画出流程图、架构图、思维导图这类带连接关系的图示。这类需求在技术文档、系统设计、教学分享里几乎天天遇到，但常用工具要么门槛高，要么只支持静态图，改起来非常痛苦。所以我做了一个以数据模型为驱动的图表设计工具，把节点、连线、画布、样式全部抽象成结构化数据，再用SVG渲染出来。
这篇文章适合两类人看：一类是想了解图表工具底层原理的前端开发者，另一类是有画图需求但被现有工具坑过、想知道自研方案值不值的产品和技术负责人。我会从整体思路、核心技术点、完整实现过程，再到实际开发中踩过的坑，把我做这个项目的过程和复盘完整写出来。
1. 整体设计与思路拆解
1.1 为什么选择自研图表设计工具
市面上不是没有画图工具，通用绘图产品能画自由形状，在线白板能多人协作，但我实际用下来都差一口气。通用画图工具的自由度太高，没有业务约束，画出来的图风格混乱；文档里的形状工具更麻烦，画完就是一张静态图，后续节点一多，调整位置等于重画。更关键的是，这些工具无法和业务数据结构绑定，比如从接口拉回来的流程数据，没法自动展开成图。
diagram-design 的定位一开始就不是“更高级的画板”，而是“数据驱动的图表设计面板”。核心思路是：让用户用操作界面拖拽出节点和连线，背后生成一套可序列化的 JSON 模型；反过来，只要有数据模型，就能直接还原成可视化的图表。有了这套双向机制，图表工具就能嵌入到项目管理、低代码平台、在线文档中，成为真正可复用的组件，而不是孤立的白板工具。
适用场景我梳理过几类：技术人画架构图、产品经理画流程图、教师做课程知识图谱、运营做活动时间线。共同特点都是节点数量不多（一般几十到几百个）、节点之间有明确的连接关系、需要频繁调整布局和样式。这个规模下，自研工具的性价比很高，不需要引入重型引擎，一个合理的渲染方案就能跑得很顺。
1.2 方案选型：SVG 还是 Canvas
图表工具首选的渲染方案无非两种：SVG 和 Canvas。我最终选了 SVG，理由很实际。
SVG 的图形元素天然就是 DOM 的一部分，每个节点、连线都是独立元素，可以直接绑定事件、单独设置样式、用开发者工具调试，这对交互式图表来说是极大的便利。拖拽节点、高亮连线、点击选中，这些操作在 SVG 里几乎不需要自己做命中检测，浏览器全处理了。Canvas 在性能上确实更猛，适合成千上万个图形元素的场景，但代价是所有的命中检测、事件分发、状态管理都要自己实现，文本排版和可访问性也弱很多。
diagram-design 的目标场景是交互频繁、节点数通常不超过 500 个的图表编辑器，SVG 的交互便利性远重要于原始渲染性能。而且 SVG 是矢量格式，导出高清图、适配不同分辨率都很自然。当然我也保留了一个扩展点：如果以后要渲染上千个节点的数据血缘图，可以用分层渲染方案，把静态连线和复杂图形丢给 Canvas，节点交互部分保留 SVG，这个后续再说。
1.3 架构设计与数据模型
项目架构上我贯彻了一个原则：把“图的数据”和“图的绘制”彻底分离。数据层只维护模型，渲染层只负责把模型变成 SVG，交互层修改的是数据而非直接操作 DOM。这样带来的好处很多，撤销重做、保存加载、协同编辑都变得容易，因为它们操作的是同一个数据源，而不是一团散落的图形命令。
数据模型核心就两种元素：节点和连线。节点包括唯一 id、坐标、尺寸、类型和样式属性；连线通过 source 和 target 引用节点 id，而不是直接存坐标，这样节点移动时连线能自动跟着更新。画布视图状态单独存，包括缩放比例和平移偏移量。我再用一个简单的 Store 管理这些数据，任何修改都触发统一的渲染更新，类似单向数据流。
目录结构也按这个思路来划分，model 放数据定义、render 放 SVG 渲染逻辑、interaction 放拖拽和连线交互、ui 放工具条和属性面板。这样即使以后换渲染引擎，只要数据模型不变，上层 UI 基本不用动。
2. 核心细节解析与实操要点
2.1 拖拽、缩放与平移的核心实现
拖拽是所有交互的基础，我踩过最大的坑就在坐标转换上。监听容器上的 pointer 事件后，拿到的是屏幕坐标，必须换算成 SVG 里的画布坐标，否则节点会越拖越偏。正确做法是先用document.querySelector('svg').getScreenCTM()拿到 SVG 变换矩阵，再用该矩阵逆变换屏幕点，得到画布坐标；也可以用screenCTM.inverse()加原生 DOMPoint 来完成，这样能自动处理边框和内边距带来的偏移。
拖拽本身建议使用 Pointer Events 而不是传统的 Mouse Events，因为前者天然兼容鼠标、触摸和触控笔。在pointerdown时记录初始偏移，然后用setPointerCapture把指针锁定到目标元素上，后续的pointermove和pointerup都直接绑定在当前节点上，不用在全局反复绑定和解绑。需要特别留意的细节是给 SVG 容器设置touch-action: none，否则手机端拖拽会触发页面滚动，看起来就是节点刚被拿起又被夺走。
缩放和平移我采用“外层视口平移 + 内层内容缩放”的组合。最容易出问题的是缩放时保持鼠标位置不漂移，简单来说就是要让鼠标所指的点在缩放前后保持在同一画布位置。比较稳妥的做法是记录缩放前的鼠标坐标，计算缩放后新坐标与旧坐标的差值，把这个差值补偿到平移偏移量里。这个过程看起来是数学题，但只有亲手实现一次，才会真正明白为什么很多图形编辑器的缩放代码都带着那几行魔法数字。
2.2 节点连线与路径计算
连线是图表工具的核心复杂度所在。我的设计里，连线数据只保存源节点 id、目标节点 id 和路由方式，具体路径由渲染层实时计算，而不是创建时写死。这样才能保证节点被拖动时，连线始终紧贴节点边缘，不会出现“线断了”的尴尬。
锚点方面，我默认提供节点四条边的中点作为连接点。拖出连线时，如果离某个锚点足够近（比如小于 10 像素），自动吸附到锚点上。这个小小的磁吸效果能让用户感觉工具有“粘性”，体验质变。锚点的位置是按节点中心加尺寸算出来的，所以节点移动、缩放后锚点始终一致，不需要额外维护。
路由方式分两种。架构图和流程图适合正交折线，看起来干净严谨；逻辑图和思维导图适合曲线，更柔和。正交折线我用一种简化的曼哈顿路径算法：先根据源节点和目标节点的相对位置判断出口方向，再用半程点转折，生成三段式或五段式的折线路径。不要一开始就上完整的寻路算法，那会引入绕障碍、寻路权重等复杂问题，先做一版可用的再逐步迭代，符合大多数场景需要。
贝塞尔曲线则更简单，取两个节点的水平方向偏移做控制点，生成平滑的对称曲线。关键是控制点方向要和节点出口方向一致，否则曲线会走出奇怪的 S 形。
2.3 状态管理与撤销/重做
图表编辑器如果没有撤销重做，用起来就像开车没有倒挡，用户不敢操作。实现撤销重做，我选了命令模式而不是频繁保存整份快照。命令模式的思路是：把每次操作封装成一个命令对象，内部包含execute和undo两个方法。移动节点的命令记录旧坐标和新坐标；创建连线时记录连线的 id 和端点信息；删除节点的命令则要记录被删除节点和所有关联连线的完整数据，这样才能在撤销时完整恢复。
用命令模式有几个好处。第一，撤销操作是精准的，不会因为一步撤销影响到后续无关操作；第二，可以方便实现合并，比如拖拽节点整个过程中的几十次坐标变化可以合并成一个命令，用户按一次撤销，节点回到起点，而不是走一步退一格；第三，内存占用小，相比每次操作都复制整个数据模型，命令模式只存必要字段。
不过命令模式处理“批量替换样式”“清空画布”这类大操作时很吃力，快照反而更直接。我的处理是定义两种命令：小型操作记录差异，大型操作记录特定数据集的深拷贝，并在 Store 里设置了撤销栈最大长度，比如 100 步，超出后丢弃最旧的记录，避免浏览器被历史记录撑爆。
Store 本身是数据模型和 UI 之间的桥梁。每次命令执行后，Store 触发订阅者，渲染层根据最新模型重新绘制受影响的部分。这里追求的不是“性能最优”，而是“逻辑最清晰”：任何时候只要看 Store 里的数据，就知道当前图表的完整状态，这为调试和扩展带来了巨大便利。
2.4 样式系统与主题定制
节点的外观一点也不能轻视，图表工具的专业感大部分来自样式的一致性。我的方案是给每种节点类型设定默认样式模板，然后用设计令牌（design token）的方式管理颜色、边框、字体。比如流程节点默认是浅蓝底深蓝边，判断节点是菱形，开始结束节点是圆角矩形。这些映射关系放在一个主题对象中，用户可以整体切换深色主题或浅色主题。
实现上，我用 CSS 变量来做主题切换。SVG 节点的 fill 和 stroke 不写死颜色值，而是引用var(--diagram-node-color)这样的变量。切换主题时只更新顶层容器的 CSS 变量，所有节点样式自动跟随变化，渲染性能开销为零。属性面板里用户自定义的颜色会以内联样式方式覆盖主题变量，实现局部定制。
导出和导入是样式系统里的隐藏难点。SVG 一旦脱离页面环境，外部 CSS 样式就不会生效。所以在导出前，我需要遍历整个 SVG 树，把用到的 CSS 变量解析成具体的颜色值，写成内联样式，再用 XML 序列化生成独立的 SVG 文件或转成图片。这个坑几乎每个做图表导出的人都会踩一次，后面问题排查环节再细说。
3. 实操过程与核心环节实现
3.1 环境准备与项目脚手架
开发现代 Web 客户端，我习惯用 TypeScript 从头起步。选择 TypeScript 不是跟风，而是因为节点、连线、命令这些数据模型字段非常多，类型错误在编译期暴露远好过运行期才跳错。我用标准组件化前端框架搭建界面，配合一个构建工具完成本地开发服务器的启动和打包，整个过程几分钟能完成。
项目结构建议按职责清晰分区，下面是我实际使用的目录结构：
diagram-design/ ├── src/ │ ├── model/ │ │ ├── Node.ts │ │ ├── Edge.ts │ │ └── GraphModel.ts │ ├── render/ │ │ ├── SVGCanvas.ts │ │ ├── NodeRenderer.ts │ │ └── EdgeRenderer.ts │ ├── interaction/ │ │ ├── DragManager.ts │ │ ├── ConnectManager.ts │ │ └── ZoomPanManager.ts │ ├── state/ │ │ ├── Store.ts │ │ ├── Command.ts │ │ └── History.ts │ ├── ui/ │ │ ├── Toolbar.ts │ │ └── PropertyPanel.ts │ └── index.ts数据模型定义是整个项目的基础，我把它写得非常类型化，节点和连线的代码大致是这样的：
interface DiagramNode { id: string; type: 'process' | 'decision' | 'start' | 'end'; x: number; y: number; width: number; height: number; style?: NodeStyle; } interface DiagramEdge { id: string; source: string; // 指向源节点 ID target: string; // 指向目标节点 ID router: 'orthogonal' | 'bezier'; label?: string; }把节点和连线的端点设计成引用 id 而不是坐标，是做对的第一步。后续所有逻辑都围绕这两套数据展开，任何属性面板的修改都能精准落到对应的节点或连线，不会出现“数据改不动、画布不更新”的混乱。
3.2 实现一个可拖拽的 SVG 节点
第一个里程碑是让一个节点能拖起来。我把节点画在一个<g>组里，内部是一个<rect>和一个<text>。拖拽前，需要把模型数据映射成 SVG 属性，这一步交给渲染层统一处理。
核心逻辑都在 DragManager 里。pointerdown时记录鼠标在节点内的偏移，也就是鼠标坐标减去节点左上角坐标；pointermove时用当前画布坐标减去偏移，更新 Store 里的节点坐标；pointerup时结束拖拽并保存一条命令。关键代码片段如下：
class DragManager { private startOffset = { x: 0, y: 0 }; onPointerDown(e: PointerEvent, node: DiagramNode) { const canvasPoint = toCanvasCoords(e.clientX, e.clientY); this.startOffset = { x: canvasPoint.x - node.x, y: canvasPoint.y - node.y, }; e.target.setPointerCapture(e.pointerId); } onPointerMove(e: PointerEvent, node: DiagramNode) { const canvasPoint = toCanvasCoords(e.clientX, e.clientY); const nextX = Math.round(canvasPoint.x - this.startOffset.x); const nextY = Math.round(canvasPoint.y - this.startOffset.y); store.updateNodePosition(node.id, nextX, nextY); } }这里有两个细节容易忽略。第一，一定要用Math.round对坐标取整，否则节点会显示在奇数像素上，字体和边框看起来发虚；第二，在pointerdown中使用setPointerCapture，这样即使鼠标移出画布，节点也能正常移动，并且松开会自动收到pointerup，不需要额外做全局事件解除。
为了防止拖拽过程中触发浏览器原生行为，比如选中节点里的文本、出现拖拽幽灵图，需要在相关元素上禁用user-select，并在拖拽开始时调用e.preventDefault()。
3.3 实现连线与锚点的完整闭环
拖拽节点跑通之后，下一步就是连线交互。这个交互流程我拆成四个阶段：触发连接、拖动预览、目标吸附、创建连线。整个过程的反馈必须即时，用户拖出一条线时，线上要实时显示当前走向，否则很容易让人觉得工具失灵。
触发连接的方式是选中节点后会显示锚点，按住锚点开始拖拽。ConnectManager 会创建一条临时连线，起点固定为锚点坐标，终点跟随鼠标移动。移动过程中，系统检测鼠标下方是否有可连接的节点，如果有并且不是源节点自身，就把终点吸附到该节点的锚点上，并把临时连线高亮；如果位置无效，连线保持灰色，松开时不创建。
创建完整连线的数据模型操作非常轻，只是向 Store 中加入一条新的 Edge 对象，其他全部由渲染层自动完成。当用户拖动已存在的节点时，EdgeRenderer 会读取该节点的最新位置，重新计算路径。这就是引用 id 带来的好处：连线和节点之间没有冗余的坐标数据，永远不会有“线还指着旧位置”的状态问题。
连线路径计算里，正交连线的中间点数量需要控制。节点靠得近的时候，过多的拐点会让图形看起来很碎；节点离得远时，拐点太少又显得线很僵硬。我的策略是：先计算两点之间的中间距离，如果小于某个阈值，直接使用单拐点；否则使用双拐点或多拐点，并且保证拐点按“源节点出口方向优先”生成。
3.4 性能优化与渲染方案
SVG 方案交互很爽，但也需要小心性能。最大的性能杀手是拖拽节点时，所有相连的连线都重新计算并触发 DOM 更新，如果连线数量多、路径计算复杂，就会感到卡顿。最有效的优化是给渲染更新加一层节流——拖拽过程中不每次移动都对连线做全量重绘，而是使用requestAnimationFrame合并同一帧内的多次更新，保证一帧只重绘一次。
针对 SVG DOM 的更新，我建议优先修改已有元素的属性，而不是销毁重建。创建节点和连线时，建立 id 到 SVG 元素的映射；数据变化时，通过映射找到对应元素，只更新位置、路径或样式属性。这样能大幅减少 DOM 节点的创建销毁次数，也方便做局部更新。
如果节点数量真的涨到几千，SVG 也会吃力。那时可以引入“视口裁剪渲染”——只渲染当前可视区域内的节点和连线，用户平移缩放时实时调整渲染范围。更高阶的方案是把背景网格和大量连线丢给 Canvas 画，SVG 只保留节点层做交互，形成混合渲染架构。我虽然没用这套方案，但在架构层面留了接口，后续扩展不至于推倒重来。
4. 常见问题与排查技巧实录
4.1 拖拽卡顿与事件冲突
做演示 demo 时最容易暴露的是卡顿和诡异位移。有一次我拖拽一个节点，节点不但没跟着鼠标走，反而跳到画布左上角。查到最后发现是坐标转换时用了错误的参考对象，把鼠标坐标直接当成 SVG 坐标用了，没有经过矩阵逆变换。排查思路很简单：拖拽时打印鼠标和节点的画布坐标做对比，只要两个值差值稳定，说明坐标转换正确；如果不稳定，基本就是矩阵转换算错了。
另一个高频问题是页面上的文本选中、图片拖拽等原生行为干扰交互。解决方法是给 SVG 容器和节点元素设置user-select: none，拖拽节点时在pointermove里调用preventDefault。如果页面还有滚动容器，还要考虑触控板双指滑动和平移手势的冲突，设置容器的touch-action为none可以切断大部分浏览器默认手势。
4.2 连线坐标偏差问题
有次用户反馈，两个节点明明紧挨着，连线端点却偏离节点边框几像素。我在高倍屏设备上一测，发现同样的坐标在普通屏幕显示正常，在 2 倍屏上偏差明显。根因是 CSS 像素和设备物理像素之间存在 dpr 缩放，当连线路径计算用了屏幕坐标而节点用画布坐标时，就会出现不一致。统一所有坐标换算到头结点的固定参考坐标系里，问题就彻底消失了。
另外一个很隐蔽的偏差来自节点边框宽度。默认边框是居中的，路径如果直接连接到节点矩形边界，实际上是连到了矩形外边缘而不是边框中心线。我后来把每个节点的连接点按“矩形外扩半个边框宽度”计算，确保线条末端和边框外沿完美贴合。
4.3 撤销/重做栈的内存管理
项目做到后面，用户开始往画布上拖入几十张图片节点，撤销操作就变得异常缓慢。原因是我最初对删除操作采用了“深拷贝整张图”的做法，删除一个节点就复制一次全量数据。优化方案是命令里只记录必要数据，删除节点命令同时记录被删除节点和被连带删除的连线信息，这样撤销时不需要还原整张图。撤销栈也加了上限，超过 100 条命令自动丢弃最旧记录。
其实撤销重做还有一种更省内存的思路：操作日志做成带引用关系的序列化数据，存储某个字段的变化路径，而不是完整副本。但这套方案实现复杂度高，对中小型编辑器性价比不高，所以我没有用。实际开发还是先保证逻辑正确，再优化内存，不要为了炫技把简单问题复杂化。
4.4 导出图片与打印问题
导出是图表工具逃不开的功能。我最初直接用浏览器打印页面的方式保存，结果导出图里的颜色全变了，字体也乱了。后来改用独立渲染方案：先遍历图表数据，生成一个干净的 SVG 字符串，把样式全部内联成具体颜色值，再通过XMLSerializer序列化，最后用封装的 Image 对象把 SVG 转成 PNG 下载。注意 SVG 里如果有<foreignObject>嵌入 HTML，转图片时会被浏览器拦截，所以我在导出时统一用 SVG 原生的<text>元素。
另一个风险是字体跨环境失效。图表里使用了自定义字体时，导出的图片在其他设备上可能回退成系统字体，导致排版错乱。稳妥做法是导出前检查字体是否有 woff2 文件，把它以 Data URL 形式嵌入 SVG 的 @font-face 声明中。如果字体文件太大，就直接回退到通用字体，或者把关键文字转成路径，虽然复杂度高一些，但效果最稳定。
从这几个问题可以看出来，图表工具开发中大量的时间不是花在“画图”本身，而是花在坐标转换、数据同步、样式兼容这些暗坑上。很多问题只有在真实设备上跑一遍才会暴露，所以我一直建议把功能演示版尽早给团队内部使用，不同浏览器、不同分辨率的反馈比自测更有效。
做 diagram-design 的过程中我最大的感受是：真正决定一个图表工具好不好用的，往往不是底层渲染性能，而是数据模型设计得是否干净。只要让所有交互都落在明确的数据变更上，后续的撤销、保存、协作、扩展都会自然顺起来。如果你也准备做一个类似的东西，我建议先花两天把数据模型想清楚，再动手画界面，走弯路会少很多。最后一个小技巧分享给你：画布背景网格不要用图片，直接用 SVG pattern 画两套网格线，一套浅色细线一套深色粗线，视觉层次立刻专业很多。
