diagram-design 是我去年一直在维护的一个个人项目本质是一套“图表定义即代码、渲染结果即标准 SVG”的轻量绘图与渲染引擎。很多同事问我已经有那么多成熟的绘图工具为什么还要自己写一个其实答案很简单在日常架构评审、接口说明和技术文档写作里我反复遇到三个老问题——画图太占据时间、需求一改动整个图就废、团队成员各画各的导致文档里的图越来越不可信。diagram-design 就是用来自洽这套问题的它适合正在做架构抽象、技术写作、前端可视化工作的开发者参考也适合对图形渲染管线感兴趣的人拿来做研究骨架。这篇文章我会把项目从定位拆解、数据建模、渲染实现到踩坑复盘完整展开希望能帮你复制或至少重构出自己的那套方案。1. 项目定位与核心思维拆解1.1 这个问题为什么值得自己动手开发中绘图的需求比想象中频繁画系统架构图、业务流程图、ER 图、部署拓扑图几乎每一项交付文档都离不开。用传统绘图软件时我们看起来是在画图实际上是在做双份维护一份维护真实的业务逻辑另一份维护图形文件本身。真正让人崩溃的场景是这样的某天架构调整需要把某个服务从单体拆成三个微服务原来画好的图要改二十多处连线。你用鼠标挪动一个节点另一边的线条乱掉了你手动重新排列布局整张图的空间比例又不协调了。如果图是用代码定义的比如写一行payment - order改起来就只是删一行、加三行的问题布局和连线交给渲染引擎处理。diagram-design 的核心思路就是把表达图意和绘制图形彻底分离让人只关注“有哪些节点、他们之间的关系是什么”使渲染层自动承担剩下所有事。再看协作场景。多人共同维护一份架构图时传统工具导出的文件在合并、比较、版本回退方面都非常困难。但源码形态的图定义天然可以走版本管理每次修改都是可 diff 的文本评审时可以直接看到某一次改动动了哪几个节点。这个特性对中型团队尤其有价值图不再是某个人脑中的私有知识而成为了团队共享的、可审计的资产。1.2 自研方案对比现成工具的真实考量决定自研前我做了不少对比分析市面上的方案基本分为三类云端绘图平台、桌面绘图软件、嵌入式的 JS 图表库。它们各自的优缺点我整理成了表格这也是我当时决策的主要依据。方案优势劣势适合场景云端绘图平台上手快、模板全、协作方便文件格式封闭、难以做自动化处理、离线支持弱非技术人员的快速草图桌面绘图软件功能完善、出版级效果版本管理困难、无法嵌入 Web 应用、改动成本高高精度视觉交付物嵌入式 JS 图表库功能成熟、生态好体积普遍较大、样式定制受框架限制、学习成本不低面向端上用户的复杂交互图diagram-design 自研路线轻量、纯 SVG、可离线、易嵌入、行为完全可控功能需要自己造轮子、初期开发量较大文档渲染、代码生成架构图、教学演示对比之后我确定了几条硬约束第一产出物必须是标准 SVG能无痛嵌入任意 HTML 页面第二总代码体积要控制在几十 KB 级别第三必须支持离线场景不能依赖云端服务第四要能被其他工具链二次调用暴露清晰的 API。这些约束用自研方式最容易满足同时还能在过程中完全掌握渲染链路的每一个细节。选择自研还有一个现实原因很多现有图表库的布局是“黑盒”出现问题无法从根源排查。自己实现布局引擎之后节点坐标是怎么来的、连线为什么走了那条路径都一目了然。对于需要深度定制图表行为的项目来说这种可控性远比引入成熟方案划算。2. 数据建模与语法设计2.1 用最小的 DSL 表达最复杂的关系diagram-design 的输入是一段轻量定义语言我把它设计成接近自然语言的声明式语法。设计原则是“只定义关系不定义位置”节点在哪由引擎自动计算。这样用户不需要知道任何坐标概念只需要描述有哪些东西、它们怎么相连。node 用户中心 { color: #3178c6 } node 订单服务 { color: #f59e0b } node 库存服务 用户中心 - 订单服务 订单服务 - 库存服务 : 扣减库存我选择这种文本语法而不是 JSON 或 YAML 的原因是手写效率最高。JSON 写一个图需要大量括号YAML 缩进则很容易出错而上面这种接近自然语言的描述几乎零学习成本。我只需要把节点名写出来关系用箭头表达可选的属性用花括号承接解析上也不会产生歧义。语法的解析过程遵循一条简化逻辑词法分析切割出 token语法分析识别出 node 定义块、关系定义块和属性块最后转成内部统一的图模型。整体解析器代码量控制在三百行左右核心原因是我刻意避免做泛化只对项目实际会用到的特性做支持。加新特性永远比做通用解析器省事这也是个人项目能够持续推进的关键。2.2 节点、连线、群组的内部数据模型解析完的图会被转成内部模型这个模型是渲染层和布局层之间的唯一契约。在设计模型时我参考了图论中“图由顶点和边组成”的基本定义数据类型用 TypeScript 来描述会比较清晰interface DiagramNode { id: string label: string width: number height: number x: number y: number style: NodeStyle groupId?: string } interface DiagramEdge { id: string source: string target: string label?: string style: EdgeStyle } interface DiagramGroup { id: string label: string bounds: Bounds nodeIds: string[] } interface NodeStyle { color: string textColor: string borderColor: string radius: number } interface EdgeStyle { strokeColor: string strokeWidth: number arrowType: solid | dashed | dotted }这里有个关键设计节点坐标x、y是运行时属性不是用户输入属性。用户输入阶段只填充id、label、style坐标和尺寸全部由布局阶段计算填充。尺寸的计算也遵循同样的原则因为节点的实际宽度取决于文字长度和边框内边距文字没有测量之前我们不能确定渲染结果所以“文本测量 - 尺寸计算 - 坐标布局”必须形成流水线。群组Group这个模型是后期加上的它解决的是模块归属表达问题比如“订单服务”和“库存服务”都属于“交易中台”这个逻辑分组。群组本质上是节点的矩形容器渲染时体现为背景框和标题。这个概念的加入让图的分层能力大幅提升能够表达“节点-群组-整图”的三级结构。2.3 布局引擎的定位规则与估算方式布局引擎的职责是从图模型的关系推导出每个节点的视觉位置。diagram-design 的初始版本使用分层布局算法思路与画有向无环图的经典分层方法类似但实现简化了很多核心只有四步。第一步是拓扑分层。从入度为 0 的节点开始逐层向下推进同一层的节点安排在同一个垂直坐标带上。如果图里存在环我会给环上的节点做一个层级校正保证至少有一条路径是持续向下的防止布局死循环。第二步是层内排序。同一层的节点按照“连向下一层的边数”和“对端节点在上一层的位置”综合排序目的是让连线尽量短减少交叉。第三步是坐标分配。层与层之间的垂直间距固定为 80 像素水平方向则根据节点的实际宽度动态排布每个节点左右保留 40 像素的间距。第四步是边的路径规划。普通连线使用直线或二次贝塞尔曲线群组边界处做矩形的 border 避让避免线条穿过容器框。因为尺寸计算依赖文本测量内部宽度估算我采用了一个稳定的技巧先把节点 Label 放进一个隐藏的 SVG 文本元素测量 getComputedTextLength()然后叠加内边距得到实际宽度。这个测量结果在不同字体的渲染环境中都能保持一致因为 SVG 文本测量本身就是基于最终渲染字体的。3. 渲染层实现与核心逻辑3.1 从数据到 SVG 元素的完整渲染管线渲染层接收布局后的图模型把它映射到 DOM 上。整个管线可以拆成三个阶段容器初始化、元素生成、尺寸自适应。容器初始化阶段我会在目标 DOM 节点内部创建一个svg元素设置好viewBox和命名空间。这里要特别强调的是SVG 的坐标系统是基于当前视口的如果没有正确设置viewBox缩放和居中就会非常别扭。我的做法是先计算所有节点和群组的整体边界然后以边界的最小值作为原点偏移把整个图平移到坐标系的第一象限。元素生成阶段我按照“群组 - 边 - 节点”的顺序创建 DOM 元素。先画群组背景再画连线最后画节点这样能够让节点始终覆盖在边之上视觉上不会被穿线干扰。function renderToSvg(model, container) { const svg createSvgElement(model) const bounds computeBounds(model) svg.setAttribute(viewBox, ${bounds.x} ${bounds.y} ${bounds.width} ${bounds.height}) model.groups.forEach(group renderGroup(svg, group)) model.edges.forEach(edge { const path createEdgePath(edge) svg.appendChild(path) if (edge.label) svg.appendChild(createEdgeLabel(edge)) }) model.nodes.forEach(node svg.appendChild(createNodeElement(node))) container.appendChild(svg) return svg }尺寸自适应是整个渲染流程里最容易出问题的一环。开发初期我把图的真实边界运算漏掉了导致节点一多就出现边缘被截断的现象。后来我在渲染完成后统一执行一次getBBox()遍历计算出所有元素的实际包围盒再反向调整 SVG 的宽高和viewBox。这个做法效果稳定而且在导出 PNG 时也能天然复用不需要二次测量。另一个关键点是边标签的处理。边标签不能直接叠加在节点之上否则会遮住节点内容。实现时我计算连线的中点然后偏移一个固定距离同时将标签背景设为不透明这样就形成了文字浮在线上的效果。3.2 拖动、缩放与选中态的实现要点静态的 SVG 只是第一步交互能力才是让图真正可用的关键。diagram-design 支持的交互包含三类节点拖动、画布平移缩放、节点选中态高亮。节点拖动核心是坐标重新计算。监听 pointerdown、pointermove、pointerup 三个事件拖动时直接把节点的x、y改成“鼠标当前坐标减去按下时鼠标相对节点的偏移”。这里有一个容易踩的坑SVG 内的坐标需要经过 viewBox 比例换算不能直接使用屏幕坐标。我封装了一个坐标转换函数把屏幕坐标通过当前 transform 的逆矩阵换算成用户空间坐标。画布平移缩放我用的是 SVG 的 transform 属性而不是去修改每个节点的坐标。这样做的优势是平移缩放只影响视觉呈现底层模型数据始终不变任何时刻导出 SVG 都能拿到干净的原始坐标。缩放中心以鼠标指针位置为基准公式是保持“鼠标指向的图内容点”在缩放前后相对屏幕位置不变这个体验是最自然的。选中态高亮的实现比较直接在节点元素上增加事件监听点击后给节点增加.selected类名通过 CSS 控制描边加粗和投影。因为节点元素是独立生成的 SVG 子元素CSS 选择器可以直接作用不必做复杂的对象查找。3.3 主题系统与导出能力的设计取舍主题系统解决的问题是“同一套图在不同文档里需要不同观感”。我把颜色、圆角、字重、间距都抽成了可配置的 Theme 对象用户通过构造参数覆盖默认值。interface DiagramTheme { nodeColor: string nodeTextColor: string edgeColor: string groupBackground: string groupTitleColor: string fontFamily: string nodeRadius: number horizontalGap: number verticalGap: number }有了主题系统之后适配深色模式就变成换一个 Theme 对象这么简单。我实际使用最多的是两种主题面向打印文档的浅色主题以及面向夜间展示的深色主题。切换主题不需要重新解析 DSL只要重新执行渲染函数即可模型层的独立性在这里体现出了价值。导出能力分两步走。SVG 导出最直接把当前 SVG 元素的outerHTML序列化后交给用户下载即可。PNG 导出稍微复杂需要利用 Canvas 的drawImage()方法把 SVG 绘制到画布上再调用toDataURL()。这中间有个大坑如果 SVG 内部引用了外部字体或图片Canvas 在绘制时会因为跨域或资源未加载而输出空白图。实践中的解决办法是把字体样式内联到 SVG 里并提前等待图片资源完成加载。4. 实操过程从零创建首个可用的 diagram-design4.1 分阶段推进的开发路线整个过程我分成五个阶段推进每个阶段产出可运行的最小模块这能避免做了很久却什么都看不到的挫败感。第一阶段只做 DSL 解析命令行输入定义文件输出 JSON 图模型。第二阶段做渲染把图模型画成无样式的 SVG此时不求好看只求元素数量和位置正确。第三阶段做布局引擎实现分层排布和连线避让。第四阶段做交互和主题。第五阶段做导出和性能优化。每个阶段都有明确的验收标准。第一阶段的标准是“任意合法图定义都能无报错地得到 JSON”第二阶段是“节点不重叠、连线不跨节点”第三阶段是“层次清晰、交叉尽可能少”第四阶段是“拖动、缩放都能保持坐标正确”第五阶段是“千节点图渲染耗时低于 150ms”。4.2 核心代码逐步解析解析器是最先写的模块核心函数很精简用正则和循环配合完成。我刻意没有引入任何第三方解析库因为语法足够简单手写反而更好控制。function parse(source) { const model { nodes: [], edges: [], groups: [] } const lines source.split(\n) let currentNode null for (const rawLine of lines) { const line rawLine.trim() if (!line || line.startsWith(#)) continue const nodeMatch line.match(/^node\s([\w\u4e00-\u9fa5-])\s*\{?\s*$/) if (nodeMatch) { const node createNode(nodeMatch[1]) model.nodes.push(node) currentNode node continue } const groupMatch line.match(/^group\s([\w\u4e00-\u9fa5-])/) if (groupMatch) { const group createGroup(groupMatch[1]) model.groups.push(group) currentNode null continue } const edgeMatch line.match(/^([\w\u4e00-\u9fa5-])\s*-\s*([\w\u4e00-\u9fa5-])(?:\s*:\s*(.))?$/) if (edgeMatch) { model.edges.push(createEdge(edgeMatch[1], edgeMatch[2], edgeMatch[3])) continue } const propMatch line.match(/^(\w)\s*:\s*(.)$/) if (propMatch currentNode) { currentNode.style[propMatch[1]] propMatch[2].trim() } } return model }这段代码最值得关注的设计是正则顺序节点声明、群组声明、边声明、属性声明依次匹配顺序不能颠倒否则容易误判。属性只会作用在当前节点上所以用一个currentNode指针来跟踪上下文。这种写法牺牲了一定的扩展性但换来了解析过程的高度确定性配合中文和英文节点名的双字符集支持实测解析 500 行定义文件耗时不到 2 毫秒。布局引擎的实现核心是把分层结果换算成真实坐标。这里有一个需要仔细考虑的细节同层节点的高度可能不同层高应该取当前层最大节点高度加固定间距而不是所有层都用同一个高度。function layout(model) { const layers topoSort(model) let yCursor 0 let maxWidth 0 for (const layer of layers) { let xCursor 0 let layerHeight 0 for (const node of layer) { node.x xCursor node.y yCursor xCursor node.width theme.horizontalGap layerHeight Math.max(layerHeight, node.height) } maxWidth Math.max(maxWidth, xCursor) yCursor layerHeight theme.verticalGap } return { width: maxWidth, height: yCursor } }这段代码的实践启示是最小可行版本不需要引入复杂的力导向算法。先做层次布局跑通全流程之后如果需要更自然的排布再去替换布局模块。替换的成本很低因为布局模块的输入输出边界已经定义清楚了。渲染节点的时候我采用“外层g 内层recttext”的三层结构。g负责承接拖拽事件rect负责背景和边框text负责文字。文字默认居中通过text-anchormiddle和dominant-baselinecentral两个属性实现这两个属性是 SVG 文本垂直水平居中最省事的方案。4.3 性能优化与资源占用控制图表渲染的性能瓶颈通常不在绘制本身而在节点数量和布局计算的算法复杂度。diagram-design 通过三条策略把性能控制在了可接受的范围内。第一布局计算中用 Map 存储节点索引避免在循环里反复做数组查找。边的数量可能达到节点数量的平方级如果每条边都要遍历所有节点来找坐标复杂度会爆炸。const nodeMap new Map() model.nodes.forEach(node nodeMap.set(node.id, node)) // 后续所有边的端点查找都走 nodeMap.get()第二渲染时使用DocumentFragment或一次性innerHTML拼接。SVG 元素创建本身就是开销较大的操作逐个appendChild会频繁触发重排。我最终选择了 innerHTML 方式生成字符串后一次性插入容器实测渲染 800 个节点加 1200 条边的图耗时从 420ms 降到了 130ms 左右。第三交互过程中做节流处理。拖动节点时渲染频率限制在每秒 60 次同时只在 pointermove 事件里更新被拖动节点的x、y属性不触发全图重摆。经过这几轮优化最终在千节点规模下拖动的帧率稳定在 50fps 以上完全满足日常使用。5. 常见问题与排查心得5.1 开发中反复出现的六个问题项目从雏形到稳定版本踩过的坑数量不少我挑出最有代表性的六个整理成速查表后面再展开讲其中三个最隐蔽的。现象直接原因解决方式导出 PNG 时文字消失SVG 内字体未被 Canvas 感知将字体样式内联到 SVG 根节点拖动节点后连线错位边坐标未随节点坐标更新统一从图模型读取端点坐标杜绝重复缓存文本宽度测量偏差测量时字体未加载完成等待document.fonts.ready后再布局大图滚动卡顿平移缩放事件未节流对 transform 更新做 rAF 节流群组背景遮盖节点渲染顺序错误强制先渲染群组再渲染边最后渲染节点特殊字符导致解析失败正则未覆盖转义场景节点 ID 规范化处理非法字符自动替换为连字符5.2 三个最隐蔽的问题的定位过程文本测量偏差这个问题非常折磨人。症状很离奇同一套代码在本地浏览器里一切正常部署到某些用户的浏览器里节点宽度就会偏窄导致文字溢出边框。排查到最后发现测量节点宽度的时机正好在自定义字体font-face加载完成之前浏览器用回退字体测量出了错误的宽度。解决方案是在布局前执行一次await document.fonts.ready确保所有字体资源就绪后再开始测量。这个问题对大多数图表库都有效值得收藏备用。第二个隐蔽问题是拖动节点的“幽灵连线”。拖动过程中被拖动的节点确实到了新位置但连接它的边还停留在旧位置视觉上像是一条断开的线拖着残影。根因是边元素的路径在节点坐标更新后没有被重新计算。我的修复方案就是统一从图模型读端点坐标不维护任何画布局部变量。这种“单一数据源”原则看起来是基本功但实际操作中为了性能写出来的冗余变量常常会成为这类问题的温床。第三个问题是群组背景和节点之间的遮挡关系。初次实现时我把群组背景当作普通元素按顺序添加渲染结果往往是群组盖住了节点。SVG 的绘制顺序就是文档顺序这和其他图形系统完全一致没有任何 z-index 概念。所以规定一套“先背景、再连线、最后节点前景”的固定顺序规则并且在代码注释里写清楚“不要改顺序”这个问题就不再出现。5.3 排查方法论的沉淀这些坑踩下来之后我总结出一个适用于图形渲染项目的排查套路现在遇到定位问题效率高了很多。第一步是复现最小案例把问题图精简到两三个节点排除数据量干扰。第二步是导出中间 JSON手工检查坐标是否合理判断问题出在数据层还是渲染层。第三步是给渲染函数加断点把每个阶段的输出打印出来对比比如布局前的模型、布局后的坐标、最终的 SVG 字符串。最后一步才是翻浏览器 devtools排查样式和事件问题。这种方法论的核心是把责任分层。出现渲染异常时先确定是哪一层出了问题而不是漫无目的地调试。每一次问题都往分层边界上归因长期下来整个系统的可维护性也会越来越高。我后面还会把这个项目扩展成支持自定义图形组件和流程图交互编辑的版本目前的架构里布局引擎和渲染器是完全解耦的新增交互模式不需要动渲染核心。单独说一个小的实操心得如果你也打算做类似的图表工具一定优先把“导出结果可预测”当成第一目标用户在意的从来不是引擎内部多华丽而是任何输入都能得到稳定、干净的输出。小的做法是每天提交前自动跑一遍二十张样例图的回归脚本有一张图渲染结果和上次不同构建就标红。这招看起来笨但确实是我用过的最能保证图表工具质量的办法。
