最近接了个新需求项目代号就叫 diagram-design。名字看着挺泛实际上是要在网页里做一个通用的图表设计器用户能拖拖拽拽把不同的节点放到画布上连上线导出一张能用的架构图、流程图或者知识图谱。别小看这个东西表面上是画图背后牵扯的是一整套“可交互的图数据模型”。这类需求通常出自想统一内部绘图工具的场景。团队里不同角色需要画不同图形产品要画泳道图研发要画部署架构算法要画数据处理链路如果每个人都用本地软件画最后的图散落在各处内容也难维护。diagram-design 这类项目就是要把“画图”变成“在图编辑器中维护结构化数据”图可以保存、分享、校验甚至后续自动生成文档。这篇文章我就按自己落地的经验完整拆一遍从需求梳理、数据模型、渲染选型到拖拽连线这些核心交互怎么实现再到实战中比较容易踩的坑。如果你想做一个图编辑系统或者做流程图、拓扑图、DAG 编辑器这篇应该能让你少走不少弯路。1. 项目定位diagram-design 到底要解决什么问题1.1 从一次需求说起当时产品经理跑过来跟我说要做一个“能画架构图的东西”。我那会儿的第一反应是这不就是给一个画布加几个矩形然后连上线吗。真正开工之后才发现需求远不止这么简单。内部讨论之后需求被拆成了四层。第一层是基础画布支持缩放、平移、框选、对齐第二层是节点体系节点不仅是一个矩形还要有图标、颜色、内置字段、自定义属性不同类型节点能配置不同样式第三层是连线体系连线要支持直线、折线、曲线要能自动避开节点还要能承载标签和校验信息第四层是结构化存储图不能只是一张图片而应该是一份 JSON能被后端识别能被版本管理能被不同的工具消费。你可能觉得每一层都不难但合在一起就是一个图形编辑器的核心。diagram-design 听起来是“设计图表”实际做的是“图数据的管理和交互”。这个项目最适合谁参考如果你是刚开始接触可视化编辑方向的前端或者全栈开发者平时做过图表展示但没做过“编辑器”类产品那这个拆解会很有用。如果你只是临时想画个架构示意图那直接找现成绘图工具就行没必要自己造轮子。1.2 Diagram 和 Chart 不是一回事很多人会把 diagram-design 想成图表库项目但 Diagram 和 Chart 底层思路差别很大。Chart 是数据到图形的单向映射你给它一份折线数据、柱状数据它负责渲染而 Diagram 是用户主动构建的图形节点层级关系、连线逻辑都是使用者定义出来的系统要做的是“编辑”而不是“展示”。这个区别决定了技术选型和数据模型。Chart 场景里数据是表格化的适合用常见的图表组件库而 Diagram 场景里数据是图结构的天然由节点、边、端口组成。画布上的每一个元素都要能被创建、选中、修改、删除、撤销还要支持序列化。所以 diagram-design 从一开始就不可能简单套用图表库来改。它的核心是一个“有状态”的图模型再叠加图形渲染和交互控制。理解这一点之后整个项目的架构边界就清晰了很多把业务数据、图形状态、交互逻辑分开而不是都堆在渲染层里。1.3 技术选型的总原则关于要不要用现成的开源图编辑库我的观点是可以用但不建议直接铺开用。现成库可以帮你解决一部分拖拽、连线、画布变换的问题但 diagram-design 这类项目往往需要跟业务深度耦合比如节点上绑定审批状态连线上绑定规则信息画布内嵌到业务系统里。如果直接把现成库搬过来后续会遇到两个问题一是外观和交互行为难统一二是数据格式受制于人迁移成本高。因此整体原则是“底层基础可借助成熟方案核心数据模型和状态管理一定要自己掌控”。把图的数据结构定义清楚渲染层和交互层尽量解耦。这样就算以后渲染引擎换一套数据层也不会受太大影响。我在做的过程中把项目拆成三个核心模块数据模型、渲染器、交互控制器。数据模型负责描述“图是什么”渲染器负责把图画出来交互控制器负责让用户的操作变成数据模型的变化。这三个模块严格分层之后后面的功能扩展都变得很顺。2. 核心数据模型与状态管理2.1 节点、边、端口的三层结构diagram-design 的第一步不是写画面代码而是先写类型定义。我第一版画图时特别随意节点记一个坐标和宽高连线直接记 sourceId 和 targetId结果后面做锚点、做路由、做校验时全都返工了。正确做法是把节点、边、端口拆成三层。节点是画布上的实体包含位置和尺寸端口是节点上的连接点比如输入口和输出口边是一条包含起点和终点端口的关联关系而不是只连到节点上。为什么非要加端口因为如果不区分端口连线都会指向节点中心节点靠近时曲线会交叉布局也没有方向性。有了端口边才能知道自己从哪里出发、到哪里去后续做正交路由、自动布局、模型合法性校验才有着力点。一个节点的最小结构可以这样定义interface DiagramNode { id: string; // 全局唯一 type: string; // 节点类型比如 service / storage / decision x: number; // 画布坐标不是屏幕坐标 y: number; width: number; height: number; ports: DiagramPort[]; // 端口属于节点整体存 data: Recordstring, unknown; // 业务数据比如标题、状态、扩展字段 } interface DiagramPort { id: string; direction: in | out | both; xOffset: number; // 相对节点左上角的偏移 yOffset: number; label?: string; } interface DiagramEdge { id: string; source: string; // 源节点 id sourcePort: string; // 源端口 id target: string; targetPort: string; routerType: straight | orthogonal | bezier; data?: Recordstring, unknown; }一开始就把端口做成独立实体后面收益很大。之前没有端口概念的时候做节点拖拽后连线跟着跑就只能重新计算节点中心坐标导致连线走向乱跳。有了端口边的端点位置只跟端口相对节点的偏移有关节点怎么动端口都能正确跟随。2.2 一张图的 JSON 快照图应该可以随时保存成一份 JSON也能够从 JSON 完整恢复。这份 JSON 就是图编辑器的“源文件”。我建议把画布信息和节点边信息放在同一个顶层对象里画布信息记录背景和坐标系范围节点和边各自存数组。一张比较完整的图快照大概长这样{ canvas: { width: 4000, height: 3000, background: #f8f9fa }, nodes: [ { id: n1, type: service, x: 120, y: 140, width: 180, height: 56, ports: [ { id: n1-in-1, direction: in, xOffset: 0, yOffset: 28 }, { id: n1-out-1, direction: out, xOffset: 180, yOffset: 28 } ], data: { title: 下单服务, status: running } }, { id: n2, type: storage, x: 360, y: 140, width: 180, height: 56, ports: [ { id: n2-in-1, direction: in, xOffset: 0, yOffset: 28 } ], data: { title: 订单数据库, status: healthy } } ], edges: [ { id: e1, source: n1, sourcePort: n1-out-1, target: n2, targetPort: n2-in-1, routerType: orthogonal, data: { label: 写入 } } ] }这份快照有几个设计要点。第一所有坐标使用画布坐标系跟屏幕显示无关这样缩放不会污染数据第二业务字段放在 data 里跟图形字段分开后续做搜索或校验时可以不动图形结构第三整个 JSON 是纯数据不包含函数、DOM 引用和临时状态天然可以序列化到后端。有了这份 JSON导出、导入、版本对比都好做了。我之前踩过一个坑把节点的状态、数据混乱地放在同一个平铺对象里结果同一个人在不同节点上加了不同的字段导致下游解析时要么写一堆兼容逻辑要么等着数据发烂。分层是值得一开始就做好的。2.3 状态管理和撤销重做的设计图编辑器比普通表单复杂的地方在于用户操作产生大量中间态而且这些中间态必须可回溯。拖拽一个节点从鼠标按下到抬起中间可能产生几十个坐标变化如果每个变化都记录到历史栈里撤销功能很快会被塞爆。合理的做法是把历史记录切成“提交点”。每次交互行为结束后才把完整的状态快照推入历史栈。比如拖拽节点时mousemove 只是实时更新当前内存中的坐标mouseup 时才把变化后的状态提交一次。同样连线的连接动作也是结束瞬间提交。我建议用单向数据流管理整个图对象所有节点和边的增删改都通过统一的 action 触发这样历史栈可以基于 action 构建也可以基于状态快照构建。基于快照实现最简单每次提交时深拷贝当前状态存到栈里撤销时弹出上一个快照重做时再压回去。节点数量几百个时深拷贝成本还可以接受超过上千就要考虑增量记录了。实际操作中我建议把“当前画布视图状态”和“图数据”分开管理。缩放比例、平移距离、当前选中的元素这些都应该独立于图数据之外不然保存一份图的时候会把多余的界面状态也存进去导致两个用户打开同一个图却看到不同的选区。3. 画布交互与渲染引擎的落地实现3.1 渲染层选型Canvas 还是 SVGdiagram-design 的渲染层最纠结的就是 Canvas 和 SVG。两种方案各有适用场景我做过两个版本感受很明显。SVG 的优点在于全是 DOM 节点每个矩形、每个线条都能直接绑定事件开发简单样式控制方便适合快速实现原型。缺点是节点一多DOM 节点数量大了之后事件监听和重绘性能会明显下降。几百个节点加几百条连线时拖动画布会有卡顿。Canvas 的优点是没有 DOM 节点数量的上限压力重绘灵活几十个节点渲染起来毫无压力做到一两千节点也不至于崩。缺点是需要自己处理事件命中也就是要判断鼠标点击位置落在哪个节点上开发成本更高一些。对于 diagram-design 这类图编辑器我最终选了 Canvas 作为主渲染层。核心判断依据是工具未来一定会往更大画布、更多节点方向发展越早把事件命中逻辑做出来后续扩展越稳。如果你只是要一个轻量级的流程图编辑器节点数量撑死几十个用 SVG 完全够不用给自己加戏。但如果你要做平台级能力Canvas 的长期收益更高。渲染时我还会把“视觉样式”和“数据模型”彻底分开。节点的宽高、坐标来自数据但颜色、边框、图标样式来自主题配置可以全局换肤。这样数据文件里不掺杂视觉字段导出图时不会被样式干扰。3.2 缩放平移与坐标转换很多第一次做图编辑器的人会发现一个奇怪的现象画布一旦缩放鼠标点的位置跟节点对不上了。这基本是坐标转换没做完整。只要画布不是简单静止的页面就一定存在两套坐标体系屏幕坐标和画布坐标。鼠标事件拿到的是屏幕坐标但节点存的是画布坐标。两者之间隔着容器偏移、平移距离和缩放比例。实现缩放平移时最核心的一步就是正确做坐标转换。我用的方式是这样的先把最外层容器定位为相对定位画布内部是一个逻辑坐标系再通过 CSS transform 控制画布的平移和缩放。转换公式如下function screenToCanvas(clientX: number, clientY: number) { const rect container.getBoundingClientRect(); return { x: (clientX - rect.left - viewport.panX) / viewport.scale, y: (clientY - rect.top - viewport.panY) / viewport.scale }; }同样地从画布坐标转到屏幕坐标就是逆运算function canvasToScreen(canvasX: number, canvasY: number) { const rect container.getBoundingClientRect(); return { x: rect.left canvasX * viewport.scale viewport.panX, y: rect.top canvasY * viewport.scale viewport.panY }; }这里的 panX 和 panY 是画布相对于容器的偏移量。缩放时如果我围绕鼠标位置缩放还需要额外修正 pan不然画面会朝左上角缩体验很差。这个修正公式不复杂记录鼠标在画布上的坐标缩放后让这个点保持在鼠标当前位置下。真心建议把这两个函数封装成纯函数放到一个独立的坐标模块里不要散落在各个回调中。以前我为了省事到处直接用 offsetX 和 offsetY后来发现元素有 padding、画布有缩放时就会算错排查了很久。3.3 节点拖拽和连线交互的实现要点图表编辑器最核心的三个交互是拖拽节点、平移画布、连边。每个交互背后都有细节。拖拽节点的实现框架是 pointerdown / pointermove / pointerup。pointerdown 时记录起始坐标和节点初始位置pointermove 时计算位移差并更新节点坐标pointerup 时提交一次历史记录。拖拽过程中为了性能可以直接在 Canvas 上重绘当前拖拽节点而不是反复触发整个页面渲染。画布平移和节点拖拽之间会有冲突在空白区域按住拖动是平移在节点上按住拖动是移动节点。这个冲突通过事件命中判断来解决。每次交互开始前先判断点击位置是否落在节点上如果命中了节点就走节点拖拽否则走画布平移。连线交互稍微复杂一点。常见的交互路径是从一个节点的输出端口按住鼠标拖出一条临时连线鼠标移动到另一个节点的输入端口附近时目标端口高亮松开后生成一条边。要支持这个交互需要做两件事一是绘制临时连线二是实时寻找鼠标位置附近的端口。寻找端口时我维护一个当前画布中的所有端口列表遍历计算距离。如果鼠标坐标和某个端口坐标的距离小于设定的吸附阈值就认为用户想要连接这个端口。为了提高效率端口数量多的时候可以按画布分块建立索引但一般节点数量在一千以内时直接遍历也能接受。连线生成后还需要重新计算路径。直线最简单曲线适中正交折线最麻烦因为要绕开节点、处理重叠。如果业务上强调美观建议先实现直线和曲线正交路由后续再增强不要一开始就困在复杂的寻路算法里。4. 实操过程中的高频问题与排查方法4.1 连线总是连歪、命中不了端口我第一个版本做连线时边很长一段时间都连不对地方后来发现原因很简单生成边的终点用的不是端口坐标而是节点中心坐标。两个节点稍微错位连线就会歪歪扭扭地指向中心。后来我把边的定义改为强依赖端口 id每次绘制路径时先用端口坐标算出实际端点问题就消失了。另一个原因是吸附阈值太小或太大。阈值太小用户要非常精准地停到端口上才能连上阈值太大稍微靠近就吸附到不想要的端口上。我本人用的阈值是 10 像素左右这个值在 1 倍缩放时体验合适但画布放大后阈值也要跟着除以缩放比例否则用户在放大状态下很难命中端口。还有一个体验细节拖动连线时最好在鼠标靠近端口时实时高亮目标端口并且临时连线自动吸附到高亮端口上。这样用户能明确知道“我松开会连到哪里”而不用凭感觉猜。4.2 缩放后鼠标位置漂移前面说过缩放和平移的坐标转换是图编辑器最容易出错的地方。漂移的典型表现是画布放大到 200%鼠标拖拽节点时节点跟手但位置跑偏或者框选时选区跑到别的地方。出现这种问题我先会打印一组实际数据来判断比如 clientX, rect.left, panX, scale然后手算一遍预期的 canvas 坐标再跟业务里用的值对比。绝大多数情况下是某处少减了一个 rect.left或者少除以一个 scale。特别注意不要依赖 offsetX / offsetY。这两个值虽然方便但受 padding、border 和缩放 transform 影响结果不稳定。统一使用 getBoundingClientRect 加 clientX / clientY 才是安全做法。我把坐标转换封装成独立函数后顺带写了一个小工具函数来测试转换的往返一致性无论怎么缩放平移先 screenToCanvas 再 canvasToScreen结果应该回到原始屏幕坐标。超过一像素误差就说明实现有问题。这个小工具帮我提前挡掉了很多 bug。4.3 节点一多就卡顿节点少的时候感受不到性能问题一旦业务方把几百个节点拖进画布卡顿就来了。我遇到过最明显的两个瓶颈。第一个是状态更新导致的。每移动一个像素就更新全局状态整个画布所有节点全部重绘代价很高。解决方法是让状态更新粒度尽量小拖拽过程中只更新当前节点的坐标其它节点保持不变拖拽结束再统一更新整体快照。第二个是渲染频率。Canvas 重绘做得太频繁也和状态更新频繁有关。合理做法是用 requestAnimationFrame 节流保证每一帧最多重绘一次。即使触发了很多次坐标更新只要都落在同一帧里视觉上依然流畅。如果真的到几千节点的规模就需要牺牲一部分绘制效果。我的经验是先把离当前视口太远的节点跳过不画只渲染可见区域内的元素。这个优化对画布型编辑器效果非常明显因为用户通常只盯着一块区域看图。4.4 问题排查速查表平时汇总的常见问题整理成一张表方便后面排查。症状大概率原因解决办法缩放后鼠标点击的位置和画布元素对不上坐标转换漏除缩放比例或漏减容器偏移统一封装 screenToCanvas / canvasToScreen节点拖拽很卡拖拽过程频繁触发全局状态更新拖拽中只更新当前节点拖拽结束再提交历史连线连不到端口边的端点用了节点中心坐标或者未做吸附端点改用端口坐标增加吸附阈值画布平移和节点拖拽冲突事件命中判断不当空白和节点区分不清每次交互开始前先做一次命中检测撤销回退结果不对历史栈记录了过多中间状态每次交互结束只提交一次快照保存后的图再打开变了位置存了屏幕坐标或视图状态数据层统一使用画布坐标和视图状态分离这张表里的绝大多数问题本质上都源于“没有把数据模型、视图状态、交互逻辑分开”。一旦混在一起刚开始没问题功能越来越多就会失控。diagram-design 这类项目最值得投入的就是第一周的数据模型设计把数据关系想清楚后面能省下大把排查时间。坦白说这类项目做久了我最深的感受是它不像一个普通页面更像是在做一个微型的图形软件。节点、边、画布、历史记录每个模块单独看都不复杂合在一起却很考验全局思维。我当初因为数据结构没设计好返工过一次之后开始坚持先写类型定义、再写交互逻辑、最后再做视觉。你现在做的时候也可以试试这个顺序先不要急着画界面而是先把“一张图在代码里长什么样”想明白。这个习惯能让 diagram-design 后面的路走得轻松很多。
最近接了个新需求项目代号就叫 diagram-design。名字看着挺泛实际上是要在网页里做一个通用的图表设计器用户能拖拖拽拽把不同的节点放到画布上连上线导出一张能用的架构图、流程图或者知识图谱。别小看这个东西表面上是画图背后牵扯的是一整套“可交互的图数据模型”。这类需求通常出自想统一内部绘图工具的场景。团队里不同角色需要画不同图形产品要画泳道图研发要画部署架构算法要画数据处理链路如果每个人都用本地软件画最后的图散落在各处内容也难维护。diagram-design 这类项目就是要把“画图”变成“在图编辑器中维护结构化数据”图可以保存、分享、校验甚至后续自动生成文档。这篇文章我就按自己落地的经验完整拆一遍从需求梳理、数据模型、渲染选型到拖拽连线这些核心交互怎么实现再到实战中比较容易踩的坑。如果你想做一个图编辑系统或者做流程图、拓扑图、DAG 编辑器这篇应该能让你少走不少弯路。1. 项目定位diagram-design 到底要解决什么问题1.1 从一次需求说起当时产品经理跑过来跟我说要做一个“能画架构图的东西”。我那会儿的第一反应是这不就是给一个画布加几个矩形然后连上线吗。真正开工之后才发现需求远不止这么简单。内部讨论之后需求被拆成了四层。第一层是基础画布支持缩放、平移、框选、对齐第二层是节点体系节点不仅是一个矩形还要有图标、颜色、内置字段、自定义属性不同类型节点能配置不同样式第三层是连线体系连线要支持直线、折线、曲线要能自动避开节点还要能承载标签和校验信息第四层是结构化存储图不能只是一张图片而应该是一份 JSON能被后端识别能被版本管理能被不同的工具消费。你可能觉得每一层都不难但合在一起就是一个图形编辑器的核心。diagram-design 听起来是“设计图表”实际做的是“图数据的管理和交互”。这个项目最适合谁参考如果你是刚开始接触可视化编辑方向的前端或者全栈开发者平时做过图表展示但没做过“编辑器”类产品那这个拆解会很有用。如果你只是临时想画个架构示意图那直接找现成绘图工具就行没必要自己造轮子。1.2 Diagram 和 Chart 不是一回事很多人会把 diagram-design 想成图表库项目但 Diagram 和 Chart 底层思路差别很大。Chart 是数据到图形的单向映射你给它一份折线数据、柱状数据它负责渲染而 Diagram 是用户主动构建的图形节点层级关系、连线逻辑都是使用者定义出来的系统要做的是“编辑”而不是“展示”。这个区别决定了技术选型和数据模型。Chart 场景里数据是表格化的适合用常见的图表组件库而 Diagram 场景里数据是图结构的天然由节点、边、端口组成。画布上的每一个元素都要能被创建、选中、修改、删除、撤销还要支持序列化。所以 diagram-design 从一开始就不可能简单套用图表库来改。它的核心是一个“有状态”的图模型再叠加图形渲染和交互控制。理解这一点之后整个项目的架构边界就清晰了很多把业务数据、图形状态、交互逻辑分开而不是都堆在渲染层里。1.3 技术选型的总原则关于要不要用现成的开源图编辑库我的观点是可以用但不建议直接铺开用。现成库可以帮你解决一部分拖拽、连线、画布变换的问题但 diagram-design 这类项目往往需要跟业务深度耦合比如节点上绑定审批状态连线上绑定规则信息画布内嵌到业务系统里。如果直接把现成库搬过来后续会遇到两个问题一是外观和交互行为难统一二是数据格式受制于人迁移成本高。因此整体原则是“底层基础可借助成熟方案核心数据模型和状态管理一定要自己掌控”。把图的数据结构定义清楚渲染层和交互层尽量解耦。这样就算以后渲染引擎换一套数据层也不会受太大影响。我在做的过程中把项目拆成三个核心模块数据模型、渲染器、交互控制器。数据模型负责描述“图是什么”渲染器负责把图画出来交互控制器负责让用户的操作变成数据模型的变化。这三个模块严格分层之后后面的功能扩展都变得很顺。2. 核心数据模型与状态管理2.1 节点、边、端口的三层结构diagram-design 的第一步不是写画面代码而是先写类型定义。我第一版画图时特别随意节点记一个坐标和宽高连线直接记 sourceId 和 targetId结果后面做锚点、做路由、做校验时全都返工了。正确做法是把节点、边、端口拆成三层。节点是画布上的实体包含位置和尺寸端口是节点上的连接点比如输入口和输出口边是一条包含起点和终点端口的关联关系而不是只连到节点上。为什么非要加端口因为如果不区分端口连线都会指向节点中心节点靠近时曲线会交叉布局也没有方向性。有了端口边才能知道自己从哪里出发、到哪里去后续做正交路由、自动布局、模型合法性校验才有着力点。一个节点的最小结构可以这样定义interface DiagramNode { id: string; // 全局唯一 type: string; // 节点类型比如 service / storage / decision x: number; // 画布坐标不是屏幕坐标 y: number; width: number; height: number; ports: DiagramPort[]; // 端口属于节点整体存 data: Recordstring, unknown; // 业务数据比如标题、状态、扩展字段 } interface DiagramPort { id: string; direction: in | out | both; xOffset: number; // 相对节点左上角的偏移 yOffset: number; label?: string; } interface DiagramEdge { id: string; source: string; // 源节点 id sourcePort: string; // 源端口 id target: string; targetPort: string; routerType: straight | orthogonal | bezier; data?: Recordstring, unknown; }一开始就把端口做成独立实体后面收益很大。之前没有端口概念的时候做节点拖拽后连线跟着跑就只能重新计算节点中心坐标导致连线走向乱跳。有了端口边的端点位置只跟端口相对节点的偏移有关节点怎么动端口都能正确跟随。2.2 一张图的 JSON 快照图应该可以随时保存成一份 JSON也能够从 JSON 完整恢复。这份 JSON 就是图编辑器的“源文件”。我建议把画布信息和节点边信息放在同一个顶层对象里画布信息记录背景和坐标系范围节点和边各自存数组。一张比较完整的图快照大概长这样{ canvas: { width: 4000, height: 3000, background: #f8f9fa }, nodes: [ { id: n1, type: service, x: 120, y: 140, width: 180, height: 56, ports: [ { id: n1-in-1, direction: in, xOffset: 0, yOffset: 28 }, { id: n1-out-1, direction: out, xOffset: 180, yOffset: 28 } ], data: { title: 下单服务, status: running } }, { id: n2, type: storage, x: 360, y: 140, width: 180, height: 56, ports: [ { id: n2-in-1, direction: in, xOffset: 0, yOffset: 28 } ], data: { title: 订单数据库, status: healthy } } ], edges: [ { id: e1, source: n1, sourcePort: n1-out-1, target: n2, targetPort: n2-in-1, routerType: orthogonal, data: { label: 写入 } } ] }这份快照有几个设计要点。第一所有坐标使用画布坐标系跟屏幕显示无关这样缩放不会污染数据第二业务字段放在 data 里跟图形字段分开后续做搜索或校验时可以不动图形结构第三整个 JSON 是纯数据不包含函数、DOM 引用和临时状态天然可以序列化到后端。有了这份 JSON导出、导入、版本对比都好做了。我之前踩过一个坑把节点的状态、数据混乱地放在同一个平铺对象里结果同一个人在不同节点上加了不同的字段导致下游解析时要么写一堆兼容逻辑要么等着数据发烂。分层是值得一开始就做好的。2.3 状态管理和撤销重做的设计图编辑器比普通表单复杂的地方在于用户操作产生大量中间态而且这些中间态必须可回溯。拖拽一个节点从鼠标按下到抬起中间可能产生几十个坐标变化如果每个变化都记录到历史栈里撤销功能很快会被塞爆。合理的做法是把历史记录切成“提交点”。每次交互行为结束后才把完整的状态快照推入历史栈。比如拖拽节点时mousemove 只是实时更新当前内存中的坐标mouseup 时才把变化后的状态提交一次。同样连线的连接动作也是结束瞬间提交。我建议用单向数据流管理整个图对象所有节点和边的增删改都通过统一的 action 触发这样历史栈可以基于 action 构建也可以基于状态快照构建。基于快照实现最简单每次提交时深拷贝当前状态存到栈里撤销时弹出上一个快照重做时再压回去。节点数量几百个时深拷贝成本还可以接受超过上千就要考虑增量记录了。实际操作中我建议把“当前画布视图状态”和“图数据”分开管理。缩放比例、平移距离、当前选中的元素这些都应该独立于图数据之外不然保存一份图的时候会把多余的界面状态也存进去导致两个用户打开同一个图却看到不同的选区。3. 画布交互与渲染引擎的落地实现3.1 渲染层选型Canvas 还是 SVGdiagram-design 的渲染层最纠结的就是 Canvas 和 SVG。两种方案各有适用场景我做过两个版本感受很明显。SVG 的优点在于全是 DOM 节点每个矩形、每个线条都能直接绑定事件开发简单样式控制方便适合快速实现原型。缺点是节点一多DOM 节点数量大了之后事件监听和重绘性能会明显下降。几百个节点加几百条连线时拖动画布会有卡顿。Canvas 的优点是没有 DOM 节点数量的上限压力重绘灵活几十个节点渲染起来毫无压力做到一两千节点也不至于崩。缺点是需要自己处理事件命中也就是要判断鼠标点击位置落在哪个节点上开发成本更高一些。对于 diagram-design 这类图编辑器我最终选了 Canvas 作为主渲染层。核心判断依据是工具未来一定会往更大画布、更多节点方向发展越早把事件命中逻辑做出来后续扩展越稳。如果你只是要一个轻量级的流程图编辑器节点数量撑死几十个用 SVG 完全够不用给自己加戏。但如果你要做平台级能力Canvas 的长期收益更高。渲染时我还会把“视觉样式”和“数据模型”彻底分开。节点的宽高、坐标来自数据但颜色、边框、图标样式来自主题配置可以全局换肤。这样数据文件里不掺杂视觉字段导出图时不会被样式干扰。3.2 缩放平移与坐标转换很多第一次做图编辑器的人会发现一个奇怪的现象画布一旦缩放鼠标点的位置跟节点对不上了。这基本是坐标转换没做完整。只要画布不是简单静止的页面就一定存在两套坐标体系屏幕坐标和画布坐标。鼠标事件拿到的是屏幕坐标但节点存的是画布坐标。两者之间隔着容器偏移、平移距离和缩放比例。实现缩放平移时最核心的一步就是正确做坐标转换。我用的方式是这样的先把最外层容器定位为相对定位画布内部是一个逻辑坐标系再通过 CSS transform 控制画布的平移和缩放。转换公式如下function screenToCanvas(clientX: number, clientY: number) { const rect container.getBoundingClientRect(); return { x: (clientX - rect.left - viewport.panX) / viewport.scale, y: (clientY - rect.top - viewport.panY) / viewport.scale }; }同样地从画布坐标转到屏幕坐标就是逆运算function canvasToScreen(canvasX: number, canvasY: number) { const rect container.getBoundingClientRect(); return { x: rect.left canvasX * viewport.scale viewport.panX, y: rect.top canvasY * viewport.scale viewport.panY }; }这里的 panX 和 panY 是画布相对于容器的偏移量。缩放时如果我围绕鼠标位置缩放还需要额外修正 pan不然画面会朝左上角缩体验很差。这个修正公式不复杂记录鼠标在画布上的坐标缩放后让这个点保持在鼠标当前位置下。真心建议把这两个函数封装成纯函数放到一个独立的坐标模块里不要散落在各个回调中。以前我为了省事到处直接用 offsetX 和 offsetY后来发现元素有 padding、画布有缩放时就会算错排查了很久。3.3 节点拖拽和连线交互的实现要点图表编辑器最核心的三个交互是拖拽节点、平移画布、连边。每个交互背后都有细节。拖拽节点的实现框架是 pointerdown / pointermove / pointerup。pointerdown 时记录起始坐标和节点初始位置pointermove 时计算位移差并更新节点坐标pointerup 时提交一次历史记录。拖拽过程中为了性能可以直接在 Canvas 上重绘当前拖拽节点而不是反复触发整个页面渲染。画布平移和节点拖拽之间会有冲突在空白区域按住拖动是平移在节点上按住拖动是移动节点。这个冲突通过事件命中判断来解决。每次交互开始前先判断点击位置是否落在节点上如果命中了节点就走节点拖拽否则走画布平移。连线交互稍微复杂一点。常见的交互路径是从一个节点的输出端口按住鼠标拖出一条临时连线鼠标移动到另一个节点的输入端口附近时目标端口高亮松开后生成一条边。要支持这个交互需要做两件事一是绘制临时连线二是实时寻找鼠标位置附近的端口。寻找端口时我维护一个当前画布中的所有端口列表遍历计算距离。如果鼠标坐标和某个端口坐标的距离小于设定的吸附阈值就认为用户想要连接这个端口。为了提高效率端口数量多的时候可以按画布分块建立索引但一般节点数量在一千以内时直接遍历也能接受。连线生成后还需要重新计算路径。直线最简单曲线适中正交折线最麻烦因为要绕开节点、处理重叠。如果业务上强调美观建议先实现直线和曲线正交路由后续再增强不要一开始就困在复杂的寻路算法里。4. 实操过程中的高频问题与排查方法4.1 连线总是连歪、命中不了端口我第一个版本做连线时边很长一段时间都连不对地方后来发现原因很简单生成边的终点用的不是端口坐标而是节点中心坐标。两个节点稍微错位连线就会歪歪扭扭地指向中心。后来我把边的定义改为强依赖端口 id每次绘制路径时先用端口坐标算出实际端点问题就消失了。另一个原因是吸附阈值太小或太大。阈值太小用户要非常精准地停到端口上才能连上阈值太大稍微靠近就吸附到不想要的端口上。我本人用的阈值是 10 像素左右这个值在 1 倍缩放时体验合适但画布放大后阈值也要跟着除以缩放比例否则用户在放大状态下很难命中端口。还有一个体验细节拖动连线时最好在鼠标靠近端口时实时高亮目标端口并且临时连线自动吸附到高亮端口上。这样用户能明确知道“我松开会连到哪里”而不用凭感觉猜。4.2 缩放后鼠标位置漂移前面说过缩放和平移的坐标转换是图编辑器最容易出错的地方。漂移的典型表现是画布放大到 200%鼠标拖拽节点时节点跟手但位置跑偏或者框选时选区跑到别的地方。出现这种问题我先会打印一组实际数据来判断比如 clientX, rect.left, panX, scale然后手算一遍预期的 canvas 坐标再跟业务里用的值对比。绝大多数情况下是某处少减了一个 rect.left或者少除以一个 scale。特别注意不要依赖 offsetX / offsetY。这两个值虽然方便但受 padding、border 和缩放 transform 影响结果不稳定。统一使用 getBoundingClientRect 加 clientX / clientY 才是安全做法。我把坐标转换封装成独立函数后顺带写了一个小工具函数来测试转换的往返一致性无论怎么缩放平移先 screenToCanvas 再 canvasToScreen结果应该回到原始屏幕坐标。超过一像素误差就说明实现有问题。这个小工具帮我提前挡掉了很多 bug。4.3 节点一多就卡顿节点少的时候感受不到性能问题一旦业务方把几百个节点拖进画布卡顿就来了。我遇到过最明显的两个瓶颈。第一个是状态更新导致的。每移动一个像素就更新全局状态整个画布所有节点全部重绘代价很高。解决方法是让状态更新粒度尽量小拖拽过程中只更新当前节点的坐标其它节点保持不变拖拽结束再统一更新整体快照。第二个是渲染频率。Canvas 重绘做得太频繁也和状态更新频繁有关。合理做法是用 requestAnimationFrame 节流保证每一帧最多重绘一次。即使触发了很多次坐标更新只要都落在同一帧里视觉上依然流畅。如果真的到几千节点的规模就需要牺牲一部分绘制效果。我的经验是先把离当前视口太远的节点跳过不画只渲染可见区域内的元素。这个优化对画布型编辑器效果非常明显因为用户通常只盯着一块区域看图。4.4 问题排查速查表平时汇总的常见问题整理成一张表方便后面排查。症状大概率原因解决办法缩放后鼠标点击的位置和画布元素对不上坐标转换漏除缩放比例或漏减容器偏移统一封装 screenToCanvas / canvasToScreen节点拖拽很卡拖拽过程频繁触发全局状态更新拖拽中只更新当前节点拖拽结束再提交历史连线连不到端口边的端点用了节点中心坐标或者未做吸附端点改用端口坐标增加吸附阈值画布平移和节点拖拽冲突事件命中判断不当空白和节点区分不清每次交互开始前先做一次命中检测撤销回退结果不对历史栈记录了过多中间状态每次交互结束只提交一次快照保存后的图再打开变了位置存了屏幕坐标或视图状态数据层统一使用画布坐标和视图状态分离这张表里的绝大多数问题本质上都源于“没有把数据模型、视图状态、交互逻辑分开”。一旦混在一起刚开始没问题功能越来越多就会失控。diagram-design 这类项目最值得投入的就是第一周的数据模型设计把数据关系想清楚后面能省下大把排查时间。坦白说这类项目做久了我最深的感受是它不像一个普通页面更像是在做一个微型的图形软件。节点、边、画布、历史记录每个模块单独看都不复杂合在一起却很考验全局思维。我当初因为数据结构没设计好返工过一次之后开始坚持先写类型定义、再写交互逻辑、最后再做视觉。你现在做的时候也可以试试这个顺序先不要急着画界面而是先把“一张图在代码里长什么样”想明白。这个习惯能让 diagram-design 后面的路走得轻松很多。
复杂度的完整推导)
