企业官网建设流程全解析

1. 架构图这件事，为什么总是让人头疼

干了这么多年开发，我敢说有一件事几乎所有人都逃不掉：画架构图。不管是给新人做 onboarding、给产品经理讲系统链路、还是给老板汇报技术方案，你总得把脑子里那套东西画出来。但现实往往很骨感——Visio 太重，打开就要等半天；draw.io 虽然免费，但导出的图永远是静态的，想加个动效得手动做 PPT；PlantUML 和 Mermaid 倒是能用代码生成，可样式丑得让人想哭，调个颜色比写业务逻辑还费劲。

更别提时序图了。时序图这东西，本质上是在描述“谁在什么时候给谁发了什么消息”，它天然就是动态的。可我们平时看到的时序图，全是一张死图，箭头从左拉到右，读者得自己脑补消息的先后顺序。尤其是讲 I2C 时序、SMBus 通讯协议、BLE 蓝牙建立连接这些底层协议的时候，静态图根本说不清楚“时钟线拉低之后数据线才变化”这种细节。

Archify 这个项目就是冲着这个痛点来的。它做的事情说起来很简单：用纯 HTML 和 SVG 生成可交互、带动效的时序图。没有重型依赖，没有复杂的构建流程，你写一段结构化的描述，它就能渲染出一张能点击、能播放、能逐帧查看的时序图。我第一次看到它的 demo 时，第一反应是“这东西早该有人做了”。

这篇文章我会从架构设计的角度，把 Archify 的核心思路、实现细节、实操步骤和踩坑经验全部拆开讲一遍。不管你是前端新手还是老手，只要你对“用代码画图”这件事感兴趣，或者你正好被时序图折磨过，这篇内容应该都能给你一些可以直接抄作业的东西。

2. Archify 的整体设计思路拆解

2.1 为什么选 HTML + SVG 而不是 Canvas

这是 Archify 最核心的一个技术决策，值得好好说一说。市面上画图的库，大体分两派：一派用 Canvas，比如 ECharts、Chart.js；另一派用 SVG，比如 D3.js、Snap.svg。Archify 选了 SVG，而且是把 SVG 直接嵌在 HTML 里，这个选择背后有好几层考虑。

第一层考虑是可交互性。Canvas 本质上是一块画布，你画上去的东西就是像素，想让某个元素响应点击事件，得自己算坐标、做命中检测。SVG 不一样，每个图形元素都是 DOM 节点，你给一个<rect>加onclick就跟给<div>加事件一样自然。时序图里每条消息箭头、每个生命线、每个激活块，都需要能单独响应 hover 和 click，用 SVG 做这件事的成本几乎为零。

第二层考虑是样式控制。SVG 元素可以直接用 CSS 来控制样式，这意味着你可以用熟悉的 CSS 选择器、CSS 变量、媒体查询来调整图的 appearance。Archify 里所有的颜色、线宽、字体大小都定义成了 CSS 变量，换主题只需要改几个变量值。Canvas 要做到同样的事情，得在 JS 里手动管理所有样式状态，代码量会膨胀好几倍。

第三层考虑是可访问性和可导出性。SVG 是矢量格式，放大缩小不失真，可以直接嵌入到任何 HTML 页面里，也可以单独导出成.svg文件。更重要的是，SVG 里的文字是真正的文字，可以被搜索引擎抓取、可以被屏幕阅读器朗读。Canvas 画出来的文字就是一堆像素，没有任何语义。

第四层考虑是动效实现。SVG 支持 SMIL 动画，也支持通过 CSS transition 和 animation 来做动效。Archify 的消息流动效果，本质上就是控制一条路径的stroke-dashoffset属性，配合transition就能做出“线条逐渐延伸”的效果。这个技巧在 SVG 里是标准做法，实现起来非常干净。

提示：如果你之前只用过 Canvas 画图，建议花半小时了解一下 SVG 的坐标系和基本元素（rect、circle、line、path、text），后面看 Archify 的源码会顺畅很多。

2.2 数据驱动的渲染模型

Archify 的第二个核心设计是数据驱动。它不要求你直接写 SVG 代码，而是让你用一种接近自然语言的结构来描述时序图。比如你要描述一个简单的请求响应过程，大概是这样：

