企业官网建设流程全解析

1. 从白板到线上：diagram-design的起点和目标

1.1 当时的尴尬场景

做这个项目，起因其实很简单：团队里每次要画架构图、流程图，大家都会不约而同打开同一个在线绘图网站。但用了三个月，问题越来越明显。先不说免费版导出的图片带水印，光是把图从线上工具搬到内部文档里就得先导出再上传，中间改一处细节就要重复操作一遍，图多了以后谁都不记得哪个版本才是最新的。

更让人头疼的是数据安全。当时团队对接了一些内部业务系统，画出来的拓扑图说实话还挺敏感，但所有内容都放在第三方服务器上。IT那边提过几次意见，说能不能搞一个内部能用的绘图工具，不需要多精美，就满足日常画流程图、架构图、时序图这些需求。我一开始想找开源方案部署一套，结果调研了一圈发现，很多开源编辑器虽然能跑起来，但扩展方式、数据格式、交互手感都跟我们实际用法不太匹配。想要让工具真正顺手，还得按自己的使用场景重新设计一遍。

1.2 定下功能的边界

既然决定自己动手，我先把"diagram-design"这个项目的功能边界划清楚。核心要解决的问题是三个：

• 绘制常见的二维图形：矩形、圆形、菱形、箭头连线、贝塞尔曲线，覆盖流程图、组织结构图、网络拓扑图。
• 数据要能本地保存和导出：导出的格式不仅是图片，还要有结构化数据文件，方便下次继续编辑和做版本对比。
• 交互必须像桌面软件一样顺手：拖拽、框选、缩放、撤销重做、对齐参考线，这些基础编辑体验不能打折扣。

我刻意砍掉了很多花哨的能力。比如多人实时协作，第一版直接不做，因为协作同步引入的复杂度和我的目标完全不成比例。又比如模板商城，那属于锦上添花，后期如果有需要再补。还有丰富的素材库，考虑过，但第一版宁可让用户自己画，也不想因为素材版权和分类问题拖慢研发节奏。

1.3 技术路线的初稿

技术选型上，我用的是纯Web方案。项目本身就叫diagram-design，我目标很明确：浏览器打开即用，不需要安装任何软件，数据本地存储，同时提供明确的导出能力。

这里有个很重要的判断：我一开始就没打算用某款现成的绘图框架来堆功能，而是打算从底层自己写渲染、自己管数据模型。为什么？因为框架给你的是通用能力，但一旦遇到"我想让矩形左上角显示一个小徽章"或者"连线上我想画两条并行文字"这类定制需求，反而会被约束。自己做虽然前期工作量更大，但后面每一次功能扩展都能掌控细节。这个决定，现在回头看是整件事里最值的投入。

2. 渲染引擎选择：Canvas还是SVG，最后为什么我用了自绘渲染

2.1 两种方案的对照

图表编辑器的核心就是渲染层。在动手画第一根线之前，必须先决定用Canvas还是SVG。很多人在这一步容易凭感觉拍板，但实际差异非常大。

对于节点数量动辄几百的架构图，SVG的DOM节点数量会拖垮首屏和每次刷新。Canvas虽然交互麻烦一点，但性能上限高得多。我最终选了Canvas，配合自己实现的命中检测。这是值得的，因为它让我把"整张图重绘"的控制权拿在手里，而不是由浏览器决定什么时候重绘哪一块。

2.2 数据与视图分离的文档模型

选定了Canvas之后，我给自己定的第一条规矩是：画布上显示的一切都不得直接修改，必须先改数据模型，再触发重绘。这个模型用了一个非常经典的文档结构：

interface DiagramDocument { version: number; nodes: DiagramNode[]; edges: DiagramEdge[]; viewport: ViewportState; } interface DiagramNode { id: string; type: "rect" | "circle" | "diamond" | "text"; x: number; y: number; width: number; height: number; rotation: number; style: NodeStyle; data: Record<string, unknown>; } interface DiagramEdge { id: string; sourceNodeId: string; targetNodeId: string; sourceAnchor: string; targetAnchor: string; waypoints: Point[]; style: EdgeStyle; }

整张图就是一个普通对象，节点和连线分开存放。每条连线上记录它从哪个节点的哪个锚点出发、到哪个锚点结束，如果有拐点，waypoints数组里存中间路径。这套模型的优点在于：保存文件时直接把这个对象序列化即可，所有的撤销、重做、批量修改也都围绕这个纯数据对象展开。视图层只是模型的一个投影，任何复杂的交互都先落到模型上，再统一刷新。

