HarmonyOS 数独小游戏案例解析:54题库生成、冲突校验与文件持久化实战
数独是一款经典的逻辑推理游戏,规则简单却变化无穷。最近在鸿蒙实践案例中心看到一个名为「HarmonyOS 数独小游戏」的开源案例(HarmonyOS-APP-sudoku),它用纯端侧 ArkTS 实现了一个"点开就能玩"的数独 App:内置 54 道分级题库、填错即时标红、通关自动记录进度,全程不联网、不登录。本文结合其源码,从题库生成、冲突校验、本地持久化三个核心问题入手,拆解它是如何把一个"小游戏"做得工程完备的。
一、项目架构:四层职责清晰
整个应用代码量不大,但分层非常干净,关键目录 harmony_app/entry/src/main/ets/ 下分为四层:
- 页面层(pages/):Index 首页负责展示进度卡片(已通关数/总题数,按难度分项)与"随机一题""按难度选择"入口;GamePage 游戏页渲染 9×9 棋盘、数字面板与通关弹窗;PuzzleListPage 提供按难度选题列表。
- 组件层(components/):SudokuBoard(9×9 棋盘)、NumberPad(数字选择面板)、CelebrationDialog(通关庆祝卡片)三个可复用组件。
- 逻辑层(sudoku/):SudokuTypes 定义类型与枚举,SudokuLogic 负责冲突校验与解题判定,SudokuPuzzleLibrary 负责题库生成(54 题),SudokuStore 负责文件持久化。
- 数据层:直接使用 @ohos.file.fs 操作应用沙箱文件,而非轻量级首选项。
首页展示进度与入口,游戏页加载题库并渲染棋盘;用户填数后逻辑层计算冲突掩码并回传给棋盘组件;通关时存储层将进度写入沙箱文件,首页返回时重新读取刷新。数据单向流动,状态可追踪。
二、题库生成:54 道题从哪里来
离线应用没法从服务器拉题,题库必须内置。这个案例的做法很典型:以若干基准终盘解为种子,通过确定性变换(行列置换、数字映射、区域交换等)批量派生新题目,再按比例"盲挖"空格得到不同难度的初盘。54 道题按入门/进阶等难度分级,覆盖了从少量挖空到大量挖空的梯度。
这种生成方式有两个值得注意的设计取舍:
- 保证有解:因为题目是从合法解挖空得到的,每题必有解,玩家不会遇到"无解题"。
- 不保证唯一解:案例文档明确说明,题目未做唯一性校验,同一题可能存在多套合法终盘。相应的通关判定也不与内置 solution 比对,而是校验"填满且无行列宫冲突"——任意一套合法终盘均可通关。这是把"数独 purist"的严谨性让位给玩家体验的务实选择,也避免了唯一解求解器带来的性能开销。
题库生成器用 mulberry32 这类确定性伪随机数配合置换与盲挖,使同样的种子在任何设备上生成完全相同的题库,便于测试复现与版本对比。
三、实时冲突校验:状态驱动的 UI
冲突校验是数独交互的核心。案例中 SudokuLogic 提供纯函数式的校验逻辑:对当前棋盘逐格检查其所在行、列、3×3 宫内是否有重复数字,输出冲突掩码;棋盘组件根据掩码将冲突格红色高亮,预填数字不可修改。
这体现了 ArkUI 声明式 UI 的典型思路:UI 是状态的函数。用户每填一个数字,状态变化触发校验纯函数重算,掩码回传后棋盘重新渲染——不需要手写"把某个格子变红"的命令式操作。校验本身是 O(81×27) 级别的朴素实现,对 9×9 棋盘完全够用,没有必要上位运算优化。
四、文件持久化:为什么不用 dataPreferences
进度持久化是这个案例最值得细看的工程点。通关记录存为应用沙箱 filesDir 目录下的 sudoku_progress.json,通过 @ohos.file.fs 直接读写。
为什么不直接用系统提供的 dataPreferences(轻量级键值存储)?案例说明是为了规避一个真实踩过的坑:跨页面读取旧值。preferences 的内存缓存与磁盘落盘之间存在时序差,游戏页写入后立即返回首页,首页读到的可能是未刷新的缓存值,导致"明明通关了进度却没 +1"。改为每次直接读文件,以磁盘为准,从根上消除缓存不一致。
同时,存储层设计了 reset() 接口,首页底部内置"重置进度"入口(带二次确认弹窗),内部将进度重置为 { solvedIds: [] }。卸载应用即自动清除全部进度,符合沙箱应用的隐私预期。
五、验收与迁移价值
案例的验收标准写得相当规范,五个成功标志:应用可编译安装启动、随机一题进入棋盘正常渲染、冲突格实时红色高亮、正确填满弹出庆祝卡片且首页进度 +1、重启应用进度保留。最后一条专门针对持久化,用"重启后数据仍在"来验证,而不是只看界面。
对想练手的开发者而言,这个案例的迁移价值在于"棋盘渲染 + 实时校验 + 本地存档"这一套组合拳:照搬到扫雷、华容道、记忆翻牌、2048 等游戏都成立。文档也给出了扩展练习方向:增加笔记模式(每格标记候选数字)、计时与历史最佳成绩,以及接入云题库同步与在线排行榜的生产化方向。
结语
这是一个典型的"小而完整"的鸿蒙入门案例:功能不复杂,但架构分层、状态管理、持久化一致性、验收标准一个不缺。它验证的环境是 DevEco Studio 最新稳定版、compatibleSdk 6.1.0(23)、HarmonyOS 模拟器。如果你正在寻找第一个鸿蒙实战项目,或者想系统练习 ArkUI 声明式开发与端侧数据持久化,值得跟着 README 的"最短运行"三步走一遍——10 分钟就能在自己设备上看到数独棋盘跑起来。
案例地址:gitcode.com/harmony-practice-center/Harmony-APP-sudoku(MIT 协议),配套文档 quickstart.md 与 fullpractice.md 提供快速体验与完整实践两条路线。
- 点赞
- 收藏
- 关注作者
评论(0)