const diagram = { actors: ['Client', 'Server', 'Database'], messages: [ { from: 'Client', to: 'Server', label: 'POST /login' }, { from: 'Server', to: 'Database', label: 'SELECT user' }, { from: 'Database', to: 'Server', label: 'user row' }, { from: 'Server', to: 'Client', label: '200 OK' } ] };

然后 Archify 会根据这个数据结构，自动计算出每个参与者的水平位置、每条消息的垂直位置、每个激活块的起止时间，最后生成对应的 SVG 元素。这种设计的好处是，你把“描述逻辑”和“渲染逻辑”彻底分开了。想改图的内容，只动数据；想改图的样式，只动 CSS；想改图的布局算法，只动渲染引擎。三者互不干扰。

我特别喜欢这种设计的一点是，它让时序图变成了可版本控制的东西。以前你用 Visio 画的图，改一个箭头位置，整个文件二进制都变了，git diff 出来一堆乱码。现在时序图就是一个 JS 对象或者 JSON 文件，每次改动在 git 里看得清清楚楚，code review 的时候也能像审代码一样审图。

2.3 布局算法的取舍

时序图的布局看起来简单，其实有不少细节要处理。Archify 的布局算法我拆解了一下，大致分三步：

第一步，计算参与者的水平位置。假设有 N 个参与者，画布宽度为 W，左右各留 margin，那么每个参与者的 x 坐标就是margin + i * (W - 2 * margin) / (N - 1)。这一步没什么好说的，均匀分布就行。

第二步，计算消息的垂直位置。每条消息占一行，行高是固定的（比如 60px），那么第 j 条消息的 y 坐标就是topMargin + j * rowHeight。这里有个细节：如果消息有自调用（自己给自己发消息），需要额外占一行来画那个回环箭头。

第三步，计算激活块的位置。激活块表示某个参与者在某段时间内处于活跃状态。它的起始 y 坐标是触发它的那条消息的 y 坐标，结束 y 坐标是返回消息的 y 坐标。如果有多层嵌套，还需要处理层叠偏移，让每个激活块稍微往右偏一点，避免完全重叠。

这套算法不算复杂，但 Archify 在实现时做了一个很聪明的取舍：它不支持自动换行和自动缩放。也就是说，如果你的参与者名字太长，或者消息太多，图会超出画布范围，需要你自己调整画布尺寸或者缩短文字。这个取舍看起来是个缺陷，但实际上大大简化了布局逻辑，也让渲染结果更可预测。我个人觉得这个取舍是合理的，毕竟时序图本来就不适合塞太多东西。

3. 核心细节解析与实操要点

3.1 SVG 坐标系与时序图的映射关系

要理解 Archify 怎么画图，首先得把 SVG 的坐标系和时序图的语义对应起来。SVG 的坐标原点在左上角，x 轴向右，y 轴向下。时序图的语义是：水平方向表示参与者，垂直方向表示时间流逝。所以映射关系很直接：

• 参与者的水平位置 → SVG 的 x 坐标
• 消息的先后顺序 → SVG 的 y 坐标（越往下时间越晚）
• 参与者的生命线 → 一条垂直的<line>或<path>
• 消息箭头 → 一条水平的<line>加一个箭头标记
• 激活块 → 一个窄长的<rect>

这里有个容易踩坑的地方：SVG 里画箭头不能用marker-end就完事。marker-end确实能加箭头，但箭头的方向是沿着路径方向的，如果你的路径是从右往左画，箭头会自动翻转，这没问题。但如果你想让箭头有动画效果，比如逐帧显示，marker是没法单独控制透明度的。Archify 的做法是用一个独立的<path>来画箭头三角形，这样可以单独给它加动画。

另一个坑是文字对齐。SVG 的<text>元素默认的基线是alphabetic，也就是文字底部对齐。如果你想让文字垂直居中于某条线，需要设置dominant-baseline="middle"。这个属性在 Chrome 和 Firefox 里支持得很好，但在某些老版本 Safari 里需要加-webkit-前缀。Archify 里统一用了dominant-baseline="central"，实测下来兼容性最好。

3.2 消息流动动效的实现原理

