企业官网建设流程全解析

• 文档
• 教程

Bug Race 是 app-ideas 项目集合中定级为3-Advanced的进阶项目，核心目的是用动画技巧构建一个"赌虫赛跑"游戏：用户为四条车道配置虫子图标、命名并选择速度档位，猜测谁将赢得比赛，然后观看虫子冲向终点线。本篇以 Bug-Race-Game.md 为骨架，完整拆解它的约束条件、全部用户故事与奖励功能，并结合仓库同类项目的设计风格，给出速度模型、动画循环、状态管理与校验逻辑的落地实现建议。读完你不仅拥有可直接照做的验收清单，还能掌握如何用原生语言特性（Canvas 动画、requestAnimationFrame、CSS 动画）实现一场不依赖动画库的实时竞速。

项目定位：为什么它属于 3-Advanced 档位

在 README.md 中，三个档位的划分依据是开发者的经验积累：Tier-3 面向已经具备 UI/UX 与 API 服务开发能力、正在学习更高级实现技巧（如后端应用、数据库服务）的开发者。Bug Race 被归入这一档位，原因并不在于技术栈的复杂度，而在于它横跨了多个"进阶"能力点：

• 动画体系设计：从素材（虫子图标）到驱动（每帧更新坐标）再到表现（冲线、停止、跳动、翻背）的完整动画管线；
• 多实体并发控制：四条车道的虫子以不同速度并行前进，且必须在"首个到达终点时全部停住"这一全局时序约束下工作；
• 随机性与可配置性的平衡：用户选定速度档位后，开发者需要在档位内部再做随机化，形成"用户可控 + 系统随机"的双层速度模型；
• 状态机与 UI 联动：Start 按钮的启用/禁用、赢家选择的合法性校验、比赛进行中的输入锁定，构成典型的前端状态管理场景。

从项目描述可以看出它的玩法本质（Bug-Race-Game.md）：让用户赛跑虫子，同时猜测谁会是赢家。用户故事要求提供一整套自定义控制：虫子图标、给虫子命名、选择潜在的赢家、调整比赛速度。

约束条件：规则先行的开发框架

原文档在需求正文中明确列出了四条硬性约束（Bug-Race-Game.md），它们共同决定了本项目的实现边界：

1. 开发者需要选择游戏中使用的虫子图标：图标素材的选型是开发者的职责，既可以从公开图库中寻找 3D 虫子素材，也可以使用 CSS/SVG 自行绘制，甚至用 emoji 作为轻量替代。原文档在资源部分给出的方向是"3D Bug Images"类图片素材，具体选型完全由实现者决定。
2. 比赛开始前，开发者应随机调整每条虫子的速度：让它们在用户选定的速度档位（慢、正常、快）之内以不同速率前进，避免四条虫子以完全相同的速度并驾齐驱——这是保证比赛观赏性与随机性的关键设计。
3. 慢/正常/快三个速度档位对应的速度范围由开发者自行定义：文档刻意不给出固定数值，把速度范围的数值设计留作练习的一部分（详见下文"速度模型设计"）。
4. 可以使用动画库，但用原生语言特性实现收益更大：这是本项目最值得投入的部分——自己实现动画能让你真正理解动画的底层机制（时间步进、坐标更新、重绘）。

界面骨架：用户故事的第一部分

原文档将基础用户故事拆成两个板块，首先是最基础的界面可见性（Bug-Race-Game.md）。用户可以看见：

• 一个输入面板：集中承载所有游戏配置与操作控件，承担游戏 UI 与运行参数的配置职责；
• 一条由四个水平车道组成的赛道：四条虫子分别在各自车道内行进，车道结构天然映射为四个"实体 + 各自状态"的对象；
• 与每条车道关联的单选按钮：用于让用户预先选择"潜在赢家"——这是竞猜玩法的核心交互；
• 一个 Start 按钮：触发整场比赛的启动。

这四个元素构成典型的"配置区（input panel）+ 展示区（赛道）"布局。值得一提的是，仓库中 Tier-2 的 Flip-Art-App.md 采用了"配置面板 + 操作按钮 + 展示面板"的三分结构，Tier-3 的 Boole-Bot-Game.md 也有"配置面板 + 竞技场 + 控制"的布局，说明配置区与展示区分离是该仓库动画/游戏类项目的通用惯例，Bug Race 可以沿用这一布局思路。

游戏控制区：逐项落实

输入面板内部的控制项（Bug-Race-Game.md）包含：

• 车道编号列表：每一条车道对应一个条目，条目内包含——
  • 一组单选按钮，用于在三种独特虫子图标之间选择本车道使用的虫子；
  • 一个缩略图预览，直观展示当前选中的图标；
  • 一个文本框，供用户为虫子命名。
• 速度选择控件：三枚单选按钮（Slow / Normal / Fast），全局控制本次比赛的档位。

对应产生的交互故事包括：

• 用户点击单选按钮即可为车道分配虫子图标；
• 如果同一个图标被超过一条车道选中，界面必须给出警告提示；
• 用户可以为每条车道的虫子输入名字；
• 如果同一个名字被重复使用，界面必须显示错误信息；
• 用户通过速度单选按钮选定比赛速度。