2.3 脏矩形与局部重绘

Canvas天然没有"只更新某个区域"的API，要么重绘全部，要么手动限定裁剪区域。在节点少的时候全量重绘完全没问题，但一旦图表复杂起来，每次鼠标拖动都全量重绘，那个性能损耗可不止翻倍。

我当时用了脏矩形方案。维护一个"需要重绘的区域列表"，每次操作结束之后，计算受影响的所有图形包围盒，合并成一个或多个矩形，只对这些矩形调用ctx.clip()，把绘制范围限制在脏区域内。其余区域保持上一帧的像素不变。

这块有个细节容易被忽视：连线的重绘区域不能只看线段本身，因为线宽和箭头可能会超出节点包围盒。我给所有元素都预留了一个"渲染扩展边距"，计算脏矩形时把这个边距也算进去。磨了这一层之后，哪怕上千节点同时拖动，帧率也没有断崖式下跌。

2.4 坐标变换与缩放平移

Canvas绘图的好用之处在于，它的坐标系统完全可以用一个变换矩阵来描述。我需要同时支持画布平移、缩放，而且希望缩放的中心点是当前鼠标位置——也就是说，鼠标指向哪，哪就保持不变，画布围绕这个点放大缩小。

核心公式很简单，但推导过程值得写下来。设画布的缩放比例为scale，当前平移量为offsetX和offsetY，鼠标在屏幕上的位置是(mouseX, mouseY)，在画布世界坐标里的位置是(worldX, worldY)。那么有：

worldX = (mouseX - offsetX) / scale; worldY = (mouseY - offsetY) / scale;

当缩放比例从oldScale变为newScale时，为了让鼠标指向的世界坐标不动，新的平移动量必须满足：

offsetX_new = mouseX - worldX * newScale; offsetY_new = mouseY - worldY * newScale;

我每次处理滚轮缩放时按这个公式更新平移量和缩放比例，手感非常自然。另外，Canvas的ctx.setTransform()在每次重绘时直接设置缩放和平移矩阵，所有图形绘制都基于世界坐标，屏幕坐标的换算交给矩阵处理，代码会干净很多。

3. 编辑器里的交互状态机：从拖拽到连线

3.1 状态机划分

做编辑器的人都知道，任意一个鼠标事件在什么模式下、发生在哪个对象上，会产生完全不同的结果。如果全用if-else控制，代码很快变成一团乱麻。从diagram-design的交互角度，我把画布的全局状态拆成五个互斥的状态：

• idle：空闲，没有进行任何拖拽或编辑动作。
• selecting：正在框选，鼠标拉出一个矩形区域。
• draggingNode：鼠标按住一个节点并拖动位置。
• connecting：拖出一条连线，尚未松开鼠标。
• panning：鼠标按住画布空白处，正在平移视角。

每次鼠标按下，判断事件命中的目标类型，决定进入哪个状态；鼠标移动时，根据当前状态分发到对应的处理函数；鼠标松开时，结束当前状态并执行最终的落定逻辑。用switch-case分发，逻辑一目了然，而且后续想加"缩放模式""文字编辑模式"，新增一个状态就行，不用动已有逻辑。

3.2 锚点吸附与连线判定

连线的起点和终点不应该随心所欲。我在每个节点上定义了四个锚点：上、下、左、右，同时支持按Shift时自动吸附到最近的锚点。因为节点在被拖拽的时候，锚点的世界坐标会实时变化，所以连线锚点的计算必须放在"鼠标抬起"那一瞬间，而不是"鼠标按下"时固化。

做连线时，有一段逻辑需要特别注意：当节点的边缘和连线路径相交时，连线的渲染终点要减去一个偏移量，让箭头恰好停在节点边框上，而不是穿进节点内部。这个偏移量的计算涉及连线的方向和节点形状的交点求解，矩形和圆形是两套公式，菱形又不一样。我的做法是给每种节点类型提供一个getEdgeIntersection(entryDirection): Point方法，连线模块不需要关心节点具体是什么形状，只调用这个方法拿到终点坐标。

3.3 框选、组合与层级

