1. 项目定位为什么需要重造一个 diagram-designdiagram-design 这个项目最早是因为我自己要维护一套内部系统的架构文档。技术文档写了一大堆但流程图和架构图基本靠手画白板拍照或者用通用绘图软件加班调整格式。后来团队里做设计评审发现大家传的图片格式不统一改起来特别痛苦于是萌生了一个想法与其到处找现成的在线绘图工具不如在项目内部做一个轻量级、可复用、能嵌入现有工作台的 Diagram 设计器。其实这个需求听起来不复杂但真正动手做会发现坑特别多。市面上能画流程图的库不少但很多要么是纯展示型要么是偏重数据可视化想要改一个图形、拖一条连线、导出高清图反而不够灵活。diagram-design 的定位就是解决这类轻交互、重定制、要落地的场景你可以拖拽节点、画连线、调整布局、导出多种格式把数据模型完全掌握在自己手里。这个项目适合谁参考如果你也在做一个需要内嵌图形编辑功能的 Web 应用——比如低代码平台的流程编排、知识库的架构图插件、教学工具里的图形编辑器——那这篇经验总结会比较对口。我会从技术选型、数据模型、交互实现、序列化导出几个维度展开把完整的设计思路和踩过的坑都摊开来讲。个人更认可的一个做法是不要一上来就想着做一个完整的产品而是先做一个最小可用的核心引擎。diagram-design 的迭代路径也就是这样——先把画布、图元、连线三个最核心的东西跑通再逐步加布局、导出、撤销重做这些外围能力。2. 核心设计思路与整体架构拆解2.1 先想清楚画布的本质是什么做 diagram 编辑器第一件事不是写菜单栏也不是做一堆花哨的工具按钮而是把画布内核定义清楚。画布本质上是一块无限大的逻辑平面DOM 只是它的投影窗。这意味着你的数据模型里必须区分两组坐标逻辑坐标世界坐标和屏幕坐标。逻辑坐标就是图元在无限画布上的位置比如某个节点位于1200, 800这个坐标是固定的不随缩放滚动变化。屏幕坐标是用户当前看到的像素位置它受平移 offset 和缩放比例 scale 影响。两者之间需要一套双向换算函数。我见过不少半成品项目把所有坐标都存成屏幕坐标结果一滚动画布、一缩放所有节点位置全部错乱。diagram-design 从一开始就严格分离这两层数据模型里只存逻辑坐标渲染层每次通过变换矩阵或换算函数输出到屏幕这样各种操作的风险都降了一大截。这套逻辑的代码骨架大概长这样这是早期原型后面我做了大量迭代// 坐标转换核心世界坐标 - 屏幕坐标 function worldToScreen(worldPoint, viewport) { return { x: (worldPoint.x - viewport.offsetX) * viewport.scale, y: (worldPoint.y - viewport.offsetY) * viewport.scale }; } function screenToWorld(screenPoint, viewport) { return { x: screenPoint.x / viewport.scale viewport.offsetX, y: screenPoint.y / viewport.scale viewport.offsetY }; }2.2 图元模型节点、连线与锚点Port一张 diagram 由三种基础元素组成Node节点、Edge连线、Port连接锚点。其中 Port 是最容易被新手忽略的隐藏角色。Port 是节点边界上用于连接线的点位。比如一个开始节点的底部要连出一条线到处理节点那么线的起点不是随便挂在节点矩形边框上而是应该绑定到某个 port 上。这样做有两个好处第一连续移动节点时连线会跟随 port 走不会跑偏第二导出数据时连线的拓扑关系非常清晰——节点A的bottom端口连接到节点B的top端口而不是一条线从坐标A到坐标B。diagram-design 的图元模型遵循这样一份简洁的 JSON Schema{ id: node_001, type: round-rect, x: 320, y: 180, width: 140, height: 56, ports: [ { id: p_top, position: top }, { id: p_bottom, position: bottom }, { id: p_left, position: left }, { id: p_right, position: right } ], attrs: { label: 发起请求, style: { fill: #f5f7fb, stroke: #4c7bd9 } } }节点的几何信息 x、y、width、height 管定位type 管外观类型attrs 管业务数据。所有节点统一走这个模型后新增一种图元类型只需要往注册表里加一个绘制函数不用改数据结构。2.3 渲染层选型SVG 与 Canvas 的取舍diagram-design 在这个问题上纠结过我把自己踩过的两个方案都讲一下。早期原型用的是 Canvas 渲染。Canvas 的优势是绘制性能高几百个节点重绘没有压力而且导出 PNG 特别顺畅。但缺点也明显节点多了以后想要给单个节点加 CSS 动画、做事件命中检测、或者给连线加虚线动画都得自己实现一套开发成本成倍上升。后来我把主场景切到 SVG 渲染。SVG 本身就是结构化 DOM每个节点是一个元素里面可以嵌 rect、text、path天然支持事件绑定、样式管理、浏览器原生渲染。对于这类图元数量通常在几十到几百个之间的编辑器场景SVG 的性能完全足够换来的开发效率却是实打实的。不过纯 SVG 在极大规模图比如超过 2000 个节点下的重绘性能会明显下滑。diagram-design 的解法是做分层渲染静态背景层、图元层、临时交互层分开放置交互层只承载当前拖拽中的幽灵元素和预览连线这样图元重绘时不需要全量刷新。2.4 图元注册表与工厂模式画布上能画哪些东西它们长得什么样、有哪些可编辑属性diagram-design 用一张注册表统一管理。所谓注册表就是一个 key 到图元配置的映射const registry { round-rect: { draw: (ctx) { /* 返回 SVG 元素 */ }, properties: [label, fill, stroke], defaultSize: { width: 140, height: 56 } }, diamond: { draw: (ctx) { /* 菱形绘制逻辑 */ }, properties: [label, color], defaultSize: { width: 120, height: 80 } } };这种设计最大的价值是可扩展性。团队里有人想加一个云资源图标只需要注册一个新的 type实现在工具栏里出现一个入口连线的样式、箭头的类型同样通过配置项驱动。用工厂模式创建图元实例配合注册表做动态查找是这类工具项目里性价比非常高的架构决策。对比一下接到需求就堆 if else和注册表模式两种写法前者每加一种图形就要动核心渲染循环越改越复杂后者新增图形只动注册配置核心逻辑完全不动。diagram-design 的迭代能保持稳健这个决策功不可没。3. 核心交互实现拖拽、缩放与连线3.1 事件模型统一 Pointer 事件处理浏览器里鼠标事件和触屏事件是两套体系如果分别实现代码量会膨胀还会碰到各种诡异的兼容问题。diagram-design 直接采用 Pointer Events指针事件它把鼠标、触控笔、手指统一为 pointerdown、pointermove、pointerup 一套流程配合 setPointerCapture 可以保证在拖拽过程中即使指针移出画布事件依然能持续回调。画布交互的事件流大致是这样pointerdown 时判断命中目标如果点到了空白区域启动平移画布模式如果点到了图元启动拖拽节点模式。pointermove 中持续更新视觉位置同时把事件源坐标转换为世界坐标更新节点数据。pointerup 时结束拖拽做一次吸附对齐检测然后推入历史记录供撤销重做使用。这里的核心技巧是事件处理函数内做两级分发第一级判断交互模式平移/拖拽/连线/框选第二级选定具体操作对象。模式判断用对象映射表实现避免写一长串 if else 判分支后续扩展橡皮筋框选、多选等模式时会更省力。3.2 节点拖拽与对齐吸附拖拽节点看起来最简单但细节全在吸附上。所谓吸附就是当拖拽的节点边缘接近其他节点的边缘或画布中心线时自动把位置吸到对齐的位置上帮助用户画出整洁的图形。diagram-design 的吸附实现参考了常见图形编辑器的思路在拖拽过程中动态计算当前节点四条边与其他关键图元边界的距离如果某个距离小于阈值比如 8px就把位移修正到刚好对齐的数值。用生活化类比来解释这就像你在家里挪柜子柜子快靠墙时不用拿尺子量凭感觉对齐就能推平。吸附就是把这套手感数字化了。阈值太小吸附不明显阈值太大拖拽会感觉黏黏的用户体验反而差。实测下来8px~12px 是一个比较舒服的范围。还有一个细节是参考线渲染。拖拽过程中画一条淡淡的对齐线用户能直观看到自己吸附到了哪条边上。这个功能在白色背景上很容易做用一条低透明度的 dashed line 就行成本不高但观感提升非常明显。3.3 连线的创建与更新机制连线创建的交互流程我用文字描述一下用户从节点 A 的某个 port 上按住鼠标向外拖动此时临时连线实时跟随光标移动当光标移动到节点 B 的有效 port 上时port 高亮松手后一条正式的 Edge 生成并绑定到两个 port 上。这里的核心难点有两个第一个难点是命中检测。SVG 元素通常能看到但不一定能用事件直接判断光标是否落在 port 附近因为 port 本身可能只有几个像素大。diagram-design 的做法是用一个放大的不可见热区来替代感知每个 port 在交互层配一个半径为 12px 的圆形热区命中检测的目标是热区而不是那个小圆点。第二个难点是连线的路径计算。从 A 底部出发到 B 顶部的连线如果直接用直线两个节点叠在一起时会显得很乱diagram-design 默认使用贝塞尔曲线Auto自动模式下根据两个节点的相对位置自动调整贝塞尔控制点方向让连线自然地从出来的方向弯曲。进展到这一步时我顺手把连线标签支持加上了。连线中间可以插入文本标签比如HTTP 请求MQ 消息这类语义描述。在 SVG 中实现这个只需要在 path 上叠加一个 textPath好处是标签会沿着连线方向自动排版效果很趁手。4. 状态管理、序列化与多格式交付4.1 撤销重做的两种实现路径撤销重做可以简单分成两种策略快照式和命令式。快照式思想很朴素每次操作完把整个文档 JSON 存一份撤销时回退到上一个快照。优点是实现简单缺点是内存开销大、操作频繁时性能差。diagram-design 初期用快照式后来图元一多就发现内存占用节节攀升于是迁移到了命令式。命令式把每个用户操作包装成一个包含 execute 和 undo 方法的命令对象比如移动节点命令记录了节点 id、位移前后的坐标撤销时直接恢复坐标不需要保存整份文档。设计命令栈需要注意的一点是批处理。拖动节点应该算作一次操作但拖拽过程中 pointermove 会触发几十次移动事件如果每次移动都推一条命令撤销一次只能回退一步体验会很差。正确做法是在 pointerup 时把整段拖拽的位移打包成一条命令推入栈一次。4.2 文档模型的序列化设计diagram-design 的数据是纯 JSON 的这让它做序列化和版本管理非常轻松。项目内部统一用 version 字段标识 Schema 版本这样后续模型升级时可以写迁移函数把旧版本数据升级到新版本。序列化结构我前后整理过几轮最终采用的格式长这样{ version: 1.2, viewport: { offsetX: 0, offsetY: 0, scale: 1 }, nodes: [ /* 节点数组 */ ], edges: [ /* 连线数组 */ ], meta: { id: diagram_001, title: 订单系统架构图, createdAt: 2025-01-10T09:30:00Z, updatedAt: 2025-01-12T14:20:00Z } }连线数组里只需要存 source 和 target 的节点 id 与 port id几何路径在加载时重新计算根本不需要落盘。这个设计让数据文件体积更小还自然解决了引用了同一个 port的重复问题。在线编辑场景下这样的序列化结构非常合适配合增量保存或者自动保存用户的每次修改都能很快落盘。我在实际使用中发现只要序列化 stable后面的导入导出、协同编辑、版本对比全都能站在同一个地基上扩展这算是我在这个项目里收获最大的设计决策。4.3 导出 SVG 与 PNG两种格式各有脾气导出 SVG 其实是一个结构转换问题。因为 diagram-design 的图元是动态生成的 SVG 片段导出时只需要把节点和连线渲染成完整的字符串加上 xmlns 命名空间塞进 Blob 就能下载。这个方案干干净净放大不模糊还能被其他矢量工具编辑。导出 PNG 就没那么舒服了。浏览器不能直接把 SVG 字符串翻译成位图需要借助 canvas 做中间层。具体步骤是新建 Image 对象将 SVG 转成 data URL 赋给 img.src等图片加载完成后用 canvas 画出来最后调 canvas.toBlob 拿到 PNG 数据。这段逻辑有几个坑必须提前预警如果 SVG 里用了外部字体canvas 渲染时字体还没加载完导出图片就是缺字形的乱码。需要在导出前 await document.fonts.ready 确保字体加载完成。高清导出要设置 canvas 的宽高为 SVG 尺寸乘以一个倍率比如导出逻辑尺寸 800x600、倍率 2那么 canvas 就是 1600x1200这样缩放后才能保持边缘平滑。Safari 对 canvas 内绘制 SVG 的支持相对保守部分 CSS 类样式可能渲染不了。实测可行的方案是把样式内联到 SVG 元素属性里不要依赖外部 class。4.4 从外部 JSON 自动生成图元diagram-design 的价值当然不止手动画图数据驱动的自动生成本身就是一条很实用的扩展路线。项目里内置了一个紧凑的 DSL 语法可以通过 JSON 快速生成图元{ nodes: [ { id: n1, type: round-rect, x: 100, y: 100, attrs: { label: Nginx 入口 } }, { id: n2, type: round-rect, x: 350, y: 100, attrs: { label: 应用服务 } } ], edges: [ { id: e1, source: n1:p_bottom, target: n2:p_top, label: HTTP } ] }加载这种 JSON 后系统自动创建图元、自动计算连线的贝塞尔路径再配合自动布局算法做分层排列一个数据 - 图形的转换器就完成了。这个能力让我后面做接口文档可视化时省了非常大的力气基本就是拿接口定义生成流程框架再人工微调位置即可。5. 工程化落地与典型问题排查5.1 性能优化重绘、节流与脏检查SVG 渲染的编辑器在节点非常多时会卡顿处理思路要围绕减少重绘范围展开。diagram-design 的每个节点实例内部维护了一个 dirty 标记只有标记为 dirty 的节点才触发自身的属性更新靠 SVG 局部更新能力完成最小化重绘而不影响整张画布。拖拽过程中节点坐标变化频繁如果每帧都同步更新 DOM 属性会产生大量布局计算。实际做法是把节点 object 上的数据显示更新然后用 requestAnimationFrame 合并渲染当前帧内多次坐标修改只触发一次 DOM 写入let rafId null; function requestRender() { if (rafId) return; rafId requestAnimationFrame(() { rafId null; flushPendingChanges(); // 统一执行DOM更新 }); }这个收集更新、统一提交的模式在别的交互密集场景同样适用比盲目用 throttle 更高效。throttle 会固定节流间隔而 rAF 天然跟浏览器的帧率对齐不会出现该更新的时候被跳过去或者页面空闲还在执行定时任务的情况。5.2 常遇到的问题与排查实录这里我把测试过程中最常翻车的几个问题整理成表每个都附排查思路问题现象根因解决方案拖拽节点后连线没有跟着移动连线路径是静态缓存没有绑定 port 更新事件在节点 position 变更时触发 edge 的 reroute 方法缩放画布后点击位置总是偏事件坐标直接用客户坐标未转换到世界坐标使用 screenToWorld 转换监听事件的坐标导出 PNG 图片空白SVG 字符串缺少 xmlns 命名空间canvas 无法正确解析导出前给root 补 xmlnshttp://www.w3.org/2000/svg高 DPI 屏幕下图元模糊没有考虑 devicePixelRatiocanvas 或 SVG 的宽高乘上 dpr并用 transform: scale(1/dpr) 回正批量加载 1000 个节点性能暴跌每个节点创建大量 DOM且没做分帧渲染拆分为初始骨架 异步填充详情替换自动布局算法复杂度撤销重做把节点样式也改了命令栈只记录位置没有记录属性变化将样式变更也封装为命令对象入栈时保留旧值这里面最有价值的一条经验是任何事件处理器拿到的坐标都要先经过坐标系的统一转换再进入业务逻辑否则一旦画布支持缩放必然出坐标偏移的 bug。这个 bug 不是偶发而是必发只是早晚问题。5.3 实际踩过的坑关于坐标命中范围还有一个比较隐蔽的细节必须说。SVG 元素的事件命中区域默认是它的 fill 区域rect 有背景所以好命中但一条细细的直线比如连线就很难点击到。diagram-design 在每条 Edge 下方额外绘制一条隐形加宽路径透明度 0.01、stroke-width 设成 12px负责接收所有鼠标事件视觉上的细线反而只是装饰层。这个命中范围和视觉效果分离的思路在很多交互型项目中都值得参考。类似地节点里的小按钮如果太小也可以在外围包一层透明热区保证用户点击不至于落空。5.4 扩展弹性和后续想象空间做到这步diagram-design 已经具备了一个图形编辑器最核心的骨架。在此基础上后续扩展的方向非常多接入自动布局引擎运行拓扑布局算法对节点重新排列叠加 MiniMap 缩略图组件方便大画布快速导航结合分组和泳道让复杂的跨团队流程图也有结构化组织引入协同编辑把操作序列同步给其他协作者。这里的架构有一个隐藏优势文档模型是纯 JSON 的所有交互都能抽象为对文档模型的操作序列所以后续做协同编辑时把操作命令序列化后传给远端再做 apply 就行不需要额外设计数据结构。我在实际测试中发现预先设计好文档模型对整个项目的演进帮助远大于提前做花哨的 UI。数据模型稳得住上层功能加多少都不慌数据模型散乱哪怕按钮再多后期也是寸步难行。diagram-design 做下来我对先设计文档模型再谈功能有了更深的体会。如果你也想做一个类似的项目建议第一步先想清楚数据结构和坐标体系再去碰组件库、菜单栏、工具栏那些更表层的东西。图形编辑器这类项目表面上是画布在干活本质上全是数据模型在说话。