企业官网建设流程全解析

diagram-design 这个项目，当初立项时一句话就能说清楚：让开发团队画架构图、流程图、部署拓扑时，不再切到第三方在线白板，也不用手绘草图跟文档脱节。但真正动手去做，才发现“图表设计”这个标题背后，藏着一整套图编辑器的核心问题——从数据模型、渲染机制、交互手感，到自动布局、序列化、撤销重做。这套东西做好之前，画图工具就只是“会动的画板”，做好之后才是能支撑业务的设计系统。这篇文章就把我在 diagram-design 里的完整设计思路和实操过程整理一遍，适合正在做图编辑类工具、或者准备入门前端图形渲染方向的朋友参考，也适合后端同学理解这类项目为什么这么重。

1. 项目定位与技术选型，先想清楚“画什么图”

很多人一听到“图表设计”就默认是 ECharts 那种数据可视化图表，其实 diagram-design 这类项目更贴近图形化编辑工具，类似在线白板、架构图编辑器、UML 工具。它的核心不是把数据渲染成图表，而是让用户自由摆放节点、连线、加备注、调整样式。这个定位直接决定了后面的所有技术路线。

1.1 需求拆解：四类图必须原生支持

项目调研阶段，我统计了团队内部的真实使用场景，最后收敛出四类必须支持的图：架构图（系统模块、服务调用关系）、流程图（业务审批、状态流转）、部署拓扑图（服务器、网关、中间件）、思维导图（需求拆解、知识整理）。这四类图侧重点不一样，架构图强调层级和分组，流程图强调节点之间的顺序，拓扑图强调设备和链路，思维导图强调从根节点向外发散。

如果对每一类图都单独开发一套交互，工作量会翻好几倍。我的方案是抽象出一个统一的图数据模型，把所有图都表达为“节点+连线”的组合，再通过不同类型的节点样式、连线规则和布局算法区分场景。例如流程图的节点是矩形加箭头，思维导图的根节点在左侧自动向右发散，但底层的拖拽、缩放、选中、编辑逻辑完全共用。

1.2 技术选型：为什么用 Canvas 而不是 SVG

渲染方案纠结了很久。SVG 的优势是 DOM 天然支持事件绑定和 CSS 样式，单个节点做动画很方便；Canvas 的优势是节点数量上千之后依然能保持稳定帧率，绘制自由度更高。考虑到架构图和拓扑图经常出现几百个节点的规模，我最终选择了基于 Canvas 的二次封装方案，把节点的命中检测和事件派发自己做掉。

选 Canvas 的另一个原因是这个项目里节点大多是矩形、圆角矩形、折线箭头，这些图形用 Canvas 路径 API 很容易绘制，不需要依赖额外的图形库。实际开发时我也没有直接引入一个重型图形引擎，而是自己封装了一个轻量渲染层，只绘制需要的图元。好处是包体积小、逻辑全在自己手里，排查问题的时候不用去翻别人的源码。

提示：如果项目里同时需要大量富文本节点、DOM 弹窗、内嵌网页，SVG 反而更省事。Canvas 方案在文本排版上会比较痛苦，需要自己处理换行、行高、字体测量。不过这个项目里的节点文本都很短，所以 Canvas 的缺点被控制在了可接受范围。

技术选型最终定为：TypeScript + Canvas 2D + 自研渲染层 + 自研图数据模型。核心不依赖任何大而全的图形框架，但交互细节参考了主流图编辑器的行为设计。

2. 数据结构设计，先让图“能存下来”

很多图编辑器做到一半就推翻重来，问题出在最开始的数据结构没设计好。图数据看起来简单，就 node 和 edge 两张表，但如果要支持分组、折叠、多选、撤销、撤销重做、多页画布，一开始不把模型设计清楚，后面每一步都在打补丁。

2.1 图模型：node、edge、port 三件套

第一个版本我以为只需要 node 和 edge。真到了画流程图的时候才发现，连线不应该只记录“从节点A到节点B”，而应该记录“从节点A的某个出口到节点B的某个入口”，否则后期做锚点吸附和自动布线完全没有依据。于是引入了 port 的概念，每个节点可以有多个输入输出端口，连线实际连接的是 port 而不是 node。