框选的本质很简单：用一个矩形覆盖所有被选中的节点，然后把这些节点的id放进一个选中集合里。但实际操作中容易被忽略的是"框选时是否包含连线"这个问题。我的规则是：如果一条连线的两个端点节点都在选框内，那么这条线一起选中；否则不选。这套规则符合直觉，也避免选中半个连线导致移动节点时连线断开的尴尬。

组合和层级是交互中不怎么起眼，但用起来很影响体验的功能。diagram-design里的组合不是真正把节点合并成一个复合对象，而是维护一个groupId，移动、缩放、复制都按组为单位。层级管理则对应一个简单的z-index数组，每次选中节点时把它移到数组末尾，绘制时按数组顺序从后往前画。这样一来，点选永远能选中最上方的元素，下层元素不会被误触。

3.4 撤销重做实现

撤销重做是我在编辑器中做得最谨慎的一块。很多编辑器把这功能做成"记录每次操作前后的完整快照"，这在节点少的场景下可行，但节点一多，每次操作都深拷贝整张文档，内存和耗时的代价都非常昂贵。

我用的是操作指令模式。每种操作都实现为一个类，至少包含三个方法：apply()、revert()、description()。比如移动节点这个操作，我在apply里把节点从旧位置移到新位置，revert里移回去，description里记录一下"移动了3个节点"。真正做到撤销内存友好，而且将来要做操作步骤动画，直接复现指令序列即可。

这里有个小坑：连续的拖动会产生大量中间状态，如果每移动1个像素都记录一个历史节点，撤销列表里全是垃圾记录。我给拖动操作加了合并策略——同一节点、同一个句柄、在同一段时间内的连续变化只记录一次历史。只有鼠标松开超过一定间隔之后才新建一个历史节点。

4. 自动布局：当排布不再靠手

4.1 自动布局的触发时机

图表的节点一旦多起来，手拖布局的效率直线下降。有一次我模拟了一个有七十多个节点的网络拓扑，光是让它们不重叠就花了一个晚上。那次之后我下定决心，一定要在项目里加上自动布局。虽然不是所有图都适合自动布局，但绝大多数场景下，给用户一个"一键整理"按钮，至少能把节点从一团乱麻变成基本可读的结构，剩下的交给用户去微调。

自动布局的触发时机我设置了三种。第一种是操作栏按钮，手动点击触发。第二种是在导入外部结构化数据的时候，既然图是程序生成出来的，那坐标也顺便排好。第三种是粘贴大量节点到画布时，如果判定新节点和现有节点大面积重叠，就自动跑一次局部布局算法。

4.2 有向图的层级布局

最常用的自动布局类型是流程图的层级布局。这个算法很多软件都在用，但实现的时候有几个关键点。第一步是进行拓扑排序，把节点按照依赖关系分成多个层级，同层节点之间没有互相指向的边。第二步是确定每层的节点顺序，这一步的目标是让跨越层级的连线的交叉数量尽可能少。完整的交叉最小化算法是一个相当复杂的问题，我做了一个近似方案：每层节点先按入度排序，然后迭代两次相邻层交换节点位置，如果交叉数量下降就保留交换。虽然不是全局最优，但实际效果已经能看。

坐标计算其实就是给每个节点分配x和y。y由层级决定，每个层级间隔一个固定距离；x由该层内的节点序号决定，序号越大越靠右。等所有节点位置算完之后，再统一做一边归一化，把整张图平移到原点附近。连线路径则根据起点和终点锚点的方向，生成正交折线，拐点放在中点处。

4.3 力导向布局与桥型图

层级布局适合有方向的流程图，但遇到无向图、拓扑结构图就不太合适了，这时候需要力导向布局。我对力导向布局的实现是一个传统的模拟过程：每个节点受到三种力，第一是相连节点之间的弹簧力，倾向于把节点拉到固定距离；第二是任意两个节点之间的斥力，防止重叠；第三是轻微的向心力，让整个图不至于漂散到画布外面。

力导向布局的参数调起来真的是门学问。弹簧的弹性系数k决定了边的理想长度，斥力系数repulsion影响节点的疏密程度。我给diagram-design设置了一套默认参数：k = 80，repulsion = 1000，迭代次数最多300轮。这些参数不是算出来的，而是拿了几张实际业务图试出来的。经验是：图越大，斥力系数就要稍微调低一点，否则外围节点会被推出画布太远。