这里要注意一个细节：图标"重复选中"用的是警告（warning），而名字"重复使用"用的是错误（error），两者在文案强度与视觉呈现上应当有所区分——警告可以允许用户继续操作，而错误往往意味着流程需要阻断或至少被显著提示。

竞速流程：比赛时序与状态机

第二板块是比赛过程中的用户故事（Bug-Race-Game.md）：

1. 用户点击任意车道上的单选按钮，选定潜在赢家；
2. 用户点击 Start 按钮启动比赛；
3. Start 按钮在比赛结束前保持禁用状态——防止比赛进行中被重复触发或修改配置；
4. 如果用户没有选择赢家就点击 Start，界面必须显示错误信息；
5. 虫子在其所属车道内朝终点线竞速；
6. 当第一条虫子到达终点线时，所有虫子立即停止移动；
7. 游戏指标更新，显示本次会话（session）已进行的比赛场次数。

第 6 条是全局时序约束的关键：四条虫子在各自循环中前进，但"全部停止"必须在某一只到达终点的瞬间同时生效。这要求比赛循环对"是否有人冲线"做统一判定，而非每只虫子各自为政。

会话指标与逐虫指标

文档明确要求至少维护一个全局指标：本 session 内的比赛场次数（Bug-Race-Game.md）。奖励功能进一步要求为每条虫子维护独立指标：比赛场数、胜场数、负场数（Bug-Race-Game.md）。这暗示数据模型应当同时存在两个层级：

• sessionStats：{ racesRun: number }，会话级；
• bugStats[bugId]：{ races: number, wins: number, losses: number }，虫子级。

胜/负的判定时机与"第一个到达终点"一致：冲线的那只记胜，其余在本次比赛中"落败"。这里的负场数语义可以由开发者定义为"参加了该场比赛但未获胜"，需要注意在并列冲线等边界情形下的口径一致性（例如是否允许平局）。

速度模型设计：档位、随机化与数值建议

原文档刻意没有给出任何具体数值，把速度范围的定义权交给开发者（Bug-Race-Game.md）。但结合约束条件可以推导出完整的速度模型应该包含两层：

第一层：档位选择。用户通过 Slow / Normal / Fast 单选按钮选定全局档位，这个档位决定速度范围。

第二层：档内随机化。比赛开始前，为每条虫子在其所在档位范围内随机生成一个具体速度，使同一档位下四条虫子速率各不相同。

作为实现参考（以下数值仅为本篇文章给出的建议，并非仓库规定），可以定义如下：

对应的实现示意（参考实现思路，非仓库源码）：

const SPEED_RANGES = { slow: [80, 120], normal: [150, 220], fast: [260, 360], }; function randomSpeed(level) { const [min, max] = SPEED_RANGES[level]; return min + Math.random() * (max - min); }

设计速度范围时有几个实用要点：

• 范围上下限之间要有足够跨度，保证同档位内拉开差距，避免四条虫子总是咬得很近；
• 上限要考虑赛道宽度与"比赛时长"的乘积关系，让一场比赛保持在数秒量级、不至于让用户失去耐心；
• 随机化应在每次startRace()调用时重新执行，确保每场比赛结果不可预测，竞猜玩法才有意义。

动画技术选型：原生实现 vs 动画库

原文档明确指出（Bug-Race-Game.md）：可以使用动画库，但用原生语言特性实现收益更大。这与仓库其他动画类项目的取向一致——Flip-Art-App.md 明确要求开发者不要依赖动画或图形库，尽量用原生 Javascript、CSS、HTML 实现。

针对本项目的三种主流原生方案：

1. Canvas 2D + requestAnimationFrame：最贴合本项目的方案。赛道、虫子、终点线统一绘制在 canvas 上，requestAnimationFrame驱动每帧坐标更新。MDN 的 Basic Animations 教程正是围绕这一思路展开的，也是原文档资源部分强调的重点。
2. CSS Animations / Transitions：虫子可用transform: translateX()配合 CSS 过渡或关键帧动画实现。缺点是"比赛结束立即停住"这类精确时序控制需要配合 JavaScript 动态控制动画时长与暂停，不如 Canvas 直观。
3. DOM 元素逐帧更新：每帧用 JavaScript 直接修改元素style.left，与方案 1 原理一致但操作 DOM 成本更高。

推荐采用Canvas + requestAnimationFrame，核心游戏循环骨架如下（参考实现思路）：

