用 JavaScript 实现赛程对阵图生成器（Sports Bracket Generator）：单败淘汰赛对阵图的原理、需求拆解与前端实战指南

• 文档
• 教程

本文围绕本仓库中的 Sports-Bracket-Generator 项目规格文档（位于Projects/2-Intermediate目录，属于 2-Intermediate 层级），讲解如何从零构建一个在浏览器中自动绘制锦标赛赛程对阵图（Bracket）的 Web 应用。你将掌握对阵图"横向树形图 + 逐轮减半"的核心结构原理、5 条用户故事对应的输入校验与验收标准，以及包括赛程生成算法、CSS 布局渲染和 localStorage 持久化在内的完整实现方案。

一、项目背景：这份规格文档要求什么

在足球、棒球、板球乃至电子竞技锦标赛中，追踪球队晋级过程是一种常见需求。传统做法是手工绘制一张水平树形图（horizontal tree diagram）：所有首轮比赛列在最左侧，每场比赛结束后胜者与相邻比赛的胜者进入下一轮，如此逐轮推进，直到最右侧仅剩最终的冠军。

Sports-Bracket-Generator.md 定义的应用，正是要把这个"手工画图"的过程自动化：在浏览器窗口中绘制对阵图，让用户免于手动排版。它被归入本仓库 README.md 中的 2-Intermediate（中级）层级——按仓库定义，该层级面向已经熟悉 UI/UX、开发工具，并能构建调用 API 服务的应用的开发者，因此这份规格天然适合作为前端技能的练手项目。

从文档结构看，它遵循了 Example Guide.md 定义的标准模板：目标描述 → User Stories（用户故事）→ Bonus features（进阶功能）→ 参考链接与示例项目。这也意味着：仓库提供的是需求规格而非成品代码，技术栈完全由实现者自由选择，本文给出的实现方案是一种可直接落地的参考设计。

二、核心原理：对阵图的结构与轮次数学

文档对对阵图结构给出了精确描述，这是整个应用的数据模型基础：

• 每个纵列（Column）代表一轮（Round）；
• 最左侧纵列展示全部首轮比赛；
• 每个纵列的队伍数量 = 左侧相邻纵列队伍数的1/2，同时是右侧相邻纵列队伍数的2 倍；
• 队伍数从左到右逐列递减，直到最后一列只包含最终的冠军。

以 8 支队伍、单败淘汰制（Single-Elimination）为例，对阵图列结构如下：

由此可以归纳出三条可直接用于编码的规则（设队伍总数为 N，且 N 为 2 的幂）：

1. 总比赛场次恒为 N − 1（每场比赛淘汰一支队伍，最终只剩 1 支冠军）；
2. 轮次（纵列）数为 log₂(N)，例如 8 队 4 列、16 队 5 列；
3. 第 k 列（从 1 计数）的队伍数为 N / 2^(k−1)，即每向右一列队伍减半。

如果 N 不是 2 的整数次幂（比如 6、10、14 支队伍），则会产生"轮空（Bye）"或"某些轮次队伍数不均"的情况——这正是规格文档要求对奇数队伍数给出警告的原因，我们会在第五节详述处理策略。

三、User Stories 逐条拆解与验收标准

文档列出 5 条必须实现的用户故事，每条都可以转化为明确的验收条件。建议在开发前先建立这张"故事 → 验收"对照表，逐条勾选推进：

规格文档特别强调：这两条警告（invalid date / odd teams）是进入生成流程前的门槛，属于表单校验（Form Validation）的核心场景。建议采用"即时校验 + 提交时再次校验"双保险：输入框失焦（blur）即校验，点击生成按钮时统一校验一次。

值得注意的是，规格文档的 User Stories 前 3 条（名称、日期、队伍数）仅要求"能输入"，即允许用户先只填队伍数、不填具体队名就生成空骨架对阵图——这是 MVP 的关键取舍，先把结构画出来，队名、比分等细节留给进阶功能。

四、输入校验：日期与队伍数的可靠实现

规格文档对校验提出了明确要求，这里给出一个可直接复用的校验函数。它同时覆盖"日期非法"和"奇数队伍数"两类场景，并返回错误数组供 UI 逐条展示：

