从数独小游戏看 HarmonyOS 纯端侧开发：声明式 UI、确定性题库与本地持久化

今天在鸿蒙开发实践中心浏览了数独小游戏案例：一个 HarmonyOS + ArkUI 纯端侧应用，首页有进度卡片与出题入口，进入后是 9×9 棋盘，填数时实时校验行列宫冲突并红色高亮，通关后进度本地存档、重启仍保留。这篇笔记把它的三个关键设计拆开讲清楚，便于入门开发者复现。

一、声明式 UI：页面与状态分离

案例有首页、游戏页、选题列表三个页面。棋盘渲染、数字面板与游戏逻辑分开，状态变化驱动界面刷新，而不是在界面代码里到处写校验。复现时先画出三个页面的跳转关系，再写棋盘组件：空格、预填数字、冲突高亮三种状态要一眼区分，预填数字不可修改。

二、确定性题库：54 题是怎么来的

案例用基准解加置换再盲挖空格的方式生成题目，简单、中等、困难各 18 题，相同种子产生相同题目，因此结果可复现、可回归验证。值得注意的是，通关判定只校验填满且无冲突，并不与某一固定答案逐格比对，所以题库不保证唯一解，这不是缺陷，而是判定口径不同。做练习时要先把判定口径写进验收标准，避免把多解误当成 bug。

三、本地持久化：为什么不用缓存单例

案例早期曾遇到通关后进度计数不更新的问题，原因是 dataPreferences 单例缓存导致跨页面读到旧值。修复方法是改用 @ohos.file.fs 直读进度文件，每次加载都取磁盘最新值，首页返回时重新加载。复现 checklist：通关后返回首页进度加一；重启应用后进度仍在；重置后进度归零。

四、给入门者的复现顺序

1. 先跑通：克隆案例公仓，在 DevEco Studio 中打开并运行，看到首页进度卡片与随机一题入口。
2. 再读逻辑：按冲突校验、解题判定、题库生成、文件持久化的顺序读源码，记下每个函数的入口。
3. 再做验证：用固定输入验证冲突校验与解题判定，用相同种子验证题库可复现，最后做通关、重启、重置三组验收。

纯端侧方案的好处是离线可运行、不依赖云服务，适合练 ArkTS 声明式开发与本地数据管理。把它做成可复现的练习，比只看一遍案例介绍更有价值。