在数据模型层面，我定义了三层结构：Graph 包含 nodes、edges、groups；Node 包含 id、type、position、size、style、ports；Edge 包含 id、sourceNodeId、sourcePortId、targetNodeId、targetPortId、waypoints。这里的 waypoints 是折线的拐点数组，手动拖拽连线的路径会被记录在里面，自动布局时则不使用这个字段。

这样的模型可以直接 JSON 序列化，持久化到后端。同时撤销重做不需要记录画布快照，只需要记录每次操作的逆操作，这对数据量和性能都更友好。但注意第一步要把 id 的生成规则统一，我用的是有序自增 ID，因为撤销树里需要通过 id 找到对应对象，用随机字符串也能用，但肉眼调试时很不友好。

2.2 图层与分组，架构图的刚需

架构图里经常需要把一组服务框在一个大容器里，这个容器在视觉上是大圆角矩形，在逻辑上是 group。为了支持这个需求，我在普通节点之外增加了 group 节点类型，group 可以包含普通节点和其他 group，形成树形层级。渲染时先绘制深层 group 背景，再绘制其内部节点，最后绘制连线，这个顺序不能乱。

分组的难点在于判断“一个节点是否应该归属某个 group”。我采用的做法是：移动节点时，如果节点完全落入某个 group 的边界，且当前没有处于分组容器内部，就自动把该节点加入这个 group；如果节点被拖出 group 边界，就自动从 group 里移除。这套逻辑做出来之后，架构图的维护体验提升非常明显，比手动设置父子关系好用得多。

外层 group 上的文字我做了居中显示，内部节点太多时自动缩小字号。这里要提醒一下，group 的尺寸变化不能由内部节点自动撑开，因为架构图的容器边界往往有严格语义，我提供的是手动拖拽调整 group 尺寸的能力，避免用户被“自动撑开”搞到布局失控。

2.3 序列化与历史记录，版本控制的基础

预览版只有内存数据，刷新就丢，领导看演示时直接翻了车。后来我把序列化拆成两层：画布层（视口位置、缩放层级、背景开关）和内容层（节点、连线、分组）。保存时内容层单独输出成 JSON，画布层只在本地存储时记录，这样多人协作时不会因为各自视口不同而冲突。

历史记录用的是操作栈，不是快照。每个操作都实现 execute 和 undo 两个方法，例如“移动节点”的 undo 是把节点坐标改回去，“删除节点”的 undo 是恢复节点及其关联连线。这个方案比快照内存占用小得多，但需要开发时非常克制，所有对数据的修改都必须走命令模式，不能直接改模型。团队协作时，这也是一个硬性约束。

实操心得：所有修改模型的操作都要走统一入口，比如一个 moveNodes(nodes, deltaPosition) 的方法。不要为了省事直接在事件回调里写 this.node.x = e.dx，否则撤销重做必定崩。

3. 渲染核心机制，白板性能的分水岭

数据模型再漂亮，渲染跑不动也没用。Canvas 渲染在这个项目里我踩了不少坑，重点集中在视口变换、重绘策略、绘制顺序三块。

3.1 坐标体系与视口变换

我维护了三个坐标系：数据坐标（节点的真实业务坐标）、世界坐标（数据坐标加上画布缩放）、屏幕坐标（最终渲染到 Canvas 的坐标，考虑平移和缩放）。所有节点的存储值都是数据坐标，渲染时统一乘以缩放比例再加上偏移量。这样设计的好处是缩放操作不会污染数据，导出 JSON 时保存的永远是业务真实坐标。

举个例子，节点位置是 (100, 100)，画布缩放到 200%，平移到 (50, 30)，那么屏幕坐标就是 ((100+50)*2, (100+30)*2)。当鼠标点在屏幕坐标 (360, 280) 时，反向换算成数据坐标则是 (360/2-50, 280/2-30) = (130, 110)。这个换算贯穿所有交互逻辑，务必用一个公共模块做，不要在每块业务里重复写。

