diagram-design这个项目名乍一看以为是某个设计资源仓库但它实际承担的是一套在线图表设计核心库的角色。简单说就是把我们在文档里画流程图、架构图、时序图的那套体验从静态图片升级成可交互、可协作、可二次编辑的在线画布系统。这篇文章我会以整套系统的落地为主线从数据模型、画布渲染、交互设计到多人在线协同完整梳理一遍实现路径和取舍理由。如果你正打算做类似的绘图工具或需要在自己的产品里嵌入一块可编辑的画布模块这篇内容应该能帮你少走不少弯路。1. 项目定位与核心设计思路1.1 这个项目到底在解决什么问题很多团队一开始都会遇到同一个痛点文档里的架构图、时序图、流程图散落在一堆图片文件里改一次需求就要重新画一遍版本管理根本无从谈起。diagram-design的定位就是把这些图的生成和编辑过程收编到一个统一系统里让图变成一种可以持续维护的资产而不是一次性导出的图片。和直接使用现成的商业绘图工具相比自研这类画布核心有一个很现实的好处可以深度定制。我们团队当时的业务场景需要大量带有自定义图形、特殊连线规则和字段映射关系的图通用工具在这些场景下要么不支持要么需要昂贵的插件。从零做一个轻量级画布核心虽然前期投入大但后期适配成本低而且数据全部沉淀在自己手里能直接和业务数据结构打通。项目的核心使用场景有三个一是架构师画技术架构图并分享评审二是产品经理快速产出业务流程图三是运维同学用它做服务器拓扑可视化。三种场景都需要鼠标拖拽、缩放画布、连线自动吸附这些基础能力也都会遇到同一类问题节点多起来的渲染性能以及多人同时编辑时的数据冲突。1.2 核心设计画布模型选型这是整个项目第一个分歧点也是决定后续所有功能复杂度的地方。业界主流的画布实现方案无非三种SVG、Canvas、DOM绝对定位。我直接把三个方案都拉出来做了对比测试。SVG是直觉上最合适的方案因为每个节点都是一个独立的DOM元素事件绑定、光标样式、悬浮提示全都天然支持尤其是做类似“鼠标悬停节点高亮相邻连线”这种交互代码量极少。但SVG有一个致命问题节点数量上去以后DOM节点数量跟着膨胀几百个节点加上连线、label、锚点渲染线程很快就会被拖垮。Canvas的性能上限高得多几千个节点能稳定跑在60帧附近但它把“元素拾取”这件事变得很痛苦Canvas上鼠标点击命中的是一个像素点必须自己用几何计算去判断点到了哪个矩形或曲线。图形本身是画出来的没有DOM事件可依赖选中、拖拽、右键菜单全都要手写。DOM绝对定位的方案最朴素每个节点是一个div直接把节点映射到业务组件上定制性强到令人发指。但它和SVG一样有DOM数量问题而且没有现成的图元能力线条要自己用div拼接或用SVG辅助拐角、曲线会做得非常别扭。我们最终采用的是混合方案节点用SVG实现超大规模场景下切换Canvas渲染模式整体是一个可切换渲染后端的体系。这个设计听起来有点重但实际是兼顾交互开发效率和性能的最优解。常规业务图二三十个节点SVG模式足够顺滑能用最成熟的DOM事件体系快速开发交互一旦遇到上千节点的大图就降级到Canvas自绘模式保证至少能打开、能缩放、能整体查看。1.3 数据模型设计一张图的骨架无论底层渲染用什么方案图的数据模型都是共通的。一张图的基本组成是一个有向图结构节点集合、边集合、画布级配置。节点是一个矩形区域有坐标、宽高、样式、业务数据字段边是一条连接线有起点节点ID、终点节点ID、路由路径点集、样式和label信息。{ canvas: { id: board-001, width: 3000, height: 2000, zoom: 1.0, offsetX: 0, offsetY: 0, background: #ffffff }, nodes: [ { id: node-01, type: rect, x: 120, y: 180, width: 160, height: 56, attrs: { fill: #4f6ef7, stroke: #2a3fa8, label: 认证服务 }, data: { bizId: 1001, status: running } } ], edges: [ { id: edge-01, source: node-01, target: node-02, router: orth, points: [{x: 280, y: 208}, {x: 420, y: 208}], label: REST API } ] }这个结构里有一个很重要的设计决策边上的points是路由计算后的结果缓存而不是实时计算。因为图一旦大起来每次拖动节点都实时重算全网线段的路径代价非常大。我们的做法是拖动过程中先用一条临时直线表示连线松手后再重新计算该节点关联边的完整路径。这样既保证了视觉连续性又控制住了计算量。坐标体系还有一个容易踩坑的点一定要区分“画布坐标”和“屏幕坐标”。画布坐标是节点在无限画布上的真实坐标屏幕坐标是乘上了缩放倍数、加上了平移偏移之后显示在浏览器视口里的坐标。所有鼠标事件拿到的都是屏幕坐标必须先反解成画布坐标才能用来做命中检测。这个换算如果做错了缩放后拖拽节点就会出现经典的手势漂移问题——鼠标已经移开了节点还在原地缓步追。2. 图元与交互图表编辑器的灵魂2.1 节点、图层与区域管理数据模型定了之后真正开始写编辑器时就会遇到新的复杂度节点上的每一项操作都要有“可撤销”能力。比如用户拖了节点、改了颜色、删了一条线CtrlZ要能一步步回退。这个机制和业务状态管理很容易耦合出一堆bug核心做法是把所有修改操作都走统一指令通道而不是直接改数据对象。我们实现指令模式时定义了一个基础结构Command包含执行函数和回退执行函数。移动节点的指令会记录节点ID 移动前后的坐标删除边的指令会记录完整的边数据对象这样回退时就能精确恢复。整个编辑过程其实是一棵指令树的线性延伸每一步操作都对应一条记录。图层的概念同样不可或缺。在绘图工具里图层决定了元素之间的上下遮挡顺序。但我们没有做成后台软件那种一个图层一个条目的管理界面而是简化成二维平面上的z-index序号。节点被选中时自动提到最上层取消选中后如果用户没有手动调整过层级就恢复到原来的顺序。这个妥协让交互变得轻量用户不需要理解“图层”这个专业概念同时满足了绝大多数绘图场景。区域管理方面画布是一个无限坐标系空间理论上可以往任意方向延展。但我们引入了“画布范围”的概念让用户可以选择卡片式画布或者无限画布两种模式。卡片式画布适合导出图片的场景无限画布适合脑暴、梳理关系网的场景。模式切换只是修改了画布容器的边界行为数据模型完全不变。2.2 连线的锚点与路由计算连线是绘图工具里复杂度最高的子系统没有之一。首先每个节点要对外提供连接点也就是锚点。锚点数量太少会限制连线位置太多会让用户选择困难。最终我们采用的是相对定位锚点机制——矩形的四边中点各有一个默认锚点同时支持用户自定义百分比锚点位置比如在矩形顶部30%处加一个点。连接行为本身可以拆成两步拖拽连线时的寻路以及释放连接时的目标判定。寻路最朴素的做法是直线但直线穿过其他节点时视觉上非常混乱。所以我们实现了两种路径策略正交折线orthogonal和贝塞尔曲线。正交折线更接近架构图的经典观感贝塞尔曲线则更适合表达依赖关系的柔和过渡。正交路由的计算没有用网线全连接的A*算法因为性能代价太高。我们用的是基于包围盒的简化寻路先判断起点和终点是否处于水平或垂直对齐状态能够直接走一条直线就优先走直线不行就生成L型或Z型的中间拐点拐点做一次简单的障碍规避检测。这套启发式路由在高覆盖的常见场景下准确率超过85%剩下15%交给用户手动调节拐点位置。交互上按住拖动拐点可以微调路径点微调结果会覆盖自动路由结果。2.3 用户交互的细节打磨画布交互的细节密度远远超出预期每一个都能单独写一篇分享。这里挑几个最影响手感的讲。第一个是框选。用户按住空白区域拖出一个矩形框矩形内部和相交的节点要同时进入选中状态。判定相交用的是矩形碰撞检测一个节点只要有部分区域进入框选范围就被选中。这个判定规则不同工具有不同做法有的严格要求完全包含有的允许相交选中。实测下来“相交即选中”的容错率更高用户不会因为节点边角差了一个像素而莫名选不中。第二个是吸附。节点拖到另一个节点附近时如果两者的边缘距离小于8像素就自动对齐到相同边缘或中心。吸附算法本质上是对坐标做了量化四舍五入但如果不施加“吸附力”的视觉反馈用户会感觉节点被卡住了。所以吸附触发时节点颜色要轻微高亮并且按Shift键要能临时关闭吸附。这个功能在绘制对齐要求高的架构图时几乎离不开。第三个是缩放。其实缩放不是直接对整体坐标做缩放而是对“视口”做缩放。画布的缩放系数改变时节点坐标并不变只是视口矩阵变换改变了最终投影效果。这里面有个惯用手法叫“以鼠标位置为缩放中心”鼠标指向哪里缩放时就以哪里的坐标点作为保持不动的位置。实现方式是记录缩放前鼠标画布坐标缩放后重新计算视口偏移量让同一个画布坐标点仍然落在鼠标下方。3. 多人实时协同从单机编辑到云端协作3.1 协同模型选型与原因diagram-design系统最硬核的部分是多人实时协同。一张图表被多个成员同时打开编辑A同学拖动了一个节点B同学在同一时刻改了节点文字两个人的修改必须可靠地合并并且最终收敛到所有人都一致的状态。协同算法的主要路线有两条CRDT和OT。CRDT在纯文本协同场景已经非常成熟基于操作交换和状态合并天然支持多端并发不需要中心服务器做权威裁决。但它对数据结构的要求比较高需要把节点、边这些图元拆成可交换的底层数据结构像“把节点A的x坐标加10”这类操作在CRDT模型里要表达为一棵共享树的路径更新。OT算法则是以“操作变换”为核心每个客户端把本地操作发给服务器服务器通过转换函数把并发操作变成可顺序执行的操作序列。OT的问题是转换函数容易写错尤其在复合操作面前处理不好会造成不可恢复的状态分叉。我们最终走的是混合路线整体上采用OT的通道模型但把操作粒度缩小到“图元级单字段”级别。比如移动节点被拆成改x、改y两个操作修改节点文字就是一个单独的setLabel操作。操作粒度越细冲突面越小需要写变换函数的地方就越少。实际操作中95%的并发冲突都是不同字段的修改天然不会冲突剩下5%的同字段冲突才需要走一轮变换和覆盖策略。3.2 增量操作数据结构协同数据通道的数据结构直接决定了服务器端的合并复杂度。我们定义了一个标准操作帧{ opId: uuid-xxx, docId: board-001, seq: 1024, userId: user-01, type: setNodeAttr, payload: { nodeId: node-01, attr: x, value: 320 }, baseSeq: 1018, timestamp: 1690000000000 }这里的baseSeq是操作所基于的服务端版本号服务器收到操作后会校验它是否是基于最新版本的。如果当前版本号大于baseSeq说明这段时间里已经有别人提交过操作需要做变换或合并处理。seq是客户端期望的服务端分配序号用于最终排序和乱序识别。所有操作都会先进入服务端的操作日志经过合法性和冲突校验后以广播形式推送到其他在线客户端。新用户打开文档时服务端会先发送一份全量快照再告知其当前版本号之后只发送增量操作。快照加增量的组合机制让新用户打开大文档的加载时间控制在秒级。3.3 冲突解决与体验取舍同字段冲突的解决策略有一个体验上的权衡问题。两个用户同时移动同一个节点最后应该听谁的技术上我们采用了“后写优先”的简单策略因为绘图工具里没有编辑冲突必须保留双方内容的需求移动操作本身就是覆盖性的后写的操作自然覆盖先写的操作。真正麻烦的是“同字段并发覆盖”和“文字编辑冲突”的组合。比如A同学在编辑一个节点的labelB同学同时在拖动这个节点。label修改和坐标修改是不同字段完全不需要冲突处理。但如果A同学和B同学同时修改同一个label字段保留后写操作会让其中一个同学的内容丢失。我们的妥协方案是保留后写操作但给被覆盖的用户弹一次轻提示告诉他“内容被他人更新”允许他通过CtrlZ撤销到自己的版本。这个设计避免了复杂的合并算法用户体验也说得过去。协同场景下还有一个隐藏问题远端操作导致的状态变更要不要进入本地的撤销栈答案是不要。本地撤销栈应该只包含本端用户自己的操作。远端操作直接应用到画布数据后不应该污染本地用户的Undo历史。实现上需要为每个操作打上来源标记applySource为remote时跳过指令栈记录。3.4 权限与可见性控制多人协作不只是数据层面的同步权限模型同样重要。文档被分成只读、可编辑、可管理三个级别。只读用户能看到画布和元素但无法修改可编辑用户可以修改节点和连线但无法删除整张画布可管理用户拥有全部权限包括分享链接、归档文档、删除画布。权限校验在客户端做了第一层拦截服务端依然做了完整校验。客户端拦截是为了更好的交互反馈——当前用户不可编辑时进入画布后光标变成默认指针拖拽节点直接无效服务端校验是为了防止恶意绕过前端发请求。可见性控制则更精细一些。大团队合作时有些节点可能涉及敏感信息只对特定角色可见。这个功能的实现方式是节点上挂了visibilityScope字段服务端推给客户端的数据会根据用户所属角色做过滤。某个节点的可见范围不含当前用户时客户端拿到的数据里直接不包含该节点这样就避免了前端显示后再隐藏带来的闪烁问题。4. 工程落地导出、性能、常见问题4.1 文件导出与序列化diagram-design系统的导出功能分了三条路导出为图片、导出为SVG、导出为JSON项目文件。导出为图片用的是Canvas合成方案——把所有节点的SVG样式收集起来用Canvas重绘一遍再调用canvas.toDataURL(image/png)生成图片下载。这里有一个常见的坑Canvas重绘时如果节点引用了外部图片资源跨域请求会把画布污染掉导致导出结果是空白图。解决方式是提前加载图片并转成base64格式内嵌同时将canvas.crossOrigin设为空。SVG导出走的是序列化路线。我们维护了一个统一的图元渲染函数渲染到屏幕时和导出SVG时用的是同一套逻辑只是导出时不渲染滚动条和辅助线。好处是导出的SVG编辑时看到什么就是什么不会有偏差。JSON导出则是项目的全量数据快照包括画布配置、节点列表、边列表、版本号外加一个diagram-design.schemaVersion字段。这个字段决定了旧版本数据能否被新版本兼容读取每次数据模型变更都会递增这个版本号并写一份迁移函数。工程上不写迁移函数的话线上数据格式一调整旧文档大面积打不开的场景一定会发生。4.2 性能优化渲染、裁剪、合并性能优化是这个项目花时间最长的部分。我们完整踩过从“小图流畅”到“大图卡顿”的整个性能梯度最终沉淀出三条有效的优化策略。第一条是视口裁剪。画布很大但用户一次只能看到其中一小部分所以渲染时只绘制视口范围内的节点和边。视口范围是当前屏幕坐标反解后得到的画布坐标矩形判断节点是否在矩形内用矩形相交检测即可。裁剪逻辑写好后1000个节点的图在视口内一般只有五六十个节点渲染压力骤减。第二条是渲染合并。当大量节点同时移动时每个节点独立更新位置会触发布局抖动。常规做法是把移动过程放到requestAnimationFrame里收集一帧内的所有变换以批量方式统一更新DOM样式。对于SVG模式合并更新的单位是整条连线路径而不是单一的D点坐标。第三条是GC友好。图数据是结构化的对象操作频繁时会产生大量临时对象例如路径点数组、折线计算矩阵、命中检测的包围盒对象。这些临时对象积攒多了会频繁触发垃圾回收表现为操作一阵子后突然掉帧。我们做了一个简单的对象池复用机制提前申请一组包围盒对象每次计算重用而不是新建。4.3 常见问题与排查速查表开发过程中积累了不少问题排查经验整理成一张速查表遇到的很多问题都能直接对上号。问题现象根因分析解决方案缩放后鼠标拖拽漂移屏幕坐标转画布坐标公式错误检查zoom变换是否在平移变换之前叠加导出图片缺字体浏览器字体没加载完就执行了绘制导出前调用document.fonts.ready等待字体加载节点多了之后拖动发卡拖拽时高频实时更新所有关联边先临时直线松开后再进入路由计算协同编辑后部分节点消失操作冲突后本地状态被错误覆盖检查远端操作的baseSeq和本地版本号是否对齐框选不中区域内的节点命中检测用了屏幕坐标但节点是画布坐标统一全部换算到画布坐标后再做碰撞右键菜单在Canvas模式下定位不准Canvas模式缺少DOM坐标对应关系挂一个隐藏DOM层用于记录菜单坐标这里面最值得说的是第一条缩放漂移问题。正确公式是先算画布坐标时要把鼠标相对于画布容器的像素位置除以缩放系数再加上视口偏移的倒数。顺序反了的话缩放越大漂移越明显这也是新手做画布系统最容易遇到的问题。4.4 复盘与二次迭代建议diagram-design系统迭代到比较稳定的阶段后我复盘了整个技术路径。如果让我重新做一次有几个决策会调整一是底层渲染可以更早抽象出统一的插件机制而不是让业务方直接改核心代码二是协同操作变更日志需要从一开始就考虑持久化到文件系统否则追溯时就只能靠内存里的日志三是初始阶段就要把权限体系接入统一身份服务不要等协同做完才补。后续如果在这个系统上继续扩展优先级最高的是三个方向。第一个是更多的图形类型库比如UML类图、ER图、泳道图的一键生成第二个是AI辅助排版的接入根据当前画布元素密度自动调整布局第三个是嵌入场景的插件化SDK让其他业务系统能一键把diagram-design嵌入自己的界面里而不是被硬编码死。如果让我从一个更大的视角看这类项目我会说画布工具的本质不只是画图它其实是在搭建一种结构化的思维表达框架。你给它的数据模型有多强大用户能在上面描绘的复杂关系就有多丰富。这个系统的价值不在于某个节点拖得有多顺畅而在于它让那些原本只存在于文档文字里的逻辑关系变成了一种可以反复推敲、协作演进的活资产。最后分享一个小细节如果团队里第一次做图形化编辑器一定要预留时间啃交互细节。数据模型、渲染方案顶多占三成工作量剩下七成都花在参数对齐、坐标换算、命中容错这些无声的角落。把交互细节打磨好了产品交付后的维护成本能低一半以上。
diagram-design这个项目名乍一看以为是某个设计资源仓库但它实际承担的是一套在线图表设计核心库的角色。简单说就是把我们在文档里画流程图、架构图、时序图的那套体验从静态图片升级成可交互、可协作、可二次编辑的在线画布系统。这篇文章我会以整套系统的落地为主线从数据模型、画布渲染、交互设计到多人在线协同完整梳理一遍实现路径和取舍理由。如果你正打算做类似的绘图工具或需要在自己的产品里嵌入一块可编辑的画布模块这篇内容应该能帮你少走不少弯路。1. 项目定位与核心设计思路1.1 这个项目到底在解决什么问题很多团队一开始都会遇到同一个痛点文档里的架构图、时序图、流程图散落在一堆图片文件里改一次需求就要重新画一遍版本管理根本无从谈起。diagram-design的定位就是把这些图的生成和编辑过程收编到一个统一系统里让图变成一种可以持续维护的资产而不是一次性导出的图片。和直接使用现成的商业绘图工具相比自研这类画布核心有一个很现实的好处可以深度定制。我们团队当时的业务场景需要大量带有自定义图形、特殊连线规则和字段映射关系的图通用工具在这些场景下要么不支持要么需要昂贵的插件。从零做一个轻量级画布核心虽然前期投入大但后期适配成本低而且数据全部沉淀在自己手里能直接和业务数据结构打通。项目的核心使用场景有三个一是架构师画技术架构图并分享评审二是产品经理快速产出业务流程图三是运维同学用它做服务器拓扑可视化。三种场景都需要鼠标拖拽、缩放画布、连线自动吸附这些基础能力也都会遇到同一类问题节点多起来的渲染性能以及多人同时编辑时的数据冲突。1.2 核心设计画布模型选型这是整个项目第一个分歧点也是决定后续所有功能复杂度的地方。业界主流的画布实现方案无非三种SVG、Canvas、DOM绝对定位。我直接把三个方案都拉出来做了对比测试。SVG是直觉上最合适的方案因为每个节点都是一个独立的DOM元素事件绑定、光标样式、悬浮提示全都天然支持尤其是做类似“鼠标悬停节点高亮相邻连线”这种交互代码量极少。但SVG有一个致命问题节点数量上去以后DOM节点数量跟着膨胀几百个节点加上连线、label、锚点渲染线程很快就会被拖垮。Canvas的性能上限高得多几千个节点能稳定跑在60帧附近但它把“元素拾取”这件事变得很痛苦Canvas上鼠标点击命中的是一个像素点必须自己用几何计算去判断点到了哪个矩形或曲线。图形本身是画出来的没有DOM事件可依赖选中、拖拽、右键菜单全都要手写。DOM绝对定位的方案最朴素每个节点是一个div直接把节点映射到业务组件上定制性强到令人发指。但它和SVG一样有DOM数量问题而且没有现成的图元能力线条要自己用div拼接或用SVG辅助拐角、曲线会做得非常别扭。我们最终采用的是混合方案节点用SVG实现超大规模场景下切换Canvas渲染模式整体是一个可切换渲染后端的体系。这个设计听起来有点重但实际是兼顾交互开发效率和性能的最优解。常规业务图二三十个节点SVG模式足够顺滑能用最成熟的DOM事件体系快速开发交互一旦遇到上千节点的大图就降级到Canvas自绘模式保证至少能打开、能缩放、能整体查看。1.3 数据模型设计一张图的骨架无论底层渲染用什么方案图的数据模型都是共通的。一张图的基本组成是一个有向图结构节点集合、边集合、画布级配置。节点是一个矩形区域有坐标、宽高、样式、业务数据字段边是一条连接线有起点节点ID、终点节点ID、路由路径点集、样式和label信息。{ canvas: { id: board-001, width: 3000, height: 2000, zoom: 1.0, offsetX: 0, offsetY: 0, background: #ffffff }, nodes: [ { id: node-01, type: rect, x: 120, y: 180, width: 160, height: 56, attrs: { fill: #4f6ef7, stroke: #2a3fa8, label: 认证服务 }, data: { bizId: 1001, status: running } } ], edges: [ { id: edge-01, source: node-01, target: node-02, router: orth, points: [{x: 280, y: 208}, {x: 420, y: 208}], label: REST API } ] }这个结构里有一个很重要的设计决策边上的points是路由计算后的结果缓存而不是实时计算。因为图一旦大起来每次拖动节点都实时重算全网线段的路径代价非常大。我们的做法是拖动过程中先用一条临时直线表示连线松手后再重新计算该节点关联边的完整路径。这样既保证了视觉连续性又控制住了计算量。坐标体系还有一个容易踩坑的点一定要区分“画布坐标”和“屏幕坐标”。画布坐标是节点在无限画布上的真实坐标屏幕坐标是乘上了缩放倍数、加上了平移偏移之后显示在浏览器视口里的坐标。所有鼠标事件拿到的都是屏幕坐标必须先反解成画布坐标才能用来做命中检测。这个换算如果做错了缩放后拖拽节点就会出现经典的手势漂移问题——鼠标已经移开了节点还在原地缓步追。2. 图元与交互图表编辑器的灵魂2.1 节点、图层与区域管理数据模型定了之后真正开始写编辑器时就会遇到新的复杂度节点上的每一项操作都要有“可撤销”能力。比如用户拖了节点、改了颜色、删了一条线CtrlZ要能一步步回退。这个机制和业务状态管理很容易耦合出一堆bug核心做法是把所有修改操作都走统一指令通道而不是直接改数据对象。我们实现指令模式时定义了一个基础结构Command包含执行函数和回退执行函数。移动节点的指令会记录节点ID 移动前后的坐标删除边的指令会记录完整的边数据对象这样回退时就能精确恢复。整个编辑过程其实是一棵指令树的线性延伸每一步操作都对应一条记录。图层的概念同样不可或缺。在绘图工具里图层决定了元素之间的上下遮挡顺序。但我们没有做成后台软件那种一个图层一个条目的管理界面而是简化成二维平面上的z-index序号。节点被选中时自动提到最上层取消选中后如果用户没有手动调整过层级就恢复到原来的顺序。这个妥协让交互变得轻量用户不需要理解“图层”这个专业概念同时满足了绝大多数绘图场景。区域管理方面画布是一个无限坐标系空间理论上可以往任意方向延展。但我们引入了“画布范围”的概念让用户可以选择卡片式画布或者无限画布两种模式。卡片式画布适合导出图片的场景无限画布适合脑暴、梳理关系网的场景。模式切换只是修改了画布容器的边界行为数据模型完全不变。2.2 连线的锚点与路由计算连线是绘图工具里复杂度最高的子系统没有之一。首先每个节点要对外提供连接点也就是锚点。锚点数量太少会限制连线位置太多会让用户选择困难。最终我们采用的是相对定位锚点机制——矩形的四边中点各有一个默认锚点同时支持用户自定义百分比锚点位置比如在矩形顶部30%处加一个点。连接行为本身可以拆成两步拖拽连线时的寻路以及释放连接时的目标判定。寻路最朴素的做法是直线但直线穿过其他节点时视觉上非常混乱。所以我们实现了两种路径策略正交折线orthogonal和贝塞尔曲线。正交折线更接近架构图的经典观感贝塞尔曲线则更适合表达依赖关系的柔和过渡。正交路由的计算没有用网线全连接的A*算法因为性能代价太高。我们用的是基于包围盒的简化寻路先判断起点和终点是否处于水平或垂直对齐状态能够直接走一条直线就优先走直线不行就生成L型或Z型的中间拐点拐点做一次简单的障碍规避检测。这套启发式路由在高覆盖的常见场景下准确率超过85%剩下15%交给用户手动调节拐点位置。交互上按住拖动拐点可以微调路径点微调结果会覆盖自动路由结果。2.3 用户交互的细节打磨画布交互的细节密度远远超出预期每一个都能单独写一篇分享。这里挑几个最影响手感的讲。第一个是框选。用户按住空白区域拖出一个矩形框矩形内部和相交的节点要同时进入选中状态。判定相交用的是矩形碰撞检测一个节点只要有部分区域进入框选范围就被选中。这个判定规则不同工具有不同做法有的严格要求完全包含有的允许相交选中。实测下来“相交即选中”的容错率更高用户不会因为节点边角差了一个像素而莫名选不中。第二个是吸附。节点拖到另一个节点附近时如果两者的边缘距离小于8像素就自动对齐到相同边缘或中心。吸附算法本质上是对坐标做了量化四舍五入但如果不施加“吸附力”的视觉反馈用户会感觉节点被卡住了。所以吸附触发时节点颜色要轻微高亮并且按Shift键要能临时关闭吸附。这个功能在绘制对齐要求高的架构图时几乎离不开。第三个是缩放。其实缩放不是直接对整体坐标做缩放而是对“视口”做缩放。画布的缩放系数改变时节点坐标并不变只是视口矩阵变换改变了最终投影效果。这里面有个惯用手法叫“以鼠标位置为缩放中心”鼠标指向哪里缩放时就以哪里的坐标点作为保持不动的位置。实现方式是记录缩放前鼠标画布坐标缩放后重新计算视口偏移量让同一个画布坐标点仍然落在鼠标下方。3. 多人实时协同从单机编辑到云端协作3.1 协同模型选型与原因diagram-design系统最硬核的部分是多人实时协同。一张图表被多个成员同时打开编辑A同学拖动了一个节点B同学在同一时刻改了节点文字两个人的修改必须可靠地合并并且最终收敛到所有人都一致的状态。协同算法的主要路线有两条CRDT和OT。CRDT在纯文本协同场景已经非常成熟基于操作交换和状态合并天然支持多端并发不需要中心服务器做权威裁决。但它对数据结构的要求比较高需要把节点、边这些图元拆成可交换的底层数据结构像“把节点A的x坐标加10”这类操作在CRDT模型里要表达为一棵共享树的路径更新。OT算法则是以“操作变换”为核心每个客户端把本地操作发给服务器服务器通过转换函数把并发操作变成可顺序执行的操作序列。OT的问题是转换函数容易写错尤其在复合操作面前处理不好会造成不可恢复的状态分叉。我们最终走的是混合路线整体上采用OT的通道模型但把操作粒度缩小到“图元级单字段”级别。比如移动节点被拆成改x、改y两个操作修改节点文字就是一个单独的setLabel操作。操作粒度越细冲突面越小需要写变换函数的地方就越少。实际操作中95%的并发冲突都是不同字段的修改天然不会冲突剩下5%的同字段冲突才需要走一轮变换和覆盖策略。3.2 增量操作数据结构协同数据通道的数据结构直接决定了服务器端的合并复杂度。我们定义了一个标准操作帧{ opId: uuid-xxx, docId: board-001, seq: 1024, userId: user-01, type: setNodeAttr, payload: { nodeId: node-01, attr: x, value: 320 }, baseSeq: 1018, timestamp: 1690000000000 }这里的baseSeq是操作所基于的服务端版本号服务器收到操作后会校验它是否是基于最新版本的。如果当前版本号大于baseSeq说明这段时间里已经有别人提交过操作需要做变换或合并处理。seq是客户端期望的服务端分配序号用于最终排序和乱序识别。所有操作都会先进入服务端的操作日志经过合法性和冲突校验后以广播形式推送到其他在线客户端。新用户打开文档时服务端会先发送一份全量快照再告知其当前版本号之后只发送增量操作。快照加增量的组合机制让新用户打开大文档的加载时间控制在秒级。3.3 冲突解决与体验取舍同字段冲突的解决策略有一个体验上的权衡问题。两个用户同时移动同一个节点最后应该听谁的技术上我们采用了“后写优先”的简单策略因为绘图工具里没有编辑冲突必须保留双方内容的需求移动操作本身就是覆盖性的后写的操作自然覆盖先写的操作。真正麻烦的是“同字段并发覆盖”和“文字编辑冲突”的组合。比如A同学在编辑一个节点的labelB同学同时在拖动这个节点。label修改和坐标修改是不同字段完全不需要冲突处理。但如果A同学和B同学同时修改同一个label字段保留后写操作会让其中一个同学的内容丢失。我们的妥协方案是保留后写操作但给被覆盖的用户弹一次轻提示告诉他“内容被他人更新”允许他通过CtrlZ撤销到自己的版本。这个设计避免了复杂的合并算法用户体验也说得过去。协同场景下还有一个隐藏问题远端操作导致的状态变更要不要进入本地的撤销栈答案是不要。本地撤销栈应该只包含本端用户自己的操作。远端操作直接应用到画布数据后不应该污染本地用户的Undo历史。实现上需要为每个操作打上来源标记applySource为remote时跳过指令栈记录。3.4 权限与可见性控制多人协作不只是数据层面的同步权限模型同样重要。文档被分成只读、可编辑、可管理三个级别。只读用户能看到画布和元素但无法修改可编辑用户可以修改节点和连线但无法删除整张画布可管理用户拥有全部权限包括分享链接、归档文档、删除画布。权限校验在客户端做了第一层拦截服务端依然做了完整校验。客户端拦截是为了更好的交互反馈——当前用户不可编辑时进入画布后光标变成默认指针拖拽节点直接无效服务端校验是为了防止恶意绕过前端发请求。可见性控制则更精细一些。大团队合作时有些节点可能涉及敏感信息只对特定角色可见。这个功能的实现方式是节点上挂了visibilityScope字段服务端推给客户端的数据会根据用户所属角色做过滤。某个节点的可见范围不含当前用户时客户端拿到的数据里直接不包含该节点这样就避免了前端显示后再隐藏带来的闪烁问题。4. 工程落地导出、性能、常见问题4.1 文件导出与序列化diagram-design系统的导出功能分了三条路导出为图片、导出为SVG、导出为JSON项目文件。导出为图片用的是Canvas合成方案——把所有节点的SVG样式收集起来用Canvas重绘一遍再调用canvas.toDataURL(image/png)生成图片下载。这里有一个常见的坑Canvas重绘时如果节点引用了外部图片资源跨域请求会把画布污染掉导致导出结果是空白图。解决方式是提前加载图片并转成base64格式内嵌同时将canvas.crossOrigin设为空。SVG导出走的是序列化路线。我们维护了一个统一的图元渲染函数渲染到屏幕时和导出SVG时用的是同一套逻辑只是导出时不渲染滚动条和辅助线。好处是导出的SVG编辑时看到什么就是什么不会有偏差。JSON导出则是项目的全量数据快照包括画布配置、节点列表、边列表、版本号外加一个diagram-design.schemaVersion字段。这个字段决定了旧版本数据能否被新版本兼容读取每次数据模型变更都会递增这个版本号并写一份迁移函数。工程上不写迁移函数的话线上数据格式一调整旧文档大面积打不开的场景一定会发生。4.2 性能优化渲染、裁剪、合并性能优化是这个项目花时间最长的部分。我们完整踩过从“小图流畅”到“大图卡顿”的整个性能梯度最终沉淀出三条有效的优化策略。第一条是视口裁剪。画布很大但用户一次只能看到其中一小部分所以渲染时只绘制视口范围内的节点和边。视口范围是当前屏幕坐标反解后得到的画布坐标矩形判断节点是否在矩形内用矩形相交检测即可。裁剪逻辑写好后1000个节点的图在视口内一般只有五六十个节点渲染压力骤减。第二条是渲染合并。当大量节点同时移动时每个节点独立更新位置会触发布局抖动。常规做法是把移动过程放到requestAnimationFrame里收集一帧内的所有变换以批量方式统一更新DOM样式。对于SVG模式合并更新的单位是整条连线路径而不是单一的D点坐标。第三条是GC友好。图数据是结构化的对象操作频繁时会产生大量临时对象例如路径点数组、折线计算矩阵、命中检测的包围盒对象。这些临时对象积攒多了会频繁触发垃圾回收表现为操作一阵子后突然掉帧。我们做了一个简单的对象池复用机制提前申请一组包围盒对象每次计算重用而不是新建。4.3 常见问题与排查速查表开发过程中积累了不少问题排查经验整理成一张速查表遇到的很多问题都能直接对上号。问题现象根因分析解决方案缩放后鼠标拖拽漂移屏幕坐标转画布坐标公式错误检查zoom变换是否在平移变换之前叠加导出图片缺字体浏览器字体没加载完就执行了绘制导出前调用document.fonts.ready等待字体加载节点多了之后拖动发卡拖拽时高频实时更新所有关联边先临时直线松开后再进入路由计算协同编辑后部分节点消失操作冲突后本地状态被错误覆盖检查远端操作的baseSeq和本地版本号是否对齐框选不中区域内的节点命中检测用了屏幕坐标但节点是画布坐标统一全部换算到画布坐标后再做碰撞右键菜单在Canvas模式下定位不准Canvas模式缺少DOM坐标对应关系挂一个隐藏DOM层用于记录菜单坐标这里面最值得说的是第一条缩放漂移问题。正确公式是先算画布坐标时要把鼠标相对于画布容器的像素位置除以缩放系数再加上视口偏移的倒数。顺序反了的话缩放越大漂移越明显这也是新手做画布系统最容易遇到的问题。4.4 复盘与二次迭代建议diagram-design系统迭代到比较稳定的阶段后我复盘了整个技术路径。如果让我重新做一次有几个决策会调整一是底层渲染可以更早抽象出统一的插件机制而不是让业务方直接改核心代码二是协同操作变更日志需要从一开始就考虑持久化到文件系统否则追溯时就只能靠内存里的日志三是初始阶段就要把权限体系接入统一身份服务不要等协同做完才补。后续如果在这个系统上继续扩展优先级最高的是三个方向。第一个是更多的图形类型库比如UML类图、ER图、泳道图的一键生成第二个是AI辅助排版的接入根据当前画布元素密度自动调整布局第三个是嵌入场景的插件化SDK让其他业务系统能一键把diagram-design嵌入自己的界面里而不是被硬编码死。如果让我从一个更大的视角看这类项目我会说画布工具的本质不只是画图它其实是在搭建一种结构化的思维表达框架。你给它的数据模型有多强大用户能在上面描绘的复杂关系就有多丰富。这个系统的价值不在于某个节点拖得有多顺畅而在于它让那些原本只存在于文档文字里的逻辑关系变成了一种可以反复推敲、协作演进的活资产。最后分享一个小细节如果团队里第一次做图形化编辑器一定要预留时间啃交互细节。数据模型、渲染方案顶多占三成工作量剩下七成都花在参数对齐、坐标换算、命中容错这些无声的角落。把交互细节打磨好了产品交付后的维护成本能低一半以上。
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