Archify 最吸引人的地方就是那个消息流动的动效。当你点击“播放”按钮时，每条消息箭头会从发送方逐渐延伸到接收方，就像水流过去一样。这个效果看起来炫酷，实现原理其实很简单：利用stroke-dasharray和stroke-dashoffset。

具体做法是，对于一条长度为 L 的路径，设置stroke-dasharray: L，这样整条路径就变成了一段长度为 L 的实线加一段长度为 L 的空白，总共周期是 2L。然后设置stroke-dashoffset: L，实线部分就被移出了可视区域，看起来路径是空的。接着用 CSS transition 把stroke-dashoffset从 L 过渡到 0，实线部分就逐渐“长”出来了。

.message-line { stroke-dasharray: var(--line-length); stroke-dashoffset: var(--line-length); transition: stroke-dashoffset 0.6s ease-in-out; } .message-line.playing { stroke-dashoffset: 0; }

这里的关键是--line-length这个 CSS 变量，它需要在渲染时根据实际路径长度动态计算。Archify 在生成 SVG 后，用getTotalLength()方法获取每条路径的真实长度，然后把它写到元素的 style 上。这个 API 是 SVG 标准的一部分，所有现代浏览器都支持。

注意：getTotalLength()必须在元素已经挂载到 DOM 之后才能调用，否则会返回 0。如果你在创建元素的同时就调用，拿到的长度是错的。Archify 的做法是先把所有元素渲染到 DOM，然后在requestAnimationFrame回调里统一计算长度并设置变量。

3.3 交互事件的设计与绑定

Archify 的交互分三个层次：hover 高亮、click 选中、播放控制。

hover 高亮是最基础的。当鼠标移到某条消息上时，这条消息的线条加粗、颜色变深，同时对应的发送方和接收方的生命线也高亮。实现方式是用事件委托，在 SVG 根元素上监听mouseover和mouseout，通过event.target的>function playNextMessage(index) { if (index >= messages.length) return; const el = document.querySelector(`[data-message-id="${index}"]`); el.classList.add('playing'); el.addEventListener('transitionend', () => { playNextMessage(index + 1); }, { once: true }); }

3.4 响应式与自适应处理

Archify 生成的图默认是固定尺寸的，但它支持通过viewBox来实现响应式缩放。viewBox是 SVG 里一个非常重要的属性，它定义了 SVG 内部的坐标系范围。比如viewBox="0 0 800 600"表示内部坐标从 (0,0) 到 (800,600)，而 SVG 元素的实际显示尺寸由 CSS 的 width 和 height 决定。这样你就可以让图自适应容器宽度，同时保持内部布局不变。

<svg viewBox="0 0 800 600" preserveAspectRatio="xMidYMid meet"> <!-- 图形内容 --> </svg>

preserveAspectRatio这个属性控制的是当 viewBox 的宽高比和实际显示区域的宽高比不一致时，图形怎么缩放。xMidYMid meet表示等比缩放并居中，这是最常用的设置。如果你希望图形填满整个区域而不保持比例，可以用none，但那样图形会变形，时序图里一般不推荐。

还有一个细节是文字大小。当 SVG 被缩小时，文字也会跟着缩小，可能变得难以阅读。Archify 的解决方案是给文字设置一个最小字号，通过 CSS 的font-size: max(12px, 1.2vw)这样的写法来保证可读性。不过这个方案在 SVG 里支持得不太一致，更稳妥的做法是用 JS 监听 resize 事件，动态调整字号。

4. 从零实现一个 Archify 风格的时序图

4.1 项目初始化与目录结构

如果你想自己复现一个 Archify，或者基于它的思路做一个定制版本，我建议从下面这个目录结构开始：

archify-demo/ ├── index.html ├── styles/ │ ├── main.css │ └── theme.css ├── scripts/ │ ├── renderer.js │ ├── layout.js │ └── animation.js └── data/ └── diagram.js

这个结构的好处是职责清晰：layout.js只负责计算坐标，renderer.js只负责生成 SVG 元素，animation.js只负责动效控制，diagram.js只存放数据。每个文件都可以单独测试和替换。

index.html里只需要一个空的 SVG 容器和一个控制面板：