3.2 重绘策略，不要一有操作就全量刷新

初版代码里，每移动一个节点就调用 canvas.clearRect + drawAll，节点上百以后拖动起来掉帧严重。后来我改成局部重绘：维护一个 dirty 数组，任何操作只把受影响的范围坐标推入数组，每帧合并这些矩形区域，只重绘区域内图形。但这个方案在连线跨区域时有遗漏风险，比如节点移动只重绘节点周围区域，但连线另一端还在很远的地方，线就拖出残影了。

最终我采用了一套折中策略：普通移动节点时，记录节点旧位置和新位置的外接矩形，并把该节点关联的所有连线两端坐标也扩进矩形区域，然后做合并重绘；当拖拽结束之后，再做一次全量绘制校准。这个方案兼顾了性能和正确性，实际测下来 500 个节点拖拽也能维持流畅的交互感。

3.3 绘制顺序，绝不能乱

Canvas 没有 DOM 层级，所有图形按照调用顺序一层层往上叠加。我的绘制顺序固定为：画布背景（网格点）、group 背景、group 边框、普通节点、边连线的底层、边连线的文字标签、选中态高亮层、正在拖拽的预览线、右键菜单和提示框。这个顺序之所以重要，是因为选中高亮必须盖在节点上，但右键菜单必须盖在高亮上，错一步视觉就乱套。

绘制阶段我把每个图形的绘制方法拆成独立函数，比如 drawRectNode、drawImageNode、drawFlexLine，每个方法都接受坐标和样式参数。这里强调一个细节：Canvas 的描边和填充比例要一致，否则放大到 200% 时线条粗细变化明显，用户会觉得图变“脏”了。我的解决方案是线条宽度用数据坐标宽度除以缩放比例，保证渲染出来的像素宽度恒定。

4. 交互实现的关键细节，手感是打磨出来的

用户对图编辑器的第一印象不是功能多不多，而是好不好拖。拖拽跟手、连线顺滑、框选不卡，这些细节决定了工具有没有人用。交互部分花费的时间远超预期，大概占整个项目周期的四成。

4.1 拖拽、缩放与平移

节点拖拽的第一版存在鼠标加速问题，节点总比光标慢半拍。原因是 mousemove 事件的坐标变化量和节点位置变化量之间有一层视口换算，忘了把缩放比例加进去。修正之后手感明显变好。另一个细节是拖拽时默认移动的是选中集合里的所有节点，用户按住某个节点拖动时，组内其他节点要跟着一起动。

画布缩放和平移我默认用的是鼠标滚轮缩放 + 空格/中键拖拽平移。滚轮缩放始终以鼠标所在点为缩放中心，这个规则非常重要，因为用户习惯“看图放大我要看的局部”，如果始终以画布中心缩放，用户第一下就会迷失。实现方式是在滚轮事件中，把鼠标所在的屏幕坐标换算成数据坐标，然后以这个点为锚点调整视口偏移。

4.2 连线交互，最容易被低估的复杂度

连线功能不是简单的画一条线，要处理发起位置（从哪里拖出来）、预览线、目标吸附、折线拐点计算。我在节点上预置了一组默认端口：矩形节点上下左右各有一个端口，连线拖出时先靠近哪个端口就高亮哪个端口。如果用户从节点空白处拖出连线，则自动选择距离最近的方向端口。

吸附逻辑用了一个简单的距离阈值：当鼠标距离某个端口中心小于 12 像素时，认为吸附到该端口，预览线终点自动锁定到端口中心。折线拐点计算用的是曼哈顿路径算法，先尝试简单的水平垂直折线，如果两端在 Y 轴上有重叠区域就生成两段折线，否则生成三段折线。连线完成后，用户还可以拖动线上任意拐点微调路径，waypoints 字段会同步更新。

提示：连线预览时不要把每条移动轨迹都推入历史栈，否则一次连线会生成二十多步撤销记录。我是在 mouseup 完成连线时才把整个连线操作推入单一撤销步骤。

4.3 框选与多选

