做了几十个独立的小功能之后，很多人会遇到一个共同的瓶颈：单个知识点都看得懂，但真要组合成一个完整应用，脑子里还是一团浆糊。我身边就有同事卡在“组件会写了，路由也会跳了，状态管理背了一堆概念，结果一动手就不知道先写哪一行”的状态。所以当我在整理“HarmonyOS应用实例60总复习”这个系列时，特意把“算术大闯关”放到总复习的位置——它不是一个新知识点的堆砌，而是把前面五十九个实例里反复出现的状态管理、页面路由、自定义组件、生命周期、本地存储全部串起来的一次综合演练。这篇博客我就以这个练手项目为主线，把从需求拆解、数据结构设计、交互实现到真机调试踩坑的完整过程分步骤讲清楚，适合那些已经掌握HarmonyOS基础组件和ArkTS语法、想通过一个完整项目打通全流程的开发者阅读。
1. 选它做总复习不是偶然：一个案例把前面的知识全串起来了
单独练组件也好，单独练路由也好，练完之后总有同一个感觉：“我好像会了，又好像什么都不会。”因为真实应用永远是多种机制叠加在一起运作的，“算术大闯关”恰好把这些问题一次性暴露出来。
1.1 六张知识点支票，在这个项目里一次性兑现
这个项目表面上是一个算术答题闯关游戏，实际上它的每一环都踩在HarmonyOS应用开发的关键知识点上。我在做需求拆解的时候，专门列过一张对照表，把“功能点”和“底层能力”对应起来。
| 功能点 | 涉及的核心知识点 |
|---|---|
| 关卡选择页 | 列表组件、栅格布局、页面生命周期 |
| 答题页倒计时 | 定时器、状态更新、延迟任务清理 |
| 题目随机生成 | 随机数算法、运算逻辑、数据模型设计 |
| 选项点击判分 | 交互事件、动态样式切换 |
| 积分与连击 | 状态管理、数据双向同步 |
| 关卡推进与结算 | 路由跳转、参数传递、本地持久化存储 |
把这些对应关系摆出来之后，文章的逻辑就清晰了：前面单个实例练的是“点”，这个项目练的是“面”。比如状态管理，单独写一个计数器很简单，但在答题页里，正确答案、剩余时间、当前得分、连击次数是同时变化的，它们之间还有依赖关系——连击次数会影响单题得分，倒计时归零必须强制进入下一题。这种复杂联动才是真实开发里的常态，“算术大闯关”一上来就把这个难点直接摆在面前。
1.2 难度阶梯：为什么从加法到混合运算恰好对应开发门槛
这个应用在题目难度设计上也暗合了开发门槛的递进。第一关是20以内的加法，第二关是不退位减法，第三关是乘法口诀，第四关是混合运算，每关的题目数量从5道递增到10道，答题时间从30秒逐步压紧。这样的设计不是拍脑袋定的，它实际上对应了开发过程中数据模型从简单到复杂的演进路径。
从开发角度看，第一关只需要处理两个正整数的加法，生成题目和校验答案的逻辑最简单，非常适合先把整体页面框架跑通；等到第三关出现乘法，第四关出现“先乘除后加减”的混合运算，题目表达式的生成逻辑、运算符优先级处理、选项干扰项生成策略都要跟着升级。如果你一上来就做混合运算，很容易被带偏，连基础框架都搭不利索。
我在实际做这个项目的过程中也刻意遵循了这种递进思路：先把第一关的完整链路跑通——从主页进入答题页、答完5道题出结算、返回主页，然后才去扩展第二、三、四关的题目逻辑。这样做的好处是，每一步都能看到一个可运行的结果，不至于写了一大堆代码却连界面都看不到。
2. 写代码前先把数据模型定好：闯关规则这样设计才不会返工
很多初学者拿到题目就开始写UI，写完UI发现不知道数据往哪里放，这是个非常低效的路径。我的习惯是先把数据模型和闯关规则在脑子里完整过一遍，哪怕只是画几张草稿图，也能避免后面反复推翻重来。
2.1 关卡结构与题目生成策略
“算术大闯关”的规则看起来简单，但细节其实不少。四关分别是加法、减法、乘法、混合运算，每关题目数量不同、时间不同、积分倍率也不同。为了让数据模型支撑得起这些规则，我定义了一个关卡配置对象，而不是把每个关卡写死成独立的页面逻辑。
interface LevelConfig { levelId: number // 关卡编号 title: string // 关卡名称，如“加法热身” questionCount: number // 本关题目数量 timeLimit: number // 本关时限，单位：秒 scorePerQuestion: number // 基础单题得分 operator: string[] // 使用的运算符 range: number // 数值范围的上限 }这里有个容易被忽视的设计：混合运算关卡的range不能简单设成一个很大的数，否则会出现 13 × 17 这种对小学生过于疯狂的计算。我实测下来，混合运算关卡的合理范围是让每个操作数都不超过12，这样乘法表范围内的乘法和两位数加减都能覆盖，选项之间的差距也刚好不会一眼看出答案。
题目生成的核心逻辑是随机数加运算符组合。以混合运算为例，我采用了两段式生成：先随机决定“是否含乘法”，再随机决定“是否含两步运算”。两步运算的表达式如3 + 4 × 5，在计算答案时必须按运算符优先级处理。可以直接复用系统中现成的数学评估思路，但为了保证可控性，我用了一个最简单可靠的方案：先把表达式拆成操作数和运算符数组，再按“先乘除后加减”的顺序分两次计算。这样写出来的代码量不大，逻辑却非常明确，不会因为表达式求值库的边界问题出bug。
2.2 答题记录与结算数据结构定义
答题过程中的状态字段非常多，稍不注意就会在页面上埋一堆@State变量，管理起来非常痛苦。我的做法是把一次答题会话的核心状态收敛到一个页面级类中，用@Observed加上页面里@State引用的方式来统一驱动。
@Observed class GameSession { currentLevel: number = 1 currentIndex: number = 0 correctCount: number = 0 totalScore: number = 0 combo: number = 0 maxCombo: number = 0 isFinished: boolean = false }为什么要把这些字段捆到一个类里而不是分别用@State？因为它们的更新频率不一样，而且彼此之间有连带关系。比如correctCount改变时通常同时要调整combo和totalScore，如果拆成三个独立状态，逻辑代码里就要在三处做赋值操作，还容易漏掉一处。聚合成一个GameSession之后，可以写一个统一的方法来更新得分相关的字段，调用方只需要传一个“本次是否答对”的布尔值，内部自己处理所有联动逻辑。这样页面的代码会清爽很多，也方便后续做调试日志。
2.3 页面路由框架与参数传递设计
在HarmonyOS应用里做多页面跳转，主要就是两类思路：一类是系统路由框架，另一类是页面内自定义导航。这个项目我选的是前者，因为它能更自然地模拟真实应用中“从列表进入详情再返回”的路径。主页负责展示四个关卡入口和最高分，答题页负责答当前关卡的题目，结算页负责展示本次闯关结果。
路由参数传递有一个很常见的坑：对象作为参数传递时，如果只是序列化某个字段，底层会把对象转成可以序列化的键值。我在设计时干脆把GameSession里的currentLevel、questionCount、timeLimit、operator、range这些关卡配置单独抽出来，以普通键值对形式传给答题页，而不是把一个完整对象扔进路由参数。这样做的好处有两个：一是调试时能直接从路由参数看出这一关的配置，二是避免对象序列化时某些字段类型不被支持的问题。
主页 --(携带关卡配置)--> 答题页 --(结算数据)--> 结算页这套流程跑通之后，后续想扩展“每日挑战”或“自定义竞赛”模式时，只需要调整构造参数的方式，不需要改动页面主体逻辑。我在开发到第三关的时候深切体会到，这个前期设计替我省了很多返工成本。
3. 答题交互与状态同步：这个项目的心脏在这里
页面框架和数据模型定好之后，真正的核心就是答题过程中的交互逻辑与状态同步了。这个项目的难点不在于某一个交互多复杂，而在于大量的状态是同时变化的，还互相依赖。
3.1 从点击到判分：一条完整的交互链路
答题页的交互链路可以拆成五个步骤：显示题目、等待用户点选、判定对错、更新状态、推进到下一题。每道题显示两个信息：一个表达式和四个选项。我用的是两列排列的选项按钮，点击之后按钮自身会立刻改变颜色——答对变绿、答错变红，同时进入一个短暂的“锁定”状态，防止用户在动画间隙连续点击造成状态错乱。
这里分享一个代码层面容易忽略的细节：锁定状态的实现并不需要去修改按钮的禁用属性。我是在判分方法的第一行做了一次isAnswering判断，如果在答题锁定期内就直接返回，然后在状态更新完成后把它复位。这个做法比单独维护每个按钮的禁用状态要可靠得多，因为按钮的禁用属性只控制点击，控制不了定时器回调或其他入口触发的逻辑。
private onOptionClick(selectedValue: number): void { if (this.isAnswering) { return } this.isAnswering = true // 判定答案、更新得分与连击状态 // 短暂延迟后推进到下一题 }锁定逻辑真的非常关键。我在真机上试过快节奏点击，如果不加这个保护，有时候一次点击会触发两次判分，总分直接翻倍。加了isAnswering之后，这个Bug就彻底消失了。
3.2 计分、连击与关卡推进的状态流转
计分规则是这个应用最有“游戏感”的部分。基础规则是答对一题得10分，连击会额外加2分，上限是额外加10分。也就是说，如果你从第一题开始连续答对，第五题开始每题的得分是20分，判断依据是combo * 2，但封顶10分。
private applyResult(correct: boolean): void { if (correct) { this.session.combo++ let bonus = Math.min(this.session.combo - 1, 5) * 2 this.session.totalScore += 10 + bonus this.session.correctCount++ } else { this.session.combo = 0 } this.session.maxCombo = Math.max(this.session.maxCombo, this.session.combo) this.session.currentIndex++ }这段逻辑看起来很短，但它是整个答题页的主心骨。需要注意的是，currentIndex推进要放在最后，因为前面的得分状态全部依赖当前的currentIndex。有一版我图省事，把它放在开头，结果答完第一题之后直接跳到第三题，排查了好一阵子才发现是顺序问题。这种“赋值顺序引发的状态错乱”，在状态多、联动密的场景里非常典型，我后来习惯性地把“会改变判题依据的状态”放在方法末尾。
关卡推进的判断也很直接：当currentIndex >= questionCount时，整个答题会话结束，调用路由跳转到结算页。但跳转前还有个细节，必须先把totalScore和maxCombo以参数形式传给结算页，同时用本地存储更新当前关卡的历史最高分。更新历史最高分的动作我放在了答题页的onPageHide生命周期里，而不是跳转前那一个同步调用里。这样即使系统返回键触发隐藏，也能保证高分被记录下来。
3.3 自定义答题组件与父子通信的搭配
答题页里有一个倒计时组件，它和主页面是典型的父子组件关系。倒计时组件自己维护一个计时器的状态，每秒钟更新一次渲染文本；但当倒计时归零时，主页面需要立刻收到通知并强制收卷。这种需求用自定义事件就能解耦。
@Component export struct CountdownTimer { @Prop totalSeconds: number @Link timeUpEvent: () => void @State secondsLeft: number aboutToAppear() { this.secondsLeft = this.totalSeconds // 启动定时器，每秒减1，到0时触发timeUpEvent } aboutToDisappear() { // 清理定时器，避免离开页面后仍在回调 } }父子通信的另一个场景是选项区域和答题页主状态之间的同步。选项区域接收一个Question对象和当前选中答案，点击后上报给父组件。我在设计时特意让“判分”这个动作只发生在父组件里，子组件只负责表现层的“颜色反馈”。这样做的好处是，以后想改判定规则或增加题目类型时，不需要动子组件的代码。
这里要特别说一句关于@Prop与@Link的取舍：@Prop是单向同步，子组件修改自己的拷贝不会影响父组件，适合“只读展示型”属性，比如倒计时的初始秒数；@Link是双向同步，适合需要父组件也感知变化的场景。在实际开发里，凡是能被自由修改的字段，尽量让修改动作收敛到父组件，通过方法回调去更新，这样可调试性最好。我见过不少初学者把每个状态都传成@Link，最后一旦状态错乱，根本不知道是哪条链路改动了它。这个项目里，连击数和得分的修改入口全部集中在父组件，就是一个很好的实践。
4. 真机调试中我踩过的几个坑：状态残留、路由栈与屏幕适配
光看文档以为都对了，一上真机就原形毕露，这是调应用的老常态。这个项目跑真机时我也踩了几个坑，有些问题不真正跑到真机上根本不会暴露。
4.1 状态更新不及时：一个隐蔽的赋值顺序问题
我最早遇到的一个Bug是：连续答对五题后，单题得分从10分变成了12分，而不是预期的14分。排查的时候发现combo计算是对的，得分加的却是旧的加成值。原因很隐蔽，我在applyResult方法里先更新了totalScore，然后才执行combo++，于是计算加成时读到的还是上一个题目的连击数。
修复方式就是把combo++放到计算得分之前。这个教训虽然很小，但让我重新审视了一遍整个状态更新方法：状态字段的更新顺序必须和业务语义一致。为了以后不再被这类问题折磨，我尽量把“先更新判断依据，再计算结果”这个原则固定成一种编码习惯。如果你在开发自己的项目时也遇到“数值总是慢一拍”的奇怪现象，十有八九就是更新顺序的锅。
4.2 从答题页返回首页后数据没有恢复
还有一个更隐蔽的坑：从答题页返回到首页时，首页上显示的“最高分”还是旧值。按理说本地存储已经更新了，首页读取到了新值才对。后来我发现问题出在首页的读取时机上：首页的aboutToAppear只在页面首次创建时执行了一次，之后从答题页返回时走的是路由页面的onPageShow，并没有触发aboutToAppear。
解决方案很简单，把读取最高分并刷新显示的逻辑放到onPageShow生命周期里。这类事情让我明白一个道理：鸿蒙应用的生命周期回调不能只靠记忆硬背，要多翻看真机运行时的调用日志。尤其涉及多页面跳转的场景，aboutToDisappear、onPageHide、onPageShow之间的关系很容易搞混。最好的定位方法是在每个生命周期回调里打一条日志，跑一遍完整流程，看看到底是哪个回调先执行、哪个后执行，远比对着文档猜要可靠得多。
4.3 折叠屏与平板上的布局适配收尾
这个项目一开始我是按手机屏幕尺寸做的，卡片的宽度、按钮的间距都用固定数值。拿到平板上跑了一下，页面倒是没崩，但整体布局明显偏左，右侧空了一大块，视觉上非常难受。于是我改用格子布局作为整体骨架，让关卡卡片和选项按钮按列数自动撑满。
我给的参考方案是：首页的关卡入口使用两列栅格，答题页的选项按钮使用四列栅格，页面主体外距使用56号资源作为规范间距。对于倒计时这种容易受字体大小影响的文本，额外设置了maxFontScale限制，避免用户开了超大字体之后倒计时数字挤到卡片外面。这套适配逻辑做下来，同一套代码在手机和平板上显示效果都基本一致，也省了单独做平板版本的精力。
5. 从跑通到像样：打磨体验值不值得做，一线项目告诉你
很多练手项目跑到“功能都正常”就停了，这个算术闯关如果走到这一步也不算白做。但如果你想让它看起来像一个完整的产品，而不是一个课后作业，下面这些打磨点值得考虑。
5.1 用系统自带能力做出够用的视觉反馈
我没有去接任何复杂的动效库，而是充分利用了组件自身的状态切换和系统能力。答对时选项按钮变绿并轻微放大，答错时变红并轻微抖动；倒计时最后五秒，数字从黑色变成红色；每次得分变化，总分数字做一次简短的透明度过渡。这些效果在代码层面上就是几个状态值和样式切换的组合，但反馈感比干巴巴的文字提示好上不少。
音效我用了系统提供的简单提示音接口，答对和答错各对应一个音效，结算页结束时再播放一个更短的收尾音。嵌入的过程只需要几十行代码，实测下来，对整体体验的提升非常明显。我最满意的其实是“锁定答题”的那一刹那加了一个极短的震感反馈，一种“手机轻轻震动了一下表示选中成功”的感觉，很多试玩的人都说这个细节很有沉浸感。
5.2 关卡扩展与排行榜的设计空间
如果想把“算术大闯关”继续做深，有两个方向我觉得很自然。第一是增加关卡类型，比如“看时钟答题”“单位换算闯关”，每类关卡本质只需要换一套题目生成器，接入operator和range之外的题型标识字段即可。第二是加一个本地排行榜，用本地数据库或者持久化存储保存最近十次闯关记录，显示关卡、得分、连击和用时。这样“总复习”里关于本地存储的知识点就能得到再一次加固。
我在做这个项目时还留了一个扩展点：把正确答案的解析步骤也存进答题记录里，结算页不仅显示总分，还显示每一道题的对错和正确答案。这个功能在真机上跑起来之后，小朋友用它来做口算练习，错题复盘非常方便。这个设计思路本身很简单，但对一个练习类应用来说，价值远大于好看的界面。
5.3 给新手的收尾建议：这个实例的三种练法
根据我自己带人和自学的经验，同样的“算术大闯关”可以有三种练法。第一种是照着我上面讲的思路完整复刻一遍，重点体会数据模型先行、交互链路收口的做法。第二种是在跑通之后刻意回退一段代码，比如去掉“答题锁定”，看看快速连点会出什么Bug，再自己修复。这种“故意弄坏再修好”的练习方式，对理解状态同步问题的帮助非常大。第三种是不要只管一个答题页，把三个页面之间的数据流画成一张图，标注每个字段从产生到消费的完整路径，你会发现有些字段传递是多余的，可以做真正的简化。
我个人在实际开发中的体会是，练手项目的最大价值不在于界面多好看，而在于能不能让你把“单点知识点”织成“网络”。如果你现在学完一路排着学知识点还是觉得虚，真心建议找一个这样的小游戏项目，把一个会话流程完整跑通，把状态同步想明白。等你把这一套流程走完，再回头看前面那些单点实例，会有一种“原来它们都是这个项目的零件”的顿悟感。