<!DOCTYPE html> <html lang="zh-CN"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>Archify 风格时序图</title> <link rel="stylesheet" href="styles/main.css"> </head> <body> <div class="diagram-container"> <svg id="diagram" viewBox="0 0 900 600"></svg> </div> <div class="controls"> <button id="play">播放</button> <button id="pause">暂停</button> <button id="reset">重置</button> </div> <script src="data/diagram.js"></script> <script src="scripts/layout.js"></script> <script src="scripts/renderer.js"></script> <script src="scripts/animation.js"></script> </body> </html>

4.2 布局计算的核心代码

布局计算是整个渲染流程的第一步。我把它拆成了一个纯函数，输入是数据对象和画布尺寸，输出是每个元素的坐标信息。

function computeLayout(diagram, width, height) { const marginX = 80; const marginTop = 60; const rowHeight = 70; const actorCount = diagram.actors.length; const messageCount = diagram.messages.length; // 计算参与者水平位置 const actorPositions = diagram.actors.map((name, i) => ({ name, x: marginX + i * (width - 2 * marginX) / (actorCount - 1) })); // 计算消息垂直位置 const messagePositions = diagram.messages.map((msg, j) => ({ ...msg, y: marginTop + j * rowHeight, fromX: actorPositions.find(a => a.name === msg.from).x, toX: actorPositions.find(a => a.name === msg.to).x })); // 计算画布所需高度 const requiredHeight = marginTop + messageCount * rowHeight + 80; return { actorPositions, messagePositions, requiredHeight }; }

这段代码里有几个值得注意的点。第一，actorPositions用find来查找坐标，这在参与者数量少的时候没问题，但如果参与者有几十个，每次查找都是 O(n)，整体就是 O(n²)。优化方案是先用一个 Map 把名字到坐标的映射建好，查找变成 O(1)。第二，requiredHeight的计算要留出底部空间，否则最后一条消息的标签可能会被裁掉。第三，如果只有 1 个参与者，actorCount - 1会等于 0，导致除零错误，需要单独处理。

4.3 生成 SVG 元素的实操细节

渲染阶段就是把布局计算结果转换成实际的 SVG 元素。Archify 用的是document.createElementNS来创建 SVG 元素，因为 SVG 元素必须在正确的命名空间下才能被浏览器识别。

const SVG_NS = 'http://www.w3.org/2000/svg'; function createRect(x, y, width, height, className) { const rect = document.createElementNS(SVG_NS, 'rect'); rect.setAttribute('x', x); rect.setAttribute('y', y); rect.setAttribute('width', width); rect.setAttribute('height', height); rect.setAttribute('class', className); return rect; } function createLine(x1, y1, x2, y2, className) { const line = document.createElementNS(SVG_NS, 'line'); line.setAttribute('x1', x1); line.setAttribute('y1', y1); line.setAttribute('x2', x2); line.setAttribute('y2', y2); line.setAttribute('class', className); return line; }

这里有个性能上的小技巧：不要每创建一个元素就 append 到 DOM。正确的做法是先把所有元素创建好，放到一个DocumentFragment里，最后一次性 append。这样浏览器只需要做一次重排和重绘，性能会好很多。我实测过，对于有 50 条消息的时序图，逐个 append 大概要 200ms，用 Fragment 只要 30ms 左右。

const fragment = document.createDocumentFragment(); // ... 创建所有元素并 append 到 fragment svg.appendChild(fragment);

4.4 动效控制的完整实现

动效控制模块需要管理播放状态、当前进度、以及每条消息的动画触发。我设计了一个简单的状态机：

const AnimationState = { IDLE: 'idle', PLAYING: 'playing', PAUSED: 'paused' }; class DiagramAnimator { constructor(svgElement, messages) { this.svg = svgElement; this.messages = messages; this.state = AnimationState.IDLE; this.currentIndex = 0; } play() { if (this.state === AnimationState.PLAYING) return; this.state = AnimationState.PLAYING; this.step(); } step() { if (this.state !== AnimationState.PLAYING) return; if (this.currentIndex >= this.messages.length) { this.state = AnimationState.IDLE; return; } const el = this.svg.querySelector( `[data-message-index="${this.currentIndex}"]` ); el.classList.add('playing'); el.addEventListener('transitionend', () => { this.currentIndex++; this.step(); }, { once: true }); } pause() { this.state = AnimationState.PAUSED; } reset() { this.state = AnimationState.IDLE; this.currentIndex = 0; this.svg.querySelectorAll('.playing').forEach(el => { el.classList.remove('playing'); }); } }

这个实现里有个细节需要注意：transitionend事件可能会因为多种属性变化而触发多次。比如你同时改变了stroke-dashoffset和opacity，就会触发两次transitionend。解决方案是检查event.propertyName，只处理你关心的那个属性。或者更简单粗暴一点，用一个标志位来防止重复触发。

5. 常见问题与排查技巧实录

5.1 图形不显示或显示错位

这是新手最常遇到的问题。我整理了一个排查清单，按顺序检查基本都能定位到原因：

其中最常见的是命名空间问题。如果你用document.createElement('rect')创建元素，浏览器会把它当成一个未知的 HTML 元素，而不是 SVG 元素，结果就是什么都不显示。这个错误很隐蔽，因为控制台不会报错，元素也确实在 DOM 里，只是不渲染。

另一个常见问题是CSS 优先级。SVG 元素的样式可能被浏览器默认样式覆盖，或者被其他 CSS 规则覆盖。排查时可以在开发者工具里选中元素，看 Computed 面板里最终生效的样式是什么。如果发现stroke是none，那就是没设置上。

5.2 动效卡顿或不流畅

动效卡顿通常有两个原因：动画属性选择不当和元素数量过多。

第一个原因，如果你动画的是width、height、x、y这些几何属性，浏览器每一帧都要重新计算布局，性能很差。正确的做法是动画transform和opacity，这两个属性可以被 GPU 加速。对于线条延伸效果，动画stroke-dashoffset也是可以的，因为它不触发布局重排，只触发重绘。

第二个原因，如果图里有几百个元素同时做动画，再好的优化也扛不住。解决方案是分批动画，或者只对当前视口内的元素做动画。Archify 的做法是逐条播放，同一时间只有一条消息在动，这样性能压力就小很多。

提示：在 Chrome DevTools 的 Performance 面板里录制一段动画，看看有没有长任务或者频繁的重排。如果有，就针对性地优化。

5.3 导出 SVG 后样式丢失

Archify 支持把生成的图导出成独立的.svg文件。但很多人导出后发现样式全丢了，图变成黑白的。原因是外部 CSS 不会被包含在导出的 SVG 里。SVG 文件是独立的，它不会去加载你页面里的 CSS 文件。

解决方案有两个：一是把关键样式内联到 SVG 元素上，用style属性而不是class；二是在导出时把 CSS 规则提取出来，包在<style>标签里嵌入 SVG。Archify 用的是第二种方案，它维护了一个样式字符串，导出时直接拼接到 SVG 的<defs>里。

function exportSVG(svgElement, cssText) { const clone = svgElement.cloneNode(true); const style = document.createElementNS(SVG_NS, 'style'); style.textContent = cssText; clone.insertBefore(style, clone.firstChild); const serializer = new XMLSerializer(); return serializer.serializeToString(clone); }

5.4 在 React/Vue 项目里集成的问题

如果你想在 React 或 Vue 项目里用 Archify 的思路，有几个坑要注意。

React 里操作 SVG 的 DOM 和操作 HTML 的 DOM 不太一样。React 对 SVG 属性的支持有一些历史遗留问题，比如stroke-width在 JSX 里要写成strokeWidth，class要写成className。如果你直接用dangerouslySetInnerHTML插入 SVG 字符串，那倒没这个问题，但你就失去了 React 的响应式更新能力。

Vue 里相对简单一些，因为 Vue 的模板语法对 SVG 支持得比较好。但要注意v-for渲染 SVG 元素时，key 要用唯一标识，否则动画状态可能会错乱。

我个人的建议是：如果时序图是静态的或者交互很简单，直接用原生 JS 操作 DOM 最省事。如果时序图需要和复杂的应用状态联动，那再考虑用框架封装。不要为了用框架而用框架，画图这件事本身并不复杂，引入框架反而增加了一层抽象成本。

5.5 处理特殊字符和中文标签

时序图里的标签经常包含特殊字符，比如<、>、&，这些在 SVG 里需要转义，否则会破坏 XML 结构。Archify 里用了一个简单的转义函数：

function escapeXML(str) { return str .replace(/&/g, '&amp;') .replace(/</g, '&lt;') .replace(/>/g, '&gt;') .replace(/"/g, '&quot;') .replace(/'/g, '&apos;'); }

中文标签的问题主要是字体。SVG 里的文字默认使用系统字体，不同操作系统渲染出来的效果可能不一样。如果你希望中文显示得好看一点，可以在 CSS 里指定字体栈：

.message-label { font-family: -apple-system, "PingFang SC", "Microsoft YaHei", sans-serif; }

另外，中文的字符宽度和英文不一样，布局计算时如果按英文字符宽度来估算，中文标签可能会超出预期宽度。稳妥的做法是用getBBox()方法获取文字的实际包围盒，然后根据实际宽度来调整布局。不过getBBox()也有个坑：它返回的是 SVG 用户坐标系里的尺寸，如果 SVG 被缩放了，实际显示尺寸还要乘以缩放比例。

6. 一些实操心得和扩展思路

6.1 我踩过的几个坑

第一个坑是在transitionend里做太多事情。我一开始把更新状态、触发下一条动画、更新按钮文案全写在transitionend回调里，结果发现有时候动画会跳帧。后来拆开了，transitionend里只做一件事：推进索引。其他事情用requestAnimationFrame异步处理，流畅度明显提升。

第二个坑是忘记处理prefers-reduced-motion。有些用户系统设置里开启了“减少动态效果”，这时候你的动画应该自动禁用或者简化。这是一个无障碍相关的细节，但很多人会忽略。实现很简单：

@media (prefers-reduced-motion: reduce) { .message-line { transition: none; } }

第三个坑是SVG 的overflow默认是hidden。如果你的图形超出了 viewBox 范围，会被裁掉。有时候你希望图形可以溢出显示，就需要设置overflow: visible。但这个属性在不同浏览器里的表现不太一致，最稳妥的做法还是把 viewBox 设置得足够大。

6.2 可以继续扩展的方向

Archify 目前的功能已经够用了，但如果你想继续折腾，有几个方向值得尝试。

支持从文本描述自动生成时序图。比如你写一段类似Client -> Server: request的文本，解析后自动生成图。这个功能在写文档的时候特别有用，你可以在 Markdown 里直接写时序描述，渲染时自动转成图。

支持导出为 GIF 或视频。现在的导出是静态 SVG，如果能把动画过程录制成 GIF，分享到聊天工具里会更方便。实现思路是用MediaRecorderAPI 录制 canvas，但需要先把 SVG 渲染到 canvas 上，这一步会丢失一些矢量特性。

支持主题切换。把颜色、字体、间距全部抽成 CSS 变量，然后提供几套预设主题，一键切换。这个功能实现起来不难，但对用户体验的提升很明显。

支持协作编辑。如果能把时序图数据存到后端，多个人同时编辑，那就变成了一个轻量级的在线协作工具。不过这个方向就复杂了，涉及到实时同步、冲突解决等问题，不是一个小项目能搞定的。

6.3 关于工具选型的个人建议

最后说一点关于工具选型的看法。Archify 这类工具的核心价值在于用代码描述图形，它适合的场景是：图的内容会频繁变化、需要版本控制、需要嵌入到文档或网页里。如果你的图是一次性的、不需要频繁修改，那用 draw.io 或者 Figma 手画可能更快。

我自己的做法是：架构图和时序图用代码生成，UI 设计图和流程图用手画。因为架构图和时序图的结构性很强，用代码描述很自然；而 UI 设计图更依赖视觉直觉，手画更灵活。这个分工不一定适合所有人，但至少对我来说，效率提升是很明显的。

另外，不要过度追求工具的完美。Archify 本身也不是一个完美的工具，它有很多限制，比如不支持自动换行、不支持复杂的嵌套激活块。但它的核心功能足够好用，而且代码不复杂，你可以随时 fork 一份改成自己需要的样式。这种“够用就好、可定制”的思路，我觉得比追求大而全的工具更务实。