框选用橡皮筋矩形实现，但这个矩形要区分正向拖拽和反向拖拽。正向拖拽（左上到右下）要求节点完全包含在矩形内才算选中，反向拖拽（右下到左上）只要节点与矩形相交即可选中。这个细节很多人不知道，但用户直觉上是这样期待。按下 Shift 点击节点可以追加或移出选中集合，这个逻辑也比较常规，但要注意与框选的组合状态，我专门维护了一个 selectionManager 来管理选中集合的变化。

框选过程中我默认不实时平移画布，因为框选框选的同时处理滚轮平移，状态太容易混乱。取消框选的时机是 mouseup 且鼠标未移动过多距离，如果只是单击画布空白处，应该同时清空所有选中。

4.4 快捷键与右键菜单

快捷键我用了一个全局键盘事件监听器，但只在画布聚焦时生效，避免输入框打字时误触发删除。删除键、复制粘贴、撤销重做、方向键微调这些是必备的。方向键微调默认每次移动 1 像素，按住 Shift 时移动 10 像素，这是很多设计工具的习惯，用户上手成本很低。

右键菜单我自绘了一个简易浮层，包含复制、剪切、粘贴、层级上移/下移、自动布局、导出选中图等操作。右键菜单的难点在于点击空白处要自动关闭，以及菜单内部点击不能触发画布的事件冒泡。解决方案是统一事件处理：画布上的 pointerdown 事件如果发现当前坐标不在菜单区域内，就先关闭菜单再处理画布逻辑。

5. 布局算法的选型与落地，让图“自动长好”

自动布局在画架构图、思维导图时特别有用，用户把节点拖出来，点一下自动布局，图立刻整齐。这个功能听起来高级，但落地时需要在算法策略上做取舍。

5.1 树形布局，思维导图的正确打开方式

思维导图用的是经典的树形布局，根节点在左侧，子节点向右铺开。布局过程分三步：先计算每个子树的总高度；再递归确定每个子节点的垂直偏移；最后把相对坐标映射到画布全局坐标。这一步原理不复杂，但实现时要注意同一父节点的子节点间距不能恒定，应该根据子树高度动态分配，否则深度不同的节点会重叠。

树形布局支持横向展开和纵向展开两个方向，横向展开时层级按 X 轴递增，纵向展开时层级按 Y 轴递增。我把布局算法抽象成 config 配置，树间距、层间距、是否显示连接线均可调，这样后续给不同场景做预设就非常方便。

5.2 力导向布局，拓扑图的“均值回归”

部署拓扑图如果节点太多，手动拖到合理位置很痛苦，我引入了力导向布局。基本原理就是用斥力保证节点不重叠，用连线弹簧力把关联节点拉近，迭代几十次后趋于稳定。实现时我不建议完全照搬教科书公式直接迭代几百轮，那会让图旋转漂移，用户找不到北。我的做法是：固定根节点或重点节点不动，只对其他节点做力模拟，迭代 100 次左右就停止，然后把布局结果推入撤销栈，用户不满意可以一键撤回。

力导向布局还有一个参数调优问题：斥力系数太大会导致整个图四散，太小会重叠。我提供的默认参数是斥力系数 0.3、弹簧系数 0.1，最大位移限制 10，实测中小规模图效果不错。但要注意拓扑图中部分设备节点位置有强语义，比如网关一定在最上方，这些节点需要加锁定标志，布局时跳过。

5.3 手动拖拽与自动布局的协调，别让算法抢用户主权

自动布局最忌讳的事，是每次保存或刷新都重新跑一遍布局，把用户辛苦微调的位置全部覆盖。我的策略是：布局算法只作为一次性命令执行，布局完成之后就把结果写死到节点坐标上，后续任何自动布局都不会隐式触发。只有用户明确点击“重新布局”才会再次执行。

另一个细节是自动布局之前需要先移除已经被用户手动调整过的人工拐点，否则布局结果和人工路径互相冲突。操作前我会弹一个确认框：是否保留手动折线？默认选择“不保留”，因为这种场景通常是用户想要重新排版。

6. 实战踩坑与排查技巧，能救一个是一个

