羽球搭子 HarmonyOS 实战（16）：实时计分页的状态机设计

一、计分页最怕状态由按钮文字暗示实时计分看起来只是两个“1”按钮实际同时约束比赛是否进行、采用哪种赛制、比分能否修改、是否达到结束条件、是否已经落盘以及结束后是否允许重复提交。如果这些规则散落在多个点击回调中21:20、30:29、抢 21 和普通 21 分制会出现互相矛盾的结果。稳妥的实现是把比赛建模为显式状态机。playing状态接受加分、减分、直接录入和撤销每次变化后统一执行赛制判定命中结束条件后进入finished冻结按钮并触发保存。ArkUI 页面只根据状态渲染不自行推断比赛是否结束。HarmonyOS 状态管理的基础概念可参考ArkUI 状态管理概述。二、领域状态要比 UI 状态更精确计分卡片至少需要比赛标识、关联对局标识、计分制、双方名称与比分、比赛状态、胜方、开始时间和结束时间。弹窗是否展开、快捷比分面板是否显示属于 UI 状态不应进入比赛实体。这样即使换成平板双栏或语音计分入口领域模型仍保持一致。字段约束参与的状态转换status只能是 playing/finished决定所有计分按钮可用性scoringSystem创建比赛后固定决定结束阈值与领先分scoreA/scoreB非负整数每次变化后触发结束判定winnerplaying 时为空finished 时必须是 A 或 BendedAtplaying 时为 0finished 时写入时间戳linkedSessionId可为空非空时结束后回写正式对局状态字段不能互相打架。例如statusfinished但winner统计页就无法判断胜方playing却带有endedAt恢复后可能被误当作已完成。创建副本时应一次写全相关字段而不是分多次更新。三、所有比分变化走同一个入口按钮回调只传递队伍和变化量统一入口负责查找比赛、检查状态、收敛非负数、记录可撤销动作、替换数组元素并触发结束判定。这样“加一分”“减一分”和未来的蓝牙遥控器都复用相同规则。updateScore(matchId: string, team: A | B, delta: number): void { const next this.matches.slice() const index next.findIndex((item: ScoreMatch) item.id matchId) if (index 0 || next[index].status ! playing) return const current next[index] const scoreA team A ? Math.max(0, current.playerA.score delta) : current.playerA.score const scoreB team B ? Math.max(0, current.playerB.score delta) : current.playerB.score this.recordHistory(matchId, team, delta, current, scoreA, scoreB) next[index] this.copyWithScore(current, scoreA, scoreB) this.matches next this.checkAutoFinish(matchId) }这里先复制数组再替换元素确保 ArkUI 能观察到引用变化。Math.max(0, ...)只是一层底线更重要的是playing门禁它阻止已结束比赛继续被减分“复活”。四、赛制判定必须是纯函数结束规则不应该直接操作页面。纯函数接收赛制和比分返回胜方或空值便于覆盖边界测试。普通 21 分制要求至少 21 分且领先 2 分抢 21 到点且不平分即可结束15 分制同理一分到底等特殊玩法也可以作为独立策略扩展。function resolveWinner(system: ScoringSystem, a: number, b: number): Team | { const lead Math.abs(a - b) if (system 21-point Math.max(a, b) 21 lead 2) { return a b ? A : B } if (system 21-point-rush Math.max(a, b) 21 a ! b) { return a b ? A : B } if (system 15-point Math.max(a, b) 15 lead 2) { return a b ? A : B } if (system 100-point-rush Math.max(a, b) 100 a ! b) { return a b ? A : B } return }场景普通 21 分制抢 21预期20:20未结束未结束平分继续21:20未结束A 胜普通制还差领先 2 分22:20A 胜A 胜状态进入 finished30:29未设置封顶时继续A 胜规则必须与产品定义一致20:22B 胜B 胜胜方与结束时间同时写入五、结束转换要保证只执行一次快速双击可能让两次1几乎同时进入回调。结束函数再次检查当前状态只有仍为playing才创建结束副本。随后清空撤销栈、持久化比分并根据是否关联正式对局决定同步路径。重复调用直接返回避免一场比赛生成两条保存记录。finishMatch(matchId: string, winner: Team): void { const next this.matches.slice() const index next.findIndex((item: ScoreMatch) item.id matchId) if (index 0 || next[index].status finished) return const current next[index] next[index] { ...current, status: finished, winner, endedAt: Date.now() } this.matches next this.scoreHistory.delete(matchId) this.persistFinishedMatch(next[index]) }保存失败也不应把比赛退回playing。本地结果先保存并给出明确提示云端失败进入待同步状态否则用户已经看到结束画面却因为网络错误突然回到可计分状态会造成更严重的数据不一致。六、直接录入是一条新的比分基线裁判可能从纸面记录补录 18:16或者修正误操作后的整段比分。直接录入与连续点击不同它不知道每一分由哪一队获得因此不能保留旧撤销栈。输入需要校验为有限、非负整数并按赛制设置合理上限写入后清空历史再执行统一结束判定。applyDirectScore(matchId: string, rawA: string, rawB: string): boolean { const a Number(rawA) const b Number(rawB) if (!Number.isFinite(a) || !Number.isFinite(b) || a 0 || b 0) { return false } const max this.scoringSystemOf(matchId) 100-point-rush ? 200 : 50 const scoreA Math.min(max, Math.floor(a)) const scoreB Math.min(max, Math.floor(b)) this.replaceScore(matchId, scoreA, scoreB) this.scoreHistory.delete(matchId) this.checkAutoFinish(matchId) return true }直接录入达到结束条件时同样进入finished不能绕过保存链路。若比分超过产品上限应在输入框旁提示收敛结果避免用户以为录入的 999 分被完整保存。七、语音和动画是状态的副作用比分播报、局点动画和振动反馈都应该在状态更新成功之后触发。播报函数需要知道旧比分和新比分才能避免减分或无效点击重复朗读自动结束发生后则优先播报比赛结果不再播报普通比分。副作用失败不能影响比分本身。private afterScoreChanged(matchId: string, before: Score, after: Score): void { const current this.findMatch(matchId) if (current undefined) return if (current.status finished) { this.speakResult(current) return } if (before.a ! after.a || before.b ! after.b) { this.speakScore(after) } }把副作用和状态转换分开后即使设备没有可用语音引擎计分仍然可靠平板布局只需要订阅相同比赛模型不需要复制一套结束判断。八、围绕边界比分做验收计分状态机的测试重点不是 0:0 到 1:0而是临界状态和重复操作。每一种赛制至少验证一组未结束、刚好结束和结束后继续点击的场景。1. 普通 21 分制输入 20:20双方各加 1 分确认 21:21 仍在进行。 2. 再连续形成 23:21确认只结束一次胜方为 A按钮全部禁用。 3. 抢 21 输入 21:20确认立即结束普通制下同比分不得结束。 4. 在 0:0 连续减分确认比分不低于 0也不产生撤销记录。 5. 对已结束比赛再次点击加分、重置和直接录入确认状态不变化。 6. 结束时关闭网络确认本地结果保留并出现可理解的同步提示。九、总结实时计分页的核心是一组受控状态转换而不是一排按钮。领域模型明确playing与finished比分变化统一进入一个函数赛制判定保持纯净结束转换具备幂等保护直接录入重建撤销基线语音等副作用不干扰主状态。这样才能让手机、平板、语音和云同步共用一套比赛规则。