模拟过程中的每轮迭代都要更新所有节点的速度向量，然后根据速度和阻尼系数更新位置。为了避免振荡，我在每轮迭代后加了惯性衰减，让速度乘以一个小于1的系数。跑完之后再执行几轮应力最小化平滑，让线段分布更均匀。

4.4 自动布局后的手动微调

自动布局永远不可能完全代替手动调整。设计者希望强调的节点、希望突出的主链路、希望刻意留出的空白区域，这些都是算法无法理解的。所以自动布局做完之后，diagram-design会进入"微调模式"：布局算法只计算一次，并记录每个节点初始位置，然后用户可以自由拖动节点。在拖动过程中，被拖动的节点周围有四个"磁性参考线"，以周围节点的中心线为基准，容易对齐出漂亮的网格。

我在这里做了一件挺容易被忽略但很贴心的事：自动布局执行之后，如果用户微调幅度超过原始布局距离的一半，工具会主动提醒"是否放弃手动调整，重新运行自动布局"。这个提示只是一个小交互，但省去了很多反复折腾的时间。

5. 导入导出：内部模型、SVG和PNG的三角关系

5.1 文档模型的版本化设计

一个图表编辑器把图画好只是第一步，能让数据安全流转才是长期价值所在。我最早设计diagram-design的文件格式时只考虑自己内部用，结果后来几个同事用这个工具画的流程图要导入其他平台，两边数据对不上。这件事让我明白，文件格式必须在一开始就考虑兼容未来的可能性。

我的办法是给文档格式打上版本号。每次保存文件，文件头是一个JSON对象，里面包含format字段和version字段。目前是第2版，第1版导出的文件在新版里仍然能打开，打开时做一次数据迁移。迁移逻辑集中在一个函数里，文件名就叫migrateDocumentV1toV2，遇到无法迁移的字段就跳过并给出提示。这个机制虽然简陋，但它保证了长期使用的连续性。

5.2 SVG导出的样式收敛问题

Canvas绘制的东西和SVG的样式模型差异很大，直接做导出会面临一个很麻烦的问题：Canvas线段的线宽、描边样式、填充颜色都是以像素为单位的，而SVG里的样式是矢量描述。为了让导出的SVG在不同地方显示效果一致，我维护了一个样式映射表，把Canvas的绘制参数翻译成SVG的stroke、fill、stroke-width、stroke-dasharray。

导出SVG的顺序和画布上的绘制顺序是一致的，先导出所有连线，再导出节点，最后导出文字。导出的文本内容需要做XML转义，否则用户标题里的<和>字符会让整个SVG文件损坏。箭头方面，SVG可以用marker-end定义，它比手动画三角形要可靠得多，尤其在图形旋转的时候。

5.3 高清PNG导出与多倍率适配

PNG导出的坑相对集中：清晰度和性能。直接调用canvas.toDataURL()导出，得到的图片在普通屏幕上看着还行，但一旦放到Retina屏幕或PPT里放大，立刻出现锯齿。解决办法是导出一张高倍率的位图：把Canvas的尺寸乘以一个导出倍率，比如2x或3x，然后在导出前把所有绘制操作的坐标系同步放大。

这里就要小心里面的性能问题了。一个5000×5000的画布放大3倍，就是15000×15000像素，浏览器的内存和绘制时间会撑爆。我做了个保护机制：目标像素面积超过某个阈值（比如4000万像素）时，自动降低倍率，宁可稍微牺牲一点清晰度，也不能让浏览器崩溃。导出的PNG也做了尺寸记录，在导出完成之后提示用户图片实际尺寸，避免拿出去用的时候发现跟预期不一致。

5.4 文本化图示语法的可选输入

除手工绘制的数据之外，我还加了一条文本化输入的通道。很早以前用Markdown写文档的时候，习惯了用文本描述流程，再让它生成图。diagram-design支持的是一种简化过的文本语法，大概长这样：

开始 -> 选择文件 -> 读取内容 -> 判断格式 -> 渲染图表 判断格式: 支持格式 -> 直接渲染 判断格式: 未知格式 -> 返回错误提示

文本解析器会把每一行的->关系转成节点和连线，冒号后面的内容作为分支注释，最终生成内部文档模型，自动布局之后落到画布上。这条通道对有技术背景的用户来说是非常重要的效率工具，很多人宁可写文本也不愿用鼠标去拖拽。

