★ FEATURED ARTICLE 做技术这些年架构图、流程图、时序图、状态图画了不知道多少张换过的工具也一只手数不过来。说实话现成的绘图工具拿来画一张静态图没毛病可一旦这张图需要跟着数据变化、需要灌进团队的统一视觉规范、需要被人用代码 review所有现成方案都会露馅。diagram-design 这个项目就是在这种环境下长出来的核心思路一句话把“画图”变成“写数据”让图表具备可解析、可计算、可自动布局的能力同时保留手工微调的空间。这篇文章把它从数据模型、渲染方案、交互实现到踩坑调优的全过程完整拆一遍适合那些正在考虑自研图表编辑器、或者想给团队搭建统一绘图规范的开发者朋友。1. 先拆清楚diagram-design到底要做什么1.1 现成绘图工具的三个痛点先说说我真实遇到的场景。有一次我需要把系统的几十个服务节点、调用关系、状态依赖画成一张架构图画到一半发现某个服务改名了于是得手动把所有连线上的标签改一遍。这还算好的真正麻烦的是后来产品要求按环境动态生成不同规模的图总不能每次派个同学去画图工具里手工拖半天。这个时候我才意识到图表工具给我们的是一张“图”但我真正需要的是一条“图表流水线”——数据变了图自动变样式统一还能嵌入文档系统。现成工具的痛点无非三类。第一是数据结构不透明图存下来就是一份私有格式文件想解析、想迁移、想跟业务数据做关联都极其痛苦。第二是自动化能力弱不支持脚本驱动也不暴露底层的数据模型接口。第三是视觉风格难以统一每个人的图都有自己的审美放在一起像拼盘团队规范形同虚设。diagram-design 立项时就把这三件事当成核心目标数据结构化、渲染可编程、样式可配置。1.2 项目定位一份配置渲染出一张图这个项目最初的定位特别简单给我一份 JSON我就能在页面上渲染出一张可交互的图表反过来用户在这张图上做的任何操作最后也都落回这份 JSON。这个想法本质上跟“HTML 是数据、CSS 是皮肤”是同一套逻辑——图表的结构、位置、连线都是数据视觉表现是渲染层的事两者解耦。所以我把能力拆成了四块数据层负责定义节点和连线的结构渲染层负责把数据变成画面交互层负责拖拽、连线、缩放这些操作布局层负责让散落的节点自动排列整齐。这四个模块之间只靠数据通信渲染层不关心业务含义布局层不关心视觉样式。这样每个部分都能单独测试、单独替换这是整个项目能一直改下去不翻车的前提。注意千万不要把坐标、颜色这类视觉信息硬编码到业务逻辑里。diagram-design 从第一天就定了规矩——业务只产出语义化的节点和连线坐标交给布局引擎样式交给主题配置谁都不越界。1.3 为什么选 Web 技术栈和 SVG 渲染技术选型上没有纠结太久。目标场景是嵌入内部文档系统和 Web 管理后台所以天然落在浏览器环境。渲染方案我对比过 SVG 和 Canvas如果是上万节点的大规模图Canvas 优势明显但它的事件处理和文本渲染都更麻烦而且导出为矢量图还得额外做序列化。diagram-design 面向的场景是几十到几百个节点的架构图、流程图这个量级 SVG 完全撑得住还能白嫖 DOM 事件、CSS 样式继承和稳定的文本测量能力。对比项SVGCanvas事件交互每个元素独立绑定事件天然支持需要手动做命中检测和坐标换算文本渲染浏览器原生渲染清晰可选中需要自己排版文本选中困难样式控制支持 CSS 和 class 批量换肤只能通过绘制参数控制数据导出可以直接序列化为矢量文件导出为位图放大有损耗性能上限数千元素开始明显吃力数万元素也能保持流畅对我这个项目来说SVG 的优势几乎全部命中痛点。唯一需要留心的就是元素数量上来之后的性能问题这个我放在后面的调优章节专门讲。2. 核心数据模型让图表成为可计算的结构2.1 节点、连线、画布的三层定义数据模型是整个 diagram-design 的地基。我把它分成了三层画布、节点、连线。画布定义整张图的尺寸、背景、视口状态节点定义图形元素本身连线定义元素之间的关系。下面是一份简化版的 JSON 示例{ canvas: { width: 1920, height: 1080, background: #ffffff }, nodes: [ { id: user-service, type: service, label: 用户服务, x: 120, y: 80, width: 160, height: 60, style: { fill: #e8f0fe, stroke: #1967d2, cornerRadius: 6 } } ], edges: [ { id: edge-001, source: user-service, target: order-service, label: 调用, routing: orthogonal } ] }节点里有几个字段值得展开说。id 必须全局唯一这是连线和以后做 diff 更新的基础type 我建议保留它决定节点的默认外形和可配置属性也方便后续做按类型批量处理x、y 存的是节点左上角在模型坐标系里的位置不是屏幕像素坐标style 是可选字段缺省时走全局主题。连线里我刻意不存死坐标只存 source、target 和 routing 策略具体折线由布局引擎算出来。这样做的好处是节点一移动连线能自动重算不会出现那种“线还留在原地”的尴尬局面。2.2 为什么要把样式和数据分开很多从零开始写图表工具的人最容易犯的错就是把颜色、线宽、字号这类样式直接塞进每个节点的数据里。短期看没问题一旦要说“把所有失败的节点标红”你就会发现要遍历整棵数据树去改颜色改完还得记得改回来。diagram-design 的做法是数据只管“是什么”样式交给主题层回答“长什么样”。我实现了一个主题对象里面定义了节点类型的默认配色、边框、圆角连线的颜色、粗细以及字体族和字号层级。节点数据里的 style 字段只是覆盖项优先级是显式 style 类型默认样式 全局主题。这样既能保证团队默认风格统一又允许特定节点做局部强调。后来这个机制还接上了暗色模式一行代码切换主题整张图跟着变靠的就是这套优先级设计。2.3 三套坐标体系模型、世界、屏幕坐标是图表编辑器里最容易翻车的地方我花了最多时间踩坑所以必须单独讲清楚。diagram-design 里同时存在三套坐标系模型坐标是图表数据本身使用的坐标世界坐标是经过缩放平移后展示出来的坐标屏幕坐标是相对浏览器窗口的坐标。正常情况下模型坐标在经过 viewport 变换后就与世界坐标重合只有滚动页面时才需要额外考虑屏幕坐标。这里给出一段最核心的换算代码也是整个项目里被引用最多的两个函数function modelToScreen(modelPoint, viewport) { return { x: modelPoint.x * viewport.scale viewport.offsetX, y: modelPoint.y * viewport.scale viewport.offsetY }; } function screenToModel(screenPoint, viewport) { return { x: (screenPoint.x - viewport.offsetX) / viewport.scale, y: (screenPoint.y - viewport.offsetY) / viewport.scale }; }viewport 里维护三个变量scale、offsetX、offsetY。所有鼠标事件拿到的都是屏幕坐标必须先用 screenToModel 换成模型坐标再去做命中检测和拖拽计算。我见过不少半成品编辑器拖拽时节点跟鼠标之间总有偏移十有八九就是漏了这层换算直接把屏幕坐标赋给了节点位置。3. 渲染与交互把数据变成能摸能拖的图3.1 渲染函数保持纯粹数据进DOM 出渲染层我坚持一个原则渲染函数必须是纯函数输入数据模型输出对应的 SVG 元素不带任何副作用。项目里维护了一张映射表key 是节点 idvalue 是对应的 DOM 元素数据变化时只更新差异部分而不是整张图重新渲染。这段思路用代码描述大概是这样的模式function renderNode(node, theme) { const el document.createElementNS(http://www.w3.org/2000/svg, g); el.dataset.id node.id; el.innerHTML rect x${node.x} y${node.y} width${node.width} height${node.height} rx${node.style.cornerRadius || theme.cornerRadius} fill${node.style.fill || theme.node.fill} stroke${node.style.stroke || theme.node.stroke} / text x${node.x node.width / 2} y${node.y node.height / 2 4} text-anchormiddle${node.label}/text ; return el; }SVG 里包裹在g元素中的一组图形移动节点时只需要改 transform 或者更新坐标属性不需要重建子元素。连线同理但是连线的生成依赖两个节点的当前坐标所以更新节点后要连带调用边更新函数。这一步在渲染实现里是坑最多的地方顺序错了就会看到“节点拖走了线还在原地”的画面。3.2 拖拽移动与连线命中检测交互层的核心是拖拽链路mousedown 记录起始点mousemove 更新位置mouseup 结束操作。在 SVG 里监听事件需要注意一点元素内部如果有多个子元素事件会被触发多次所以项目里统一用事件委托在画布根节点监听再通过event.target.closest([data-id])找到命中的节点。连线的编辑比节点麻烦。用户需要能把线的端点拖到另一个节点上这要求先做“端点命中检测”鼠标点击位置距离起点或终点小于一定阈值我用的 10px就进入连线拖拽模式。另外还要做“节点命中检测”也就是拖出来的线落在哪个节点上。节点命中相对简单遍历所有节点做矩形包含判断就行。真正容易忽略的是线的命中我写了一个点到线段距离的函数用向量投影的方式计算整个算法十几行但是交互体验直接从“只能点节点”升级到“能选中线并且拖动线的控制点”。3.3 缩放平移让视图围绕鼠标位置缩放浏览器原生的 wheel 事件默认是滚动页面图表编辑器里要拦截它改成缩放。很多初版实现直接用 scale * 1.1 这种粗暴方式结果就是缩放中心永远是画布左上角用户想放大某个角落得反复拖拽体验很别扭。正确的做法是让缩放中心跟随鼠标位置也就是保证缩放前后鼠标所指的那个模型坐标点在屏幕上的位置不动。function handleWheel(event, viewport) { event.preventDefault(); const factor event.deltaY 0 ? 0.9 : 1.1; const newScale clamp(viewport.scale * factor, 0.1, 8); // 先换算鼠标在模型坐标系中的位置 const modelPoint screenToModel( { x: event.clientX, y: event.clientY }, viewport ); viewport.scale newScale; // 缩放后让同一个模型点仍然出现在鼠标位置 viewport.offsetX event.clientX - modelPoint.x * newScale; viewport.offsetY event.clientY - modelPoint.y * newScale; applyViewport(viewport); }这段代码我修过不下三次每一次出问题都是 offset 计算时把新旧 scale 混用了。核心公式就一句offset 鼠标屏幕坐标 - 目标模型坐标 × 新缩放值。理解这个逻辑之后缩放平移就不会再出玄学般的漂移了。3.4 撤销重做与快捷键体系图表编辑如果没有撤销用户画错一步只能手动拖回去所以 undo/redo 必须做而且要做在数据层而不是 DOM 层。diagram-design 用了命令模式每一个操作都是一个命令对象包含 execute 和 undo 两个方法。移动节点的时候不是直接改节点坐标而是生成一个 MoveCommand里面记录旧坐标和新坐标。栈里按顺序压入命令撤销时执行 undo重做时执行 redo。快捷键这块其实是在模拟桌面绘图软件的习惯删除键删除选中对象CtrlZ 撤销CtrlShiftZ 重做方向键微调位置CtrlC/CtrlV 复制粘贴。粘贴的时候记得要给新节点生成新 id并且坐标偏移 20px 左右否则粘贴出来的节点会跟原节点完全重叠用户还得手动拉开。4. 自动布局与图表设计规范4.1 分层布局让流程图自动变整齐手拖出来的图总是歪歪扭扭自动布局的价值就在这里。diagram-design 里实现了一个简化版的分层布局法专门针对有向无环图。思路分四步拓扑排序确定节点层级同层节点按度排序减少连线交叉按层分配纵坐标、按序分配横坐标最后把连线折成水平垂直的折线。第一步拓扑排序能发现有没有环有环的图没法做标准分层我会降级成力导向布局作为兜底。第二步减少交叉听起来高级实际上我用的是重心法每个节点的位置取它相邻上层节点位置的平均值然后按这个值排序迭代几次效果就挺能看了。布局引擎跑完后所有节点都拿到 x、y 坐标再走一遍渲染流程就对齐了。这里有一个运用上的经验自动布局结果允许用户在局部手动微调所以布局引擎只负责“首次排布”后续用户拖过的节点要记录一个手动覆盖标志防止每次刷新都被打回原形。4.2 设计规范配色、间距、字体一个都不能少diagram-design 的名字里带着“design”所以视觉规范也是重头戏。我总结了一套适合技术图表的默认规范直接内置为主题。配色上不超过五种主色并且让颜色语义化标准节点用中性蓝高亮用绿色警告用橙色危险用红色禁用用灰色。语义固定下来后看图的人不需要读文字就知道状态这是信息传达效率的关键。间距上我采用 8px 栅格节点之间的最小间隔、连线与节点的安全距离、内边距全部是 8 的倍数。这类小细节肉眼不一定看得出差异但整体观感会舒服得多。字号的层级也要固定标题 16 到 18px正文 13 到 14px辅助说明 11 到 12px同层级永远一致。连线的原则是横平竖直45 度斜线只用在特殊标注上正交折线更符合技术图表的阅读习惯。语义用途推荐基准色值中性普通节点、默认边框蓝灰色系比如 #5f6b7a正常运行中、成功状态绿色系比如 #2e7d32警告降级、需要关注橙色系比如 #e65100危险故障、不可用红色系比如 #c62828禁用未启用、灰度灰色系比如 #9e9e9e这里我给的不是唯一答案但它背后有个原则颜色数量要克制语义要稳定。你完全可以用自己公司的品牌色替换色值但千万不要每个节点一个颜色那样图就没有层次了。4.3 导出能力SVG、PNG 和 JSON 快照图表画完总要交出去。diagram-design 的导出做了三个通道SVG 直接导出把画布内的 SVG 内容序列化外包一层svg标签加好命名空间就能另存PNG 导出走的是先把 SVG 绘制到 canvas再用 toDataURL 输出位图注意要给背景填充白色不然透明背景在某些文档系统里会很丑JSON 快照则把整个数据模型原样存下来这是最完整的归档格式以后还能重新打开继续编辑。JSON 导出还有一个隐藏好处图表进了版本管理系统。每次改动就是一次合规的代码 diff同事能直接在 merge request 里看到这张图改了什么这是传统绘图文件完全做不到的。我现在管图的方式跟管代码一样语义化修改、分支、合并整套流程都在数据层完成。5. 踩坑记录与性能调优5.1 高频 Bug坐标漂移、事件穿透、文本测量第一个高频坑是坐标漂移。现象是窗口缩放后节点和连线的相对位置乱了或者拖拽时节点突然跳走。根因通常是容器的实际尺寸和 viewBox 不一致或者没有在 resize 时重新计算 viewport。我的处理方式是把整个 SVG 放在一个可观测尺寸的容器里尺寸一变就基于当前视口中心重新换算 offset保证视觉中心不跳。第二个坑是事件穿透。连线上覆盖了控制点元素点击控制点的事件却冒泡到了画布导致整张图被拖动。解决办法是在控制点的事件处理器里显式调用 stopPropagation并且给这些控制点设置 pointer-events: all其他非交互元素设置 pointer-events: none让命中目标精确可控。第三个坑是文本测量。节点宽度要自适应文字长度但文字渲染前又需要先知道宽度典型的鸡生蛋问题。我的方案是维护一份 canvas 2D 上下文用 canvas 的 measureText 接口预先测量文本宽度再加上左右内边距得出节点宽度实测精度跟 SVG 渲染误差在 1px 以内这个方案简单又可靠。5.2 性能优化的三板斧当图表涨到几百个节点时不做优化就会有明显卡顿。我用的三板斧都很基础但效果显著。第一板斧是批量渲染所有数据变更先合并到下一帧统一执行配合 requestAnimationFrame避免一个操作触发十几次 DOM 更新。第二板斧是局部更新节点移动只更新该节点的坐标属性连线只更新关联的路径绝不整图画布重绘。第三板斧是视口裁剪只渲染视口范围内的节点视口外的节点用一个占位对象表示缩放平移时再按需补绘。做完这三件事diagram-design 在我的测试环境里800 个节点加 1200 条连线拖拽平移基本能稳定在 30 帧以上。这个量级对架构图、流程图来说完全够用。如果哪天要支持上万的规模那就是 Canvas 的战场了项目结构也预留了替换渲染层的接口不至于推倒重来。5.3 把图表变成工程资产的一些后续想法走到这一步diagram-design 已经不是简单的画图工具了它更像一个轻量的图表基础设施。我后续计划做的方向有三个一是图表联动点击某个节点其他相关节点高亮这在系统拓扑排查场景里非常实用二是模板系统把常用架构模式存成模板新项目直接套模板生成骨架图三是嵌入文档流水线文档仓库里放一个 JSON 片段构建时自动渲染成图片挂到页面图表永远跟代码同步更新。这些方向本质上都是同一个思路的延伸图表数据化之后它就不再是一张死图片而是可以被计算、被检索、被关联的工程资产。这也是 diagram-design 和普通绘图工具最大的分水岭。我个人在实际使用中有个很深的体会这个项目帮我改掉的不是画图方式而是看待图表的视角。以前拿到需求第一反应是“用哪个工具画”现在第一反应是“这份数据结构应该长什么样”。如果你也想做类似的东西我建议从小处着手先用一份干净的 JSON 把一张最简单的图渲染出来再慢慢往里加交互、加布局、加主题。每加一层你都会对“图表系统”这个命题理解得更深一点。最后再多说一句别急着追求一次性把功能做全先把那条“数据到画面”的链路跑通后面所有高级功能都会自然地找到自己的位置。
阅读完成 · 觉得有帮助？