/** * 校验赛事配置，返回错误信息数组（为空表示通过）。 * @param {{ name: string, startDate: string, endDate: string, teamCount: number }} config */ function validateTournament({ name, startDate, endDate, teamCount }) { const errors = []; // 1. 赛事名称必填 if (!name || name.trim() === '') { errors.push('Tournament name is required.'); } // 2. 日期必须可解析，且结束日期不能早于开始日期 const start = Date.parse(startDate); const end = Date.parse(endDate); if (!startDate || Number.isNaN(start)) { errors.push('Start date is invalid.'); } if (!endDate || Number.isNaN(end)) { errors.push('End date is invalid.'); } if (start && end && start > end) { errors.push('End date must not be earlier than the start date.'); } // 3. 奇数队伍无法构成平衡的单败淘汰对阵，必须警告 if (!Number.isInteger(teamCount) || teamCount < 2) { errors.push('At least 2 teams are required.'); } else if (teamCount % 2 === 1) { errors.push('An odd number of teams cannot form a balanced bracket. ' + 'Please add one more team or remove one.'); } return errors; }

关于"奇数队伍"的处理，有三种业界常见的策略，可在实现时选择其一并在 UI 中说明：

1. 严格模式（推荐 MVP）：拒绝奇数队伍，要求用户调整到偶数——对应规格文档"警告"的默认语义；
2. 轮空（Bye）模式：为奇数队伍分配一个轮空名额，该队自动晋级下一轮，其余队伍正常配对；
3. 首轮配对不均：允许其中一场只有 1 支队伍，本质上仍是轮空。

无论采用哪种策略，校验结果都应渲染为可见的警告文案（如红色提示条），而不是静默失败。

五、数据模型与核心算法：如何生成各轮次对阵

对阵图本质上是一棵由"比赛（Match）"节点组成的树。推荐的数据模型如下：

// 一场比赛：包含对阵双方、比分、日期与胜者 { id: 'r1-m0', // 唯一标识，便于定位渲染位置 teamA: 'Team A', // 左侧参赛队（首轮为真实队名，后续轮次由晋级填充） teamB: 'Team B', // 右侧参赛队 scoreA: 2, // 可空，null 表示未完成 scoreB: 1, date: '2026-04-01', // 可空 winner: 'Team A' // 由 scoreA/scoreB 推导得出 } // 赛事配置 { name: 'Spring Cup 2026', startDate: '2026-03-28', endDate: '2026-04-05', teamCount: 8, teams: ['Team A', 'Team B', /* ... */], rounds: [/* 二维数组：rounds[0] 为第 1 轮，依此类推 */] }

对阵图生成算法分两步：首轮两两配对→逐轮生成空位（晋级位），直到只剩一场决赛。核心逻辑如下：

/** * 根据队伍数组生成完整的轮次结构（单败淘汰）。 * 假设 teamNames 长度为 2 的幂，否则需先经校验或补轮空。 */ function buildBracket(teamNames) { const rounds = []; const n = teamNames.length; // 第 1 轮：两两配对 const round1 = []; for (let i = 0; i < n; i += 2) { round1.push({ id: `r1-m${round1.length}`, teamA: teamNames[i], teamB: teamNames[i + 1], scoreA: null, scoreB: null, date: null, }); } rounds.push(round1); // 后续轮次：场次数逐轮减半，队伍位置留待胜者晋级填充 let prev = round1; while (prev.length > 1) { const roundIndex = rounds.length + 1; const next = []; for (let i = 0; i < prev.length; i += 2) { next.push({ id: `r${roundIndex}-m${next.length}`, teamA: null, teamB: null, scoreA: null, scoreB: null, date: null, }); } rounds.push(next); prev = next; } return rounds; }

当某场比赛录入比分后，需要把胜者"晋级"到下一轮对应比赛的槽位。晋级规则可用一个纯函数表达，便于单元测试：

/** 根据比分判定胜者；平局需返回 null 并提示用户定义加赛规则 */ function winnerOf(match) { if (match.scoreA === null || match.scoreB === null) return null; if (match.scoreA > match.scoreB) return match.teamA; if (match.scoreB > match.scoreA) return match.teamB; return null; // 平局：需补充加时/点球等规则 } /** 将 round 中所有已完赛的胜者推进到 nextRound 的对应槽位 */ function advanceWinners(round, nextRound) { round.forEach((match, index) => { const winner = winnerOf(match); if (winner === null) return; const target = nextRound[Math.floor(index / 2)]; if (index % 2 === 0) target.teamA = winner; else target.teamB = winner; }); }

注意这里用到了Math.floor(index / 2)的映射关系：第 k 轮的第 i 场比赛，其胜者将进入第 k+1 轮的第⌊i/2⌋场比赛，且偶数序号进左侧（teamA）、奇数序号进右侧（teamB）。这段逻辑与文档"胜者与相邻比赛胜者进入下一轮"的描述严格对应。

六、界面布局与渲染：用 CSS 复现"横向树形图"

对阵图在浏览器中的渲染，建议采用flex 横向排列的列（round）+ 纵向均匀分布的比赛卡片（match）结构，配合overflow-x: auto支持横向滚动，天然复现文档描述的"列数递增、队伍减半"的横向树形图。

HTML 骨架示例：

<div class="bracket" id="bracket"> <section class="round"> <h2>Round 1</h2> <div class="match"> <span class="team">Team A</span> <input class="score" type="number" min="0" placeholder="比分"> <span class="team">Team B</span> <input class="score" type="number" min="0" placeholder="比分"> </div> <!-- 更多比赛卡片... --> </section> <!-- 更多轮次列... --> </div>

CSS 布局核心（要点示意）：

.bracket { display: flex; /* 每个 round 是一个纵向列，从左到右排列 */ gap: 2rem; /* 列间距，同时为连接线留出空间 */ align-items: center; overflow-x: auto; /* 队伍多时横向滚动 */ padding: 1rem; } .round { display: flex; flex-direction: column; /* 本轮的比赛纵向排布 */ justify-content: space-around; /* 各比赛在列内均匀分布 */ gap: 1rem; min-width: 200px; } .match { border: 1px solid #ccc; border-radius: 4px; padding: 0.5rem 1rem; background: #fff; min-width: 200px; position: relative; } .score { width: 48px; text-align: center; }

渲染逻辑本身非常简单：遍历rounds数组，为每个轮次生成一个.round列，再为列内每场比赛生成一个.match卡片；比分为空的比赛显示为占位（晋级位）。注意：不要在 JS 中动态拼复杂 CSS 字符串，把布局责任交给 CSS，JS 只负责填充数据——这是对阵图类应用保持可维护性的关键。

如需更精细的"晋级连线"效果（胜者卡片与下一列对应比赛之间的斜线/折线），可用伪元素或 SVG 实现，这属于对规格文档"绘图表"目标的锦上添花，不影响核心功能验收。

七、进阶功能（Bonus Features）实现指南

规格文档列出 4 条可选进阶功能，完成基础用户故事后再逐步添加。下面给出各自的实现要点：

7.1 输入每场比赛的参赛队伍名称

把第四节中的teamNames数组替换为每场比赛独立可编辑的队名输入框。实现上即让每个.match卡片内的两个队名变为可编辑文本（<input>或contenteditable），在生成骨架时按队伍总数预先铺好N/2场首轮比赛的空队名槽位。

7.2 输入每场比赛的日期

为每个.match卡片增加一个日期选择器（<input type="date">），值存入match.date。可选增强：与赛事开始/结束日期联动校验，保证单场比赛日期落在赛事区间内。

7.3 输入每场比赛的最终比分

为每个队名旁增加比分输入框（如第六节骨架中的score输入框）。录入比分后调用第五节中的winnerOf与advanceWinners自动晋级胜者，并对胜者卡片做高亮标记。建议把"比分已填完的比赛自动晋级"与"手工点击晋级"做成可切换的两种模式，后者更贴近真实赛事录入的容错需求。

7.4 数据跨会话持久化

文档要求"数据在会话之间持久存在"，前端最直接的做法是localStorage。封装一个带容错的存取层：

const STORAGE_KEY = 'sports-bracket-generator'; function saveTournament(state) { localStorage.setItem(STORAGE_KEY, JSON.stringify(state)); } function loadTournament() { try { return JSON.parse(localStorage.getItem(STORAGE_KEY)) || null; } catch { // JSON 损坏时返回 null，避免整个应用崩溃 return null; } }

建议在loadTournament()返回数据后，用第四节的validateTournament再做一次持久化数据校验，防止旧数据或损坏数据渲染出非法对阵图。若未来要求支持多设备同步，可在此基础上接入后端 API——这与仓库 README 中 3-Advanced 层级"实现后端应用与数据库服务"的能力定位衔接。

八、测试策略与验收清单

本文实现方案中的算法逻辑（轮次生成、胜者晋级、日期与队伍数校验）均为纯函数，非常适合单元测试。建议至少覆盖以下用例：

• 轮次数学：8 支队伍应生成 4 列、共 7 场比赛；16 支队伍应生成 5 列、共 15 场比赛；
• 晋级映射：第 1 轮第 0 场胜者进入第 2 轮第 0 场的 teamA 槽位，第 1 场胜者进入 teamB 槽位；
• 校验边界：开始日期晚于结束日期、空名称、2 支队伍（合法下限）、3 支队伍（奇数警告）、非数字队伍数；
• 持久化容错：损坏的 JSON 应被loadTournament捕获并返回 null，而不是抛异常。

最终逐条对照第五节验收表走一遍手工测试：输入非法日期应看到警告、输入奇数队伍数应看到警告、合法配置应渲染出正确规模的对阵图——即为完成本项目的基础验收。之后可继续迭代 7.1–7.4 的进阶功能，逐步逼近一个可投入真实赛事管理的完整应用。

九、文档补充信息与仓库上下文

原始规格文档还提供了两类辅助资料：

• Useful links and resources：指向维基百科的"Bracket (tournament)"词条，用于理解对阵图/锦标赛的通用定义与变体（双败淘汰、循环赛等），建议在动手前通读以扩展赛制视野；
• Example projects：给出两个社区示例——一个"Pure CSS & DOM Sports Bracket"（纯 CSS 与 DOM 实现）和一个"Responsive Sports Bracket"（响应式对阵图），可作为布局与交互的视觉参考，但注意它们多为静态演示，不具备本文所述的完整数据录入能力。

从仓库整体看，README.md 将本项目定位为 2-Intermediate 层级并归入"Generate a sports bracket diagram"条目；CONTRIBUTING.md 与 Example Guide.md 则说明了此类规格文档的标准模板。如果你完成了本应用并想把它作为示例提交回仓库，可以参照贡献指南操作——但更重要的收获是：你已经完整走通了"读规格 → 拆需求 → 建数据模型 → 实现算法 → 渲染 UI → 持久化"的整条前端开发链路，这套方法论同样适用于本仓库中 2-Intermediate 目录下的其他项目 以及任何一份产品需求文档。

• 文档
• 教程