实现文本解析的时候我遇到了一个约束：语法解析不能破坏已存在的节点坐标。所以每次文本导入时，只有新生成的节点才参与自动布局，已存在的节点保留原位置。老用户的实际体验基本是：为了补充几个新节点，不用重排整张图。

6. 我在diagram-design开发中踩过的五个坑

6.1 键盘事件与画布焦点的博弈

第一版做完之后，收到最多的反馈是方向键移动节点失灵。排查原因时发现，方向键被浏览器默认行为抢走了，页面上下滚动但没有触发画布里的键盘处理。Canvas元素本身不具备焦点，必须把tabindex属性加上并且调用focus()方法，才能接收键盘事件。

更隐蔽的问题是，用户点击其他区域再回来画布时，焦点经常丢失。我最后用了两层保险：画布容器上监听mousedown事件时主动调focus()；同时监听document上的keydown事件，判断按下的是不是方向键，如果是且当前焦点不在输入框内，就视为画布操作。加上这个双保险之后，键盘操作才算真正稳定。

6.2 重叠节点的命中测试

Canvas自绘使得"判断鼠标点到了哪个图形"这件事得我自己写。最初的想法很简单：按z-index从高到低遍历节点，判断鼠标点是否落在节点包围盒内。但很快发现，节点旋转45度之后，包围盒的判断结果跟视觉明显不符——鼠标明明离图形还有一段距离，却被判定为命中。

我把所有节点的命中测试统一改成"点在多边形内"的算法：矩形虽然只有四个顶点，但加上旋转之后就是一个四边形，圆和菱形也是如此。每次命中测试先做一次快速边界检查，如果鼠标在包围盒外直接跳过，如果在内再进入精确的多边形判定。这个优化让性能没有明显下降，同时旋转节点不再误选。

6.3 大画布下内存泄漏的定位

有一次我开着图表编辑器反复复制、删除一个大节点，然后发现内存占用不断上涨而且不回落。打开浏览器内存分析工具找原因，才发现问题不在Canvas绘制本身，而在于我给每个节点附加的监听器。代码里创建节点时顺手挂了一个自定义事件监听，删除节点时没移除，监听器闭包里又保存了整个文档引用，相当于删掉的每个节点都还活在闭包链里，内存只能一路涨上去。

修复方式并不复杂，在removeNode方法里主动调用监听器的cleanup()。但我后来养成了一个习惯：任何从事件系统接入的对象，都给销毁函数命名成destroy()，在模型变更时显式调用。这套约定帮我减少了很多潜在泄漏。

6.4 导出模糊背后的dpr问题

前面说到导出倍率，有一段时间无论怎么调倍率，导出的PNG都比预期模糊。调试半天才发现问题不在倍率，而在于设备像素比。浏览器的Canvas默认坐标和物理像素之间存在一个devicePixelRatio缩放，我的绘制代码用的坐标系没有乘这个值，导致导出时所有图形都按较低分辨率生成。

理解了这一点后，我的做法是设置一个统一的dpr变量，在Canvas尺寸初始化时乘以dpr，再通过ctx.scale(dpr, dpr)把坐标系还原。所有后续绘制逻辑不感知dpr，但导出的图片实际分辨率已经翻了倍，清晰度立刻上来了。

6.5 数据量激增时的性能下滑

diagram-design最后一个坎是性能。早期测试只用了几十个节点，一切正常。有一次导入真实业务数据，节点数直接到2000多条，结果拖动画布的时候掉帧严重，缩放的顺滑感也没有了。

优化思路分两条线并行。一条是绘制层面，剔除视口外的节点，只绘制当前可见区域内的内容，这一步能砍掉大概40%的绘制量。另一条是数据层面，把节点的样式和位置分开存，拖拽过程中只更新位置数组，样式不参与脏检测。最终的效果是，2000节点的情况下日常交互重新回到了60帧，这个成绩在纯Canvas方案里已经算很不错了。

结尾的几句实在话

做diagram-design的过程中，我最深的体会是：图表编辑器的难点从来不在"画一个矩形"或者"连一条线"，而在于把交互、数据、渲染三个层的关系理清楚。每一次用户觉得"顺手"的操作，背后都堆积了大量此前没预见的细节。即便方案做得再完善，开发周期的最后三分之一也总会被意外问题占据。如果还有下一次重构，我会在项目第一天就拉开版本化的字段设计，并为所有对象生命周期建立统一的销毁机制。这套积累下来的坑和规则，比那些看上去绚丽的功能点要值钱得多。