我最早开始动笔写 diagram-design 这个项目是因为一次特别憋屈的架构图绘制经历。那天我花了将近三个小时在一个通用绘图工具里一点点拖动节点、手动折线、反复调整箭头位置最后导出的图一放大就糊同事说你这线好多都没对齐。我盯着屏幕上歪歪扭扭的连接线突然意识到市面上大部分工具要么太重、要么太死真正适合开发者用来快速画架构图、流程图、拓扑图的东西居然没有一个能完全贴合我的习惯。于是就有了 diagram-design——一个以让开发者用代码和简单交互快速生成整洁图表为目标的个人项目最核心的诉求只有三个可编程、可交互、可导出。这篇文章不是给 diagram-design 做的宣传而是把我从零开始设计这个绘图工具时踩过的坑、想明白的原理、最终沉淀下来的实现思路完整梳理一遍。如果你正准备做类似的 diagram 工具或者想在项目里嵌入一个可视化编辑器那这篇应该能帮你省下不少试错时间。里面没有那种复制就能用的完整代码但会把关键设计决策和背后的为什么讲透你可以照着这个思路去搭自己的基础架构。1. 为什么会有 diagram-design从一次手绘架构图的无能狂怒说起1.1 现有工具让我抓狂的三个瞬间第一个瞬间是对齐。画三个服务框手动拖到屏幕上感觉差不多齐了可只要放大到 200%就能看到左边框和右边框差了那么一两个像素这对一个写代码出身的人来说简直像眼睛里进了沙子。第二个瞬间是连线的自动路由。画一条从 A 到 B 的线要跨过中间一个矩形节点工具默认给的直线直接穿过去我得手动添加好几个拐点拐点又粘不到网格上来回拖三十分钟。第三个瞬间是批量修改。架构图里改了某个模块的名字旁边关联的三条边备注全部要手动改改完还容易漏。这些痛点其实不是我不会用工具而是通用绘图软件的设计目标是自由画布可我需要的是一种半自动的图表生成器节点放置要有规则感连线要能自动避障数据变更后图要能跟着变。换句话说我需要的不只是一块画布更是一个有逻辑的图形引擎。1.2 决定自己写之后的第一轮需求清单决定动手之后我先给自己列了一个需求清单而不是直接打开编辑器写代码。我始终觉得绘图工具这种项目如果连自己要用什么功能都没想清楚很容易在渲染层打转几个月。最初定下来的核心功能是这样的节点矩形、圆角矩形、菱形、圆形支持自定义尺寸和颜色。连线直线、折线、曲线支持箭头样式支持在线上标文字。交互节点拖拽、画布平移缩放、多选、框选、对齐辅助线。数据导入导出一套简洁的 JSON 格式能完整还原图。自动布局至少支持树形结构和分层布局两种模式。这看起来和现成工具差不多但真正的区别在第四点。我希望 diagram-design 的图谱数据是活的——存在一个与渲染无关的纯数据模型里界面只是这个数据的投影。这样以后我想接代码生成、接口可视化、数据绑定都有地基。2. diagram-design 的地基数据模型和渲染层的拆分逻辑2.1 图数据模型节点、边、端口和画布我设计的数据模型没有上来就追求复杂而是参考了最常见的图结构定义只做了必要的扩充。最底层是Canvas它代表一张独立画布存自己的宽高、背景色、缩放比例。画布里装两类元素Node和Edge。一个Node除了 id、类型、位置、尺寸之外我额外加了一个东西叫ports也就是端口。端口是节点上用于连接线的锚点可以是上下左右四个方向也可以是任意自定义位置。为什么要单独抽象端口因为如果边直接连到节点边界上线的终点就会跟着节点边框位置变来变去当你需要精确控制这条线从右侧三分之一处引出时会非常痛苦。端口把连线锚点变成了可命名的对象拖拽的时候线的端点可以稳定吸附在端口上这是一个看着不起眼、实际大幅提升编辑体验的设计。Edge就更直接了它保存起点节点 id、终点节点 id、起点端口 id、终点端口 id剩下的路由路径全部由计算层去填。我坚持不让 Edge 数据里缓存全量的折线路径因为路径是派生的只要节点移动了就要重新算缓存反而容易带来不一致。另外我还给 Graph 对象维护了一个简单的索引根据节点 id 能立刻查到它关联的所有边。这个索引在后续做选中联动、删除节点时删边、自动布局权重计算时都特别有用。2.2 为什么渲染层不能碰业务数据很多绘图小项目写到最后变成一团乱麻根因就是渲染层直接操作数据鼠标拖一下节点DOM 元素的 style 被改掉然后再回头从 DOM 里读坐标去更新数据。这条路前期爽后期全是债。我在 diagram-design 里定了一条铁律渲染层只负责把模型渲染出来它不拥有数据也不产生数据。用户拖动节点交互层发出node-move事件事件里带着节点 id 和新的坐标位置然后由控制器去改写模型数据模型数据变更后再触发重绘。单向数据流听起来像是前端框架的老生常谈但放到绘图工具里同样成立。这样做的第一个好处是撤销重做非常好做。因为每一次修改都是对模型的显式操作我可以在模型层记录操作前后的状态。第二个好处是序列化变得简单存储时直接拿模型对象即可不需要从 DOM 反推。第三个好处是支持多端渲染我可以在浏览器里渲染成 SVG将来也能渲染成 Canvas甚至导出一份纯文本的 ASCII 图形语义都不变。2.3 序列化与撤销重做的支点序列化我是这么设计的一个图的 JSON 结构大概是{ version, canvas, nodes, edges }。每个节点除了几何信息还会塞一个data字段用来放业务自定义数据比如节点代表的服务名、负责人、描述。这样 diagram-design 就从一个纯画图工具往可视化建模工具方向迈了一步。撤销重做我第一版用了最笨但最稳妥的快照法每次用户操作结束时把整个图的数据快照压入历史栈。因为图的数据量不大几千个节点也就几 MBJSON.stringify 一次才十几毫秒完全能接受。后来发现性能瓶颈不在快照而在重绘。但那是后面踩坑的部分。快照法虽然简单粗暴但它天然支持任何操作类型不需要为每种操作编写逆向逻辑对于个人项目来说稳定性永远比炫技重要。3. 拖拽、缩放、连线交互层最难的三块硬骨头3.1 坐标系的坎屏幕坐标与画布坐标所有画图工具第一个坑都在坐标系转换。屏幕上的鼠标位置是相对浏览器视口的而我们需要的是相对画布内容的坐标。如果画布根本没有缩放和平移这两个值是一样的一旦加了缩放和平移矩阵直接拿鼠标 offsetX 去设置节点位置节点就会到处飞。我的做法是维护一个viewport对象里面存scale和offset。任何鼠标事件进来先用这个公式换算canvasX (screenX - offsetX) / scale canvasY (screenY - offsetY) / scale所有模型数据一律使用 canvas 坐标。渲染时在渲染层统一应用transform: scale(...) translate(...)这样模型层感知到的永远是一个稳定的世界。还有一个小细节缩放最好不要以画布原点为基准而是以鼠标所在位置为锚点否则缩放时会觉得内容在往角落跑。这个锚点缩放公式很简单但很多教程不讲确实容易做错。3.2 拖拽节点的命中测试与吸附拖拽第一个遇到的问题是命中测试。在 SVG 渲染下可以直接用事件目标的 id 映射到节点但如果节点上层有重叠元素比如选中框、装饰标签就要自己判断。我写了一个简单的命中检测函数先遍历所有节点画包围盒再用四叉树做空间索引优化。不过早期节点数量不超过五百个时线性遍历也够用索引是后来被性能逼出来的。拖拽过程中最大的体验问题是吸附对齐。如果只让节点跟随鼠标你会发现很难把两个节点边界精确对齐。我在拖拽时动态计算目标节点和附近候选节点的水平中心线、垂直中心线、左右边界、上下边界如果当前节点的对应边距离这些参考线小于某个阈值默认 5px就强制把位置修正到线上同时渲染出一条辅助线。这个逻辑不复杂但很吃候选节点的筛选策略一开始我全量遍历节点多了会有卡顿后来改成只检查视口内最靠近的十几个节点瞬间顺畅。3.3 连线时的折线计算与实时预览连线交互我设计成两个阶段先从一个节点的端口拖出绘制一条跟随鼠标的临时预览线然后松手检测终点是否落到了另一个节点的某个端口上如果有效就正式生成一条边否则取消预览。预览线用最简单的方式一根直线过渡到折线。等正式生成边之后再调用路由计算器算出这条折线的最佳路径。我的路由算法没有上来就上复杂的 A* 寻路而是先用了一个非常工程化的方案确定起点方向确定终点方向然后根据两个点之间的相对位置产生 2 到 4 个拐点。举个例子如果起点的端口在右侧终点的端口在左侧那么这条线先水平向右走一段固定长度再垂直走到与终点对齐的水平线再水平向左到达终点。这个世界坐标路径说起来简单但实现时要注意一个关键点拐点坐标不能和节点包围盒重合否则线会穿过节点。我给每条路径加上了一个叫directionHint的东西记录每条线段的方向然后在生成路径时考虑节点宽度预留出避让距离。4. 让图变得整齐自动布局与智能对齐的实现思路4.1 分层布局树形图、分层图与网格布局diagram-design 的自动布局模块最早是为了解决从代码生成图表这个场景。用户导入一份 JSON 描述工具自动把节点排布好不需要手动拖拽。第一版我实现了树形布局用在组织架构图上。树形布局的核心是确定同一层节点在垂直方向上的位置。我采用的算法思路是递归后序遍历先计算所有子树的宽度然后父节点放在子树的中心位置每一层 y 坐标递推。这个逻辑在纯树上跑得很好但遇到任意图就失灵了因为存在环。后来我加了分层布局专门处理有向无环图。思路分三步先用拓扑排序给每个节点分配一个层级再按层级分组最后在同一层内做顺序优化尽量让边交叉数量最小。交叉最小化没有完美解我用了 biconnected 分割配合贪心启发式虽然不能保证最优但在节点数少于两百时看起来已经比手动拖拽整齐多了。网格布局就是给任意图兜底的把所有节点按行排列固定行高列宽适合快速预览谈不上美观但胜在永不重叠。4.2 对齐线、等距排列和边缘检测的权衡自动选择了布局后手动微调阶段的智能对齐才是日常体验的决定因素。对齐线帮用户把节点边界对齐但等距排列是我后来补上的。有一阵子我发现用户总是把三个节点的间距调成接近相等但要手抖半天于是我在多选拖拽时加了等距提示当三个以上节点在水平方向上的间距都接近某个平均值时显示一组等距虚线用户按下快捷键即可自动均分。边缘检测则是对齐之外的一个补充当节点被拖出画布边界时自动阻止或提示。我选择的是软边界策略允许拖出但画布边缘会出现红色指示条松开时如果节点中心在画布外就自动把它拉回来。这个策略比硬性限制更容易让用户接受因为硬限制会阻断连续拖拽的操作节奏。4.3 从能用到好用智能粘贴与自动避让复制粘贴这种基础功能在绘图工具里也有大学问。第一版我按普通编辑器的方式复制节点时只拷贝节点本身粘贴到画布中心结果原图旁边新图混在一起用户根本分不清哪些是新贴的。后来我改成这样复制时记录所有选中节点的相对位置关系粘贴时生成新的节点 id整体偏移一个默认距离并确保偏移后所有节点依然落在画布可视范围内。更重要的是如果粘贴位置的区域已经被其他节点覆盖需要自动寻找一个不重叠的落点。我写了一个简单的扫描算法从目标点开始向右下方向做螺旋搜索找到第一个能容纳整个选择集的空白区域。这个功能虽然小但对用户体验的提升非常明显。5. 性能优化和撤销重做上线前差点翻车的两个坑5.1 重绘风暴节流、脏矩形和增量更新diagram-design 我一开始选用 SVG 渲染因为 DOM 节点天然支持事件绑定用起来省心。但 SVG 的弱点在于节点多了以后重绘性能会迅速劣化。当我把测试图加到一千个节点时拖动一次画布整个界面就像掉进泥潭帧率直接掉到十几。第一次优化是消除无效重绘。我观察到一个问题每次拖动某个节点我把整个图全部重新渲染了。但事实上只有被拖的节点位置变了其余九百九十九个节点都没变。于是我实现了脏区域机制每次模型变化时收集受影响的最小矩形范围重绘时只更新这个范围内的 DOM 节点。由于 SVG 支持对单个元素改属性我直接只更新那个被拖节点的 transform避开了全量刷新。第二次优化是给平移缩放做节流。平移画布时每一帧都在改变视口如果每次都触发全量重绘检查点就全费了。我把渲染请求放到 requestAnimationFrame 里合并保证一帧最多渲染一次。这样改完之后两千个节点在平移缩放时也能保持基本流畅。5.2 撤销栈的设计全量快照与操作记录之争前面提到我用了快照法但实际实现时还是踩了一个坑如果每拖拽一个像素就压一个快照历史栈会爆炸。我的解决办法是引入操作批处理。一次完整的拖拽从 mousedown 到 mouseup 算一个操作在这个操作周期内所有中间状态只缓存最新的临时快照等鼠标释放时才真正提交一个快照入栈。这个做法的妙处在于内存占用能被肉眼控制。拖一个星期操作记录可能也就上千条每条快照最多几兆普通页面完全扛得住。还有一个小细节撤销后需要恢复的不只是数据还有视图的滚动位置和缩放比例。我在快照里把视口信息也存进去用户撤销后才不会出现数据变了但屏幕还在老地方的错乱。5.3 一次内存泄漏的排查过程上线前我跑了长时间的加载测试发现打开一个图然后反复增删节点页面内存占用只涨不降。一开始怀疑是事件监听器泄漏检查了一遍又一遍没有发现。后来才定位到问题SVG 元素删除后浏览器会在元素上挂载的一些自定义属性形成的闭包引用没有被释放尤其是在节点的自定义 data 字段里存了较大对象时内存不会被自动回收。解决方案也很粗暴删除节点时先把节点上的业务数据置空再从父容器移除 DOM 元素最后手动把元素引用设置为 null。同时我在浏览器提供的 performance API 里加了内存监控超过阈值时打印可疑对象列表。从那以后长时间操作内存曲线终于平稳了。6. 如果让我重新做一次 diagram-design我会在这些地方提前动手6.1 插件系统应该从第一版就考虑第一版 diagram-design 的功能边界是锁死的所有布局算法、节点样式、导出格式都写死在核心代码里。等有人跟我说我想加一个泳道图布局的时候我发现要动核心模块的不少代码风险很大。如果重新来我会在第一版就预留插件机制定义好节点类型注册表、布局算法注册表、导出器注册表。核心只做模型和渲染其他都通过插件形式扩展。这不难实现只要在初始化时提供一个注册函数把插件挂到一个 store 上即可。早做和晚做的成本差异巨大越晚重构越痛苦。6.2 导出的边界图片、PDF还是可编辑格式很多人画完图第一件事是导出。我在 diagram-design 里一开始只支持导出 JSON 文件结果被反馈没有图片不能发群。后来加了 SVG 导出又加了 PNG 导出。PNG 在导出大图时特别容易糊需要把临时画布放大数倍再缩回来这里有个细节svg 里的文字在转 canvas 渲染时浏览器对标准字体和自定义字体的处理不一样有时会出现文字偏移或者丢失。我最后是用逐行解析 SVG 里的 text 元素手动在 canvas 里重绘文字才彻底解决。如果让我重来我会把导出抽象成一个管道先有一个渲染后端把图渲染成一份中间格式再分别从中间格式产出 SVG、PNG、PDF。这样每个导出器只负责格式转换不重复实现把模型画成图形的逻辑。6.3 给准备入坑的同类项目开发者的建议做绘图工具最需要耐心的不是图形算法而是交互细节的海量堆积。一个对齐线做出来了还有吸附阈值要调吸附调好了又要考虑两个节点重合时怎么处理。这些细节没有定论只能靠你自己在真实使用场景里不断打磨。我的建议是先用最小的模型把核心链路跑通——建模、渲染、拖拽、保存、导出然后再开始堆功能。很多人一上来就研究最复杂的自动布线结果基础交互一塌糊涂最后用户连一个节点都拖不利索。diagram-design 这个项目让我最大的收获不是写出多少行代码而是明白了克制设计的重要性关注核心路径冗余功能能砍就砍等真有人用到了再说。如果你也在做类似的东西欢迎把我这套架构思路拿去借鉴。数据模型和渲染层分离、操作批处理、脏矩形重绘这几板斧并不神秘但每一样都是我用一次次卡死、一次次数据丢失换来的。把这些地基打扎实剩下的功能只是在这个骨架上不断添肉而已。
