diagram-design 这个项目，我第一眼看到就觉得很对胃口。市面上不是没有画图工具，但如果你需要的是一个能嵌入自己业务系统、能控制每一个像素、能根据数据动态生成图形、大概率还要被二次开发的“图形基础设施”，那么现成的白板工具基本帮不上忙。diagram-design 就是这样一个面向研发者的图形设计/编辑系统：它不生产 PPT，也不替代 Figma，它提供一套从数据结构到渲染引擎再到交互手势的完整能力，让你在自家产品里拥有一个属于自己的“画布”。
这套系统能解决什么问题？本质上是三类：一是格式不统一，各业务线各画各的，流程图、架构图、时序图风格混乱；二是数据与图形割裂，图形只是“画出来的装饰”，改数据不能联动改图；三是交互体验差，缩放、拖拽、连线生硬，挂到真实项目里一用就露馅。适合谁来参考？想给自己的平台搭建图形模块的前端工程师、正在选型或者准备自研图形引擎的团队负责人，以及所有对“如何从零做一个画图工具”这件事有好奇心的开发者。
1. diagram-design 要解决的核心问题与整体设计思路
1.1 业务场景与“画图三痛点”
先聊业务场景。diagram-design 最初的需求背景很朴素：某团队内部需要一个统一的图形表达工具，用来承载数据流向说明、系统架构展示、流程编排预览这类内容。刚开始的方案是“各自画图、上传图片”，结果就是图片千奇百怪不说，一旦业务逻辑调整，就得重新画一张，维护成本非常高。后来逐渐形成了共识：我们需要一个“图形即数据”的工具，图形永远基于结构化数据实时生成，数据一变，图就跟着变。
在这个过程中，我总结出所谓“画图三痛点”，基本上是所有自研图形系统的共性：
- 数据结构混乱：不同图形各自为政，矩形有宽高属性，连线有折线信息，文本有字号字重。如果每一类图形都定义一套独立的数据格式，渲染时到处是 if-else，维护到后期必然崩。
- 渲染与交互脱节：很多起步方案直接拿 SVG 硬画，拖拽、缩放、框选都得自己从头写，做到一半发现性能不行，或者坐标计算对不上，进退两难。
- 扩展性不足：今天要加一种节点类型，明天要支持新的连线样式，如果引擎的扩展点设计得不好，每次加需求都要动核心代码，风险极高。
diagram-design 的破局思路很直接：先定义一套统一的图形描述协议，所有图形都是“数据对象”，再围绕这个协议构建渲染引擎和交互引擎，最后暴露清晰的插件机制给上层业务扩展。
1.2 技术选型：为什么坚持自研而非白板工具
技术选型这部分，很多人问过我：为什么不用现成的开源白板白板库，非要自己写？参考答案是这样的：现成方案在“通用能力”上确实强，但一旦你的需求触及这几个方面，自研反而是更合理的选择。
第一，数据融合能力。自研系统可以把图形数据直接接入业务数据结构。例如业务侧有一个服务节点，包含服务名、状态、下游依赖等字段。diagram-design 允许你把这些字段直接映射成图形属性，上游数据变更时，图形自动刷新。这不是导入导出层面的“兼容”，而是数据层面的“同源”。
第二，交互定制空间。通用白板库通常把交互都封装好了，你要改“双击进入文本编辑”的行为，可能要翻源码、打补丁。自研系统从事件源头就掌握在自己手里，连线的锚点吸附逻辑、右键菜单的策略、批量框选的范围判定，全部可控。
第三，性能与体积控制。通用库为了兼容各种场景，包里通常带着大量用不到的特性。diagram-design 只保留图形渲染、交互、布局三件事，核心包体积可以控制得很小，在弱网环境内嵌到后台系统里，加载压力小很多。
注意：自研不是盲目造轮子。如果你的项目只需要画几张固定模板图，不需要二次开发，直接用现成工具反而更合适。diagram-design 的选型前提是“图形模块是业务的长期基础设施”，这个判断很重要。
1.3 产品定位：图形编辑器还是图形引擎
这里有一个关键定位问题：diagram-design 到底应该做成图形编辑器，还是图形引擎？我花了很长时间才想明白——它的内核应该是一个引擎，编辑器只是引擎之上的一个预设形态。
为什么这么说？如果你做成编辑器，用户打开页面就是画布、工具栏、属性面板，大家会下意识拿它和成熟的画图软件去比较，这是必输的。但如果你做引擎，你提供的是一整套能力：节点定义、连线规则、渲染逻辑、交互事件、布局算法。业务方可以用这些能力快速搭建流程图编辑器，也可以组装出架构图渲染器，甚至可以做一个只读的图形展示组件。同一套内核，不同的装配方式。
diagram-design 的具体定位是“轻量级图形引擎 + 标准编辑器外壳”。引擎层负责图形描述、渲染、事件、布局，编辑器外壳则是一个默认实现，给用户提供可视化编辑体验。业务方如果不想要外壳，完全可以自己搭。
这样的好处非常明显：分工清晰、模块解耦、复用度高。引擎层不绑死 UI，编辑器只是入口之一，后续做移动端适配或者嵌入到其他系统中，都不需要动引擎代码。
2. 核心细节解析：数据结构与引擎架构
2.1 图形数据模型：JSON 描述一切
diagram-design 的核心设计决策之一是“一切图形皆 JSON 数据”。这句话听起来简单，但它直接决定了系统的复杂度上限。这里把数据模型拆开看。
一个节点的最小描述单位是GraphNode，包含三类信息：
- 身份信息：
id、type、parentId。type用于关联渲染器，决定这个节点长什么样；parentId用于支持组合、编组等层级结构。 - 几何信息：
x、y、width、height、rotation。所有几何属性统一使用相对坐标，避免绝对坐标带来的耦合问题。 - 业务信息：
data，一个自由对象，保存节点承载的业务数据。比如流程节点可以存状态、审批人；架构图节点可以存服务名、实例数。
连线在数据模型上是独立的GraphEdge，它存储起点节点 id、终点节点 id、锚点索引、路径点数组等。这样的好处是：布局算法可以单独操作连线，不需要侵入节点数据结构。
整体数据结构是一棵GraphModel树，包含nodes、edges、viewport三个字段。viewport保存视口变换信息，包括缩放比例、平移距离，保证保存/恢复时画布位置不丢失。
提示：设计这套结构时，最重要的一点是“不要为了省钱把数据揉成一团”。节点、连线、视口分开存放，后续做序列化、做局部更新、做协同编辑都会轻松很多。前期省事，后期还债。
2.2 坐标系统与渲染管线
图形系统最容易被新手低估的是坐标系统。diagram-design 使用三种坐标：
- 世界坐标：图形在画布中的真实坐标，后续布局算法、保存数据都用它。
- 视口坐标：经过平移缩放后实际渲染到屏幕上的坐标。
- 屏幕坐标：浏览器窗口坐标，主要用来处理鼠标事件、命中检测。
三者之间的转换核心公式是：
屏幕坐标 = (世界坐标 - 视口原点) * 缩放比例每次渲染时，引擎不再逐个节点计算变换，而是把整个画布的变换矩阵应用到最外层容器上，子节点只负责描述自己“在世界坐标里的样子”。这样渲染性能高，代码也简单。
渲染管线我用了分层策略：
- 底层网格层：提供背景网格、辅助线，用于辅助用户感知尺寸和对齐。
- 图形内容层：渲染所有节点。每种节点类型注册对应的渲染器函数，统一输入
GraphNode，输出渲染指令。 - 交互辅助层：渲染选中态、锚点、拖拽预览框等临时交互元素。这些元素不进入数据模型，只在交互过程中动态出现在屏幕上。
这种分层让渲染模块的职责非常单一。网格层不管节点，内容层不管选中框，辅助层不管业务数据。各层独立变化，互不干扰。
2.3 交互层与状态管理
交互是画图工具的“门面”。diagram-design 的交互层围绕“状态机”构建。基本状态包括：idle、hover、dragging、selecting、connecting、editing。
举个例子，拖拽一个节点的完整链路是：
- 鼠标按下时命中检测，找到目标节点，状态从
idle切到dragging。 - 鼠标移动时，计算世界坐标增量，更新节点位置，触发渲染更新。
- 鼠标抬起时，检查是否拖到组合容器内，处理编组逻辑，状态回到
idle。
这套状态机的好处是：每个交互行为都有明确的进入条件和退出条件，不容易出现“鼠标明明松开了节点还在飞”的诡异问题。所有状态转换产生的操作，统一包装成Command对象进入撤销栈，这一点对画图工具来说是刚需。
状态管理方面，我没有引入全局状态库，而是用事件总线加局部状态处理。图形数据是核心数据，保存在引擎内部的 Store 中；交互产生的临时状态，比如当前 hover 了哪个节点、框选区坐标是什么，只放在交互层局部变量里。两者严格分离，避免“画一笔到处响应”的混乱局面。
3. 实操过程：核心环节一步步落地
3.1 初始化工程与基础类型定义
这一节直接上实操。我们用一个 TypeScript 工程来落地 diagram-design 的核心骨架。
interface GraphNode { id: string; type: string; parentId: string | null; x: number; y: number; width: number; height: number; rotation: number; data: Record<string, unknown>; } interface GraphEdge { id: string; sourceId: string; targetId: string; sourceAnchorIndex: number; targetAnchorIndex: number; path: Array<{ x: number; y: number }>; } interface GraphModel { nodes: Record<string, GraphNode>; edges: Record<string, GraphEdge>; viewport: { zoom: number; x: number; y: number; }; }初始化时，一个最简的 GraphModel 就是三行空对象。这里要特别注意：nodes和edges用Record而不是数组。用数组的话，删除一个节点需要遍历查找；用Record，键就是 id，增删改都是常数级操作。后续做数据同步、做批量更新，这种结构优势非常明显。
3.2 图形属性组装与校验（BaseGraphSchema）
图形种类多了之后，最怕每个节点各写一套解析逻辑。diagram-design 用BaseGraphSchema解决这个问题的思路是：所有节点类型都要注册自己的“描述配置”，引擎统一按这个配置解析属性。
interface GraphSchema { type: string; defaultSize: { width: number; height: number }; anchors: Array<{ x: number; y: number }>; renderer: (node: GraphNode) => RenderInstruction; validator?: (node: GraphNode) => boolean; }每个新图形类型只需实现这份契约并注册到引擎，就能获得渲染、拖动、连线等全套能力。我在实践里遇到过很多次“图形属性不生效”的问题，排查到最后基本都是 schema 没注册或者注册时机不对。开发时最好加一个启动自检：遍历所有已注册 schema，检查 renderer 是否可调用，缺了就报错，避免运行时才暴雷。
3.3 事件总线与撤销重做实现要点
撤销重做是画图工具绝对绕不开的功能。diagram-design 的实现策略是把所有“改变数据”的操作统一描述成命令：
interface Command { name: string; redo: () => void; undo: () => void; }例如移动节点，redo 函数把节点坐标从旧值改成新值，undo 函数从新值改回旧值。实践中，每次交互开始前先记录快照，交互结束后根据快照与当前数据生成增量修改，再包装成 Command。这是最稳妥的方式。
实现撤销重做有两个关键的坑：
- 命令里不能保存对象的引用，要保存值。如果存引用，后续节点属性变了，历史记录里的数据也跟着变，撤销就失效了。
- 合并连续操作。用户拖拽节点时，鼠标每移动一步都产生一次坐标更新。如果每一步都入栈，一次拖拽会生成几十条撤销记录，用户按一下撤销却只撤回一像素的移动，体验极差。我的处理办法是：同一次交互过程中产生的连续命令，只保留第一条和最后一条状态，合并成一个命令。
注意：合并逻辑必须限定在同一次交互上下文里。比如用户在拖拽过程中还切换了画布缩放，那就不算连续，不能合并。
3.4 布局算法与自适应连线
布局算法这里，我的选择是先支持常见的分层布局，再逐步扩展。分层布局的核心是计算每个节点的层级和同层顺序，我可以给一个简单实现思路：
- 根据边的方向建立拓扑序列。
- 每一层的节点按入度、出度排序，尽量减少交叉。
- 同层节点均匀分布，层与层之间按预设间距排布。
自适应连线是一个更容易出彩的部分。连线默认使用正交折线，计算逻辑是：先获取起点锚点和终点锚点的坐标，再根据锚点方位决定折线的中间路径。这里有一个我踩过的真实坑：如果起点在节点右边，终点在另一个节点的左边，连线就会横穿整个画布。解决思路是对折线候选路径做简单路由检测，若检测到路径与节点矩形相交，则绕行偏移一个固定距离。
这个方案在图形规模不大时完全够用，而且代码量可控。对规模特别大的场景，才需要考虑引入网格化寻路算法，那是后话。
4. 常见问题与排查技巧实录
4.1 问题现象、原因与解法速查表
开发 diagram-design 的过程中，我积累了一批高频问题，整理了速查表，分享出来。
| 问题现象 | 常见原因 | 排查方法 | 解决预案 |
|---|---|---|---|
| 节点拖不动 | 事件未绑定到有效命中目标 | 在 mouse down 阶段打印命中结果 | 检查渲染层元素层级，确保命中区域的 z-index 正确 |
| 节点位置错乱 | 世界坐标与屏幕坐标混淆 | 在拖拽更新时打印两种坐标 | 统一使用世界坐标，仅在事件入口做坐标转换 |
| 撤销后图形位置不对 | 命令中保存的是对象引用 | 检查 Command 数据是否深拷贝 | 入栈前对变化字段做一次浅拷贝 |
| 连线不跟随节点移动 | 连线路径未订阅节点更新事件 | 确认节点移动后是否广播了更新 | 节点位置变化时触发对应连线重算 |
| 框选选中了不可见元素 | 命中检测未过滤隐藏节点 | 检查节点 hidden 属性 | 命中检测前先过滤非可见节点 |
| 缩放后文字模糊 | 渲染层未按缩放重绘 | 检查渲染时机是否依赖缩放值 | 缩放变化后调 requestRender 强制重绘 |
这张表看着简单，但每一条背后都是真实调试过的问题。比如坐标混淆这个问题，初期几乎每周都犯一次，后来强制规定了“任何事件回调拿到的坐标，先在入口处一次性转为世界坐标”，从此绝迹。
4.2 高频事故现场复盘
挑一个印象最深的事故现场聊聊。有段时间，连线锚点总是对不齐，节点明明在旁边，连线端点却飞出去很远。定位发现是锚点坐标用了相对节点左上角的偏移量，但是渲染连线时直接把它当成世界坐标用，少加了一次节点平移量。
这个事故的教训是：图形系统里的坐标转换链一旦断了一环，“看起来正常”和“真正正确”之间就差一个平移量。修好之后，我给所有坐标转换函数加了单元测试，专门把已知的世界坐标、视口坐标组合跑一遍，保证转换函数回归安全。
另一个场景是批量添加节点时页面卡死。排查后发现不是渲染问题，而是每个节点添加都触发一次完整重绘。解决思路是引入“脏标记”机制：每次操作只标记受影响区域，在下一个动画帧统一渲染一次，而不是立即重绘。这个优化之后，批量渲染效率提升了不止一个量级。
4.3 性能优化与 10 万节点渲染策略
谈到性能，必须直面一个目标：diagram-design 要做到十万节点不卡。这个目标听起来吓人，但实际渲染上可以借助分层、裁剪、缓存三板斧。
- 视野裁剪：只渲染视口范围内的节点。世界坐标统一后，判断一个节点是否在视口内非常快，直接比较边界矩形即可。
- 渲染缓存：对于短期内没有变化的节点，把渲染指令缓存起来，跳过重新生成的过程。数据变更时清理对应缓存，其他节点不受影响。
- 分片调度：当有大批节点需要更新时，不要在一个同步循环里全部渲染，而是分片放进渲染队列，每次只处理一小批，避免长时间阻塞主线程。
十万节点的性能测试，我实际跑过：在普通笔记本上，静态渲染的帧率稳定在 30 帧以上，交互操作时的响应延迟可以控制在合理范围内。达到这个效果的关键不在于用了什么超前技术，而在于每一层都做了“减法”：能不算的就不算，能缓存的就缓存，能裁剪掉的绝不多画一个像素。
结尾
我自己的体悟是：diagram-design 这种项目的价值不在于做出了一个好看的画图界面，而在于它把“画图”这件事拆成了可以管理、可以复用、可以测试的工程模块。画一个矩形很容易，画一万个不重样的矩形并让它们智能地连接、排列、响应交互，才真正体现功底。如果你也在做类似的事情，我的建议是不要着急堆功能，先把数据模型、渲染分层、坐标体系三件事夯实；这三块稳了，剩下的功能都只是时间问题。
最后再分享一个小技巧：做图形系统时，请养成随手给关键转换函数写测试的习惯。坐标、锚点、折线、命中检测，这些纯函数看起来很简单，但恰恰是它们最容易被后续改动误伤。我吃过一次大亏之后，对这些函数的回归测试覆盖率一直保持很高，后面所有新功能开发都顺畅了很多。