这个项目从开发到内测，我至少踩了几十个坑，挑几个有代表性的分享。这些问题如果不注意，等到用户量上来再改，代价会很惨痛。

6.1 节点高亮太多导致卡顿

初版实现中，鼠标移入节点就高亮节点，移走后取消高亮，同时触发重绘。当鼠标在连线密集区域快速扫过时，高亮状态频繁切换，每帧都在全量重绘，帧率直接崩到个位数。排查后解决方案是：高亮状态只要变化，进入下一帧合并渲染；同时对鼠标移入移出做 50ms 的防抖，避免误触。另外高亮层的绘制只重绘高亮节点和外接矩形区域，不再全量重绘。

6.2 连线端点与节点中心不一致

内测阶段有用户反馈：从节点中心连线看不出是哪个端口，而且折线起点不在节点边缘，视觉上像“断线”。原因是首次实现里连线端点用了节点中心坐标，没有考虑端口偏移。修复方式是：从节点中心算起，先找到与目标方向一致的边界交点，再把连线端点定位到边界交点，如果这条连线由端口发起，则直接定位到端口中心。流程图看起来就正常了。

6.3 导出图片时字体和图标丢失

导出功能我用的是 Canvas 的 toDataURL，再转成 PNG 下载。本地测试正常，但在某些环境导出后图标全部变成了方块。排查发现导出画布上的跨域图片资源时，Canvas 被污染，字体图标本身没被绘制进去。解决方法是用 blob 加载字体文件并在导出的临时 canvas 上主动绘制，同时为所有图标资源加上 crossOrigin 设置。另外导出的图片分辨率我默认提高了 2 倍，防止在 Retina 屏上模糊。

实操心得：Canvas 导出到 PNG 时，一定要把原画布的缩放比例算进去，否则在 200% 缩放下导出的是整体放大后的模糊图。导出的知识：先创建大尺寸 canvas，把所有节点按导出比例重新绘制一遍。

6.4 撤销重做时引用断裂

我踩过的最大一个坑，是删除一个分组时，组内节点还在，但 undo 时组内节点和组外连线的引用的 groupId 已经指向一个不存在的分组。排查后我在删除分组命令里加了级联处理：删除分组时，组内节点自动提升到父级，同时把关联连线全部保留；undo 删除分组时，把节点重新还原到分组子级。经验是：任何涉及关联数据的操作，都要把“连带影响”一并建模，否则历史栈回滚时必定出 bug。

7. 从工具到平台的扩展空间，diagram-design 还能做什么

diagram-design 做到内测稳定后，我开始思考它的定位，不只是画图工具，而是一个可以嵌入业务的图形设计基础设施。如果后续要继续演进，我这边已经梳理了两个方向，也实际做了部分探索。

第一个方向是组件化业务图谱。针对特定行业的实体关系建模，比如项目管理中的任务依赖图、电商中的订单状态流转图，通过预置的业务节点模板和规范的端口定义，让非技术人员直接拖拽组成业务语义图。这意味着底层数据模型要增加一个 schema 层，节点不仅仅有样式，还携带业务字段，可以填写责任人、优先级、状态等。我目前已经在尝试把 diagram-design 的 JSON 输出接入一个简单的业务表格渲染，效果还算自然。

第二个方向是多人实时协作。图数据的变更合并比普通文档难很多，因为节点坐标和连线关系存在强耦合。业内常见的做法是操作变换 + 在线状态同步，我这边只做了一个简单的 localStorage 同步 demo，还没有上服务端实时推送。真要上协作，我会优先做“中心化操作日志广播”，客户端接收操作后本地执行，这样天然适配现有的撤销栈。这里还想提醒一句：多人协作一定不要直接同步全量画布状态，那会在节点多的时候把服务器带宽打满。

顺着这个思路往下想，diagram-design 的价值其实不完全在“画图”，而在“画完图之后的业务联动”。把图形数据变成可查询、可计算、可流转的结构化数据，它就不再是一个画图工具，而是业务建模的入口。这个方向比单纯优化渲染更有意思，也是我后续想继续深入的东西。