function raceLoop(timestamp) { const dt = (timestamp - lastTime) / 1000; // 秒 lastTime = timestamp; let finished = false; bugs.forEach((bug, i) => { if (!bug.finished) { bug.x += bug.speed * dt; // 每帧按速度前进 if (bug.x >= finishLineX) { // 冲线判定 bug.finished = true; finished = true; onBugWins(bug); } } }); if (finished) { stopAll(); // 全部停止：不再更新位置 renderFinalState(); return; // 退出循环 } render(); // 重绘赛道与虫子 requestAnimationFrame(raceLoop); }

关于精灵动画（sprite animation）：如果选择的虫子图标是多帧精灵图，可以结合逐帧切换实现爬行/振翅等动作，原文档资源部分也收录了 sprite 动画的构建教程作为参考方向。实现时通过setInterval或帧计数切换精灵帧即可，与位移动画解耦。

校验与错误处理：可运行的前提条件

原文档通过三个负面场景刻画了输入校验的边界：

一个值得注意的时序问题：配置区在比赛进行中应处于锁定状态（Start 按钮禁用即隐含这一要求），否则用户在比赛中途改图标、改名字、改速度会导致状态不一致。因此合理的设计是引入一个state枚举（CONFIGURING/RACING/FINISHED），在非CONFIGURING状态下禁用配置区全部控件。

校验逻辑的参考实现：

function validateConfig() { const icons = lanes.map(l => l.icon); const names = lanes.map(l => l.name.trim()); const iconDuplicated = hasDuplicate(icons); // 触发 warning const nameDuplicated = hasDuplicate(names); // 触发 error const noWinnerPicked = winnerLane === null; // 触发 error return { iconDuplicated, nameDuplicated, noWinnerPicked }; }

错误/警告信息应就近展示在输入面板中，并明确指向出问题的车道（例如"Lane 2 与 Lane 3 使用了相同的名字"），便于用户定位修复。

奖励功能：从"能玩"到"好玩"

基础用户故事交付一个可运行的竞速游戏后，原文档给出四组奖励功能（Bug-Race-Game.md），它们从"数据、表现、听觉"三个维度提升体验：

1. 逐虫比赛指标：每只虫子显示比赛场数、胜场数、负场数。这要求指标数据跨比赛持久于 session 内，并与"会话比赛次数"统一维护。实现上可将统计挂在虫子对象上，比赛结束时统一回写。
2. 获胜虫子跳动（bounce）：冲线获胜后，获胜者播放弹跳动画。实现上可在onBugWins后对获胜虫子的 y 坐标叠加正弦函数y = baseY + amplitude * Math.sin(t * frequency)，持续 1~2 秒。
3. 落败虫子翻背（flip on backs）：失败虫子翻转 180° 倒地。可用 CSS 过渡transform: rotate(180deg)或 Canvas 中的逐帧旋转绘制实现。
4. 开始与结束音效：比赛启动与结束时播放独特音效。Web Audio API 的AudioContext可合成简单音效而无需外部音频文件；若使用<audio>元素，注意用户交互后初始化播放以符合浏览器自动播放策略。

从仓库其他 Tier-3 项目看，这类"表现层增强"是进阶项目的常见加分方向：Shell-Game.md 的奖励功能同样包含得分面板与获胜动画；Elevator-App.md 也包含到达楼层音效等听觉反馈。Bug Race 的音效与动画增强与之同属一个设计脉络。

完整验收清单

综合原文档全部用户故事与奖励功能，一份可直接用于自测的验收清单如下：

基础功能

• 输入面板、四车道赛道、车道赢家单选按钮、Start 按钮可见；
• 每个车道条目含图标单选按钮（三种图标）、缩略图、命名文本框；
• 速度选择区含 Slow / Normal / Fast 三枚单选按钮；
• 点击图标单选按钮可为本车道分配图标；
• 同一图标被多车道选中有警告提示；
• 可输入虫子名字，同名有错误提示；
• 可点击速度单选按钮切换档位；
• 可点击车道单选按钮选择潜在赢家；
• 点击 Start 启动比赛；
• 比赛期间 Start 按钮禁用；
• 未选赢家时点 Start 显示错误；
• 虫子沿各自车道冲向终点线；
• 第一条冲线后所有虫子立即停止；
• 会话内比赛场次数实时更新。

奖励功能

• 每只虫子显示场数、胜场、负场；
• 获胜虫子播放跳动动画；
• 落败虫子翻背倒地；
• 比赛开始与结束时播放不同音效。

资源与进阶方向

原文档在资源与示例部分（Bug-Race-Game.md）给出的学习材料集中在三类：3D 虫子图片素材检索、Canvas 基础动画教程（MDN）、以及 JavaScript 动画与 sprite 动画的构建方法——这些资源指向的能力点正是上文反复强调的 Canvas 绘制、帧循环与精灵动画，建议按"先 Canvas 基础动画 → 再精灵动画 → 最后独立设计速度模型"的顺序推进学习。文档还列举了若干同类参考项目（街机游戏、拖车竞速动画、赛马），可作为交互风格与视觉呈现的参照样本，但最终实现仍应以本文档的用户故事为准。

若你希望将 Bug Race 作为提交回仓库的完整项目，可参考 Example Guide.md 的模板结构（目标描述、User Stories、Bonus features、Resources、Example projects）整理项目说明，并遵循 CONTRIBUTING.md 的贡献流程——该仓库本身即由这样一套"创意文档 + 示例实现"的机制驱动。完成本项目的核心目标只有一个：用最原生的方式，把四条虫子跑起来，并把"猜赢家"的乐趣做到位。

• 文档
• 教程