使用华为云码道(CodeArts)鸿蒙开发智能体,从一句自然语言需求出发,创作一款内置 54 道分级题库、支持实时行列宫冲突校验与通关进度本地持久化的 HarmonyOS 数独小游戏App。
| 文件 | 最后提交记录 | 最后更新时间 |
|---|---|---|
| 1 个月前 | ||
| 2 个月前 | ||
| 7 天前 | ||
| 3 个月前 | ||
| 3 个月前 | ||
| 2 个月前 |
HarmonyOS 数独小游戏
一个“点开就能玩”的鸿蒙数独游戏:数字填错即时标红,通关后自动记住进度。全程本地运行、不联网、不登录——跟着本案例,你也能从零写出自己的第一个鸿蒙 App。

| 项目 | 内容 |
|---|---|
| 适合谁 | 有 ArkTS/ArkUI 基础、想练习声明式 UI 与端侧数据持久化的开发者 |
| 难度与耗时 | 入门 · 预计 0.5–1 小时 |
| 你将学到 | ArkUI 声明式 UI、@Builder 组件、本地文件持久化 |
| 你将完成 | 一个可编译安装、可通关记录进度的 HarmonyOS 数独应用 |
| 最近验证环境 | DevEco Studio(官网最新稳定版)· compatibleSdk 6.1.0(23) · 最后验证于 2026-08-19 |
选择你的阅读路线:想先看到结果 → 最短运行 · 想完整学习 → 完整实践 · 遇到问题 → 见 docs/quickstart.md 与 docs/fullpractice.md 的「验收与排障」章节
1. 价值
数独是经典的逻辑推理游戏。本案例在 HarmonyOS 端侧实现一个完整的数独体验,重点解决三个问题:如何用声明式 UI 渲染 9×9 棋盘并实时高亮冲突、如何在不联网的情况下生成并提供 50+ 道分难度的题库、如何用本地文件可靠记录通关进度。这些能力可迁移到任何离线优先的卡片式应用。
项目亮点
- 做出的是“真东西”:不是演示 Demo,而是带 50+ 题库、实时冲突校验、通关进度存档的完整小游戏。
- 门槛低、收获实:不需要后端和数据库,纯 TypeScript 逻辑 + 声明式 UI,0.5–1 小时就能从零跑通。
- 套路能复用:棋盘渲染 + 实时校验 + 本地存档的组合,照搬到扫雷、华容道、记忆翻牌都成立。
核心功能与体验
- 进入首页 → 看到进度卡片(已通关数 / 总题数,按难度分项)与“随机一题”“按难度选择”入口
- 选择难度或随机出题 → 进入棋盘页,点击空格弹出 1~9 数字面板,填入后实时校验行列宫冲突并红色高亮冲突格
- 填满无冲突 → 弹出庆祝反馈卡片,返回首页后进度计数自动更新
| 首页 | 数独游戏页 |
|---|---|
![]() |
![]() |
完成本案例后,你已经:掌握 ArkUI 声明式组件与 @Builder/@Prop 状态管理;实现数独题库生成与行列宫冲突实时校验;用文件系统解决跨页面进度持久化的缓存一致性问题;交付一个可编译运行的纯端侧 HarmonyOS 数独应用。
2. 环境
环境与资源
| 项目 | 要求 | 检查或获取方式 |
|---|---|---|
| 基础知识 | ArkTS、ArkUI 声明式语法 | ArkTS / ArkUI 开发入门 |
| 开发环境 | Windows/macOS、DevEco Studio(官网最新稳定版)及配套 HarmonyOS SDK | DevEco Studio 下载 |
| 测试设备 | HarmonyOS 模拟器或真机 | hdc list targets 应返回设备 |
SDK 版本说明:
build-profile.json5中compatibleSdkVersion为 6.1.0(23)(应用最低可运行的 API 级别),compileSdkVersion与targetSdkVersion为 6.1.1(24)(编译与目标 API 级别)。这些是构建兼容信息,不是“所有读者必须安装的唯一版本”:优先使用 DevEco Studio 官网最新稳定版,本地 SDK 至少包含 6.1.1(24) 即可编译。
3. 最短运行
想在 10 分钟内看到应用启动,按下面三步走。完整步骤与排障见 docs/quickstart.md。
1)获取最新代码
git clone https://gitcode.com/harmony-practice-center/Harmony-APP-sudoku.git
cd Harmony-APP-sudoku
cd harmony_app
克隆的是仓库默认分支(main)的最新内容,无需切换到某个固定提交或 Git 标签。
2)构建并运行
优先在 DevEco Studio 中打开 harmony_app 目录并点击 Run(自动完成签名、安装与启动)。命令行需先签名,再用 hdc install 与 hdc shell aa start 完成安装启动,完整命令见 docs/quickstart.md 第 2 节。
3)看到结果
设备出现“数独”应用图标,首页显示进度卡片与“随机一题”“按难度选择”入口;点“随机一题”进入 9×9 棋盘即可开始游戏。
4. 成功标志
- 应用可编译、安装并启动,首页无白屏。
- 点“随机一题”能进入棋盘页,9×9 棋盘渲染正常、预填数字不可修改。
- 填入与同行/同列/同宫重复的数字时,冲突格实时红色高亮。
- 正确填满整盘后弹出庆祝卡片,返回首页对应难度进度 +1。
- 重启应用后,已通关进度仍然保留。
以上是“跑通”的判据;逐条对照的验收步骤见 docs/quickstart.md「业务验收」。
5. 核心原理
技术方案一览
flowchart LR
A["ArkUI 页面<br/>Index / GamePage"] --> B["数独逻辑层<br/>SudokuLogic / Library"]
B --> C["本地存储层<br/>SudokuStore"]
C --> D["文件系统<br/>@ohos.file.fs"]
首页展示进度与入口,游戏页加载题库并渲染棋盘;用户填数后逻辑层计算冲突掩码并回传给棋盘组件;通关时存储层将进度写入应用沙箱文件,首页返回时重新读取刷新。
| 层级 | 技术/产品 | 验证版本 | 作用 |
|---|---|---|---|
| 端侧 | ArkTS / ArkUI | compatibleSdk 6.1.0(23) | 声明式 UI、组件化、状态管理 |
| 逻辑 | TypeScript 纯函数 | — | 题库生成、冲突校验、解题判定 |
| 数据 | @ohos.file.fs |
— | 进度 JSON 文件直读(本案例选择,规避跨页面读旧值) |
| 工具 | DevEco Studio / hvigor | DevEco Studio | 构建、签名、安装 |
关键目录
.
├── README.md # 案例入口与项目介绍
├── docs/
│ ├── quickstart.md # 快速体验与验收排障
│ ├── fullpractice.md # 完整实践与验收排障
│ └── image/ # 案例截图
├── LICENSE # 开源许可证(MIT)
└── harmony_app/
├── AppScope/ # 应用级配置与资源
├── build-profile.json5 # 构建配置
└── entry/
└── src/
├── main/
│ ├── ets/
│ │ ├── sudoku/ # 数独核心逻辑
│ │ │ ├── SudokuTypes.ets # 类型与枚举
│ │ │ ├── SudokuLogic.ets # 冲突校验与解题判定
│ │ │ ├── SudokuPuzzleLibrary.ets # 题库生成器(54 题)
│ │ │ └── SudokuStore.ets # 文件持久化
│ │ ├── components/ # 可复用 UI 组件
│ │ │ ├── SudokuBoard.ets # 9×9 棋盘
│ │ │ ├── NumberPad.ets # 数字选择面板
│ │ │ └── CelebrationDialog.ets # 通关庆祝卡片
│ │ ├── pages/ # 页面
│ │ │ ├── Index.ets # 首页(进度+入口)
│ │ │ ├── GamePage.ets # 游戏页(棋盘+面板+弹窗)
│ │ │ └── PuzzleListPage.ets # 按难度选题列表页
│ │ ├── entryability/EntryAbility.ets # 生命周期入口
│ │ └── entrybackupability/EntryBackupAbility.ets # 备份恢复扩展能力
│ ├── resources/ # 颜色、字号、字符串资源
│ └── module.json5 # 模块配置
├── test/ # 本地单元测试(LocalUnit.test.ets / List.test.ets)
└── ohosTest/ # 设备侧测试(ets/test/ 下 Ability.test.ets / List.test.ets)
深入阅读与扩展
- 扩展练习:增加笔记模式(每格可标记候选数字)
- 扩展练习:增加计时与历史最佳成绩
- 生产化方向:接入云题库同步与在线排行榜
6. 验收
人工验收
| # | 操作 | 预期结果 |
|---|---|---|
| 1 | 首页点“随机一题” | 进入棋盘页,9×9 渲染、预填不可点击 |
| 2 | 填入与同行重复的数字 | 冲突格红色高亮 |
| 3 | 正确填满整盘 | 弹出庆祝卡片 |
| 4 | 返回首页 | 对应难度进度 +1 |
| 5 | 重启应用 | 已通关进度保留 |
完整验收表(含证据/检查方式)见 docs/quickstart.md「业务验收」。
关键算法固定样例
冲突校验、解题判定与题库不变量均可复现,固定输入输出样例见 docs/quickstart.md「关键算法固定样例」。
| 项目 | 内容 |
|---|---|
| 验证日期 | 2026-08-19 |
| 代码来源 | 仓库默认分支 main 的最新内容 |
| 设备与系统 | HarmonyOS 模拟器 / compatibleSdk 6.1.0(23) |
| 结论 | 业务验收 5/5 通过(人工);核心算法以固定输入输出样例复核 |
说明:截图只能证明界面状态,不能替代算法、持久化与生命周期验证;后两者分别由固定样例与人工步骤(重启后进度保留)验证。
7. 边界与维护
边界说明
- 本案例为纯端侧离线应用,不依赖任何云服务、账号或网络权限。
- 题库由内置基准解经确定性变换生成,保证每题有解;但不保证唯一解:题目由合法解盲挖空格得到,未做唯一性校验,同一题可能存在多套合法终盘。通关判定仅校验“填满且无行列宫冲突”,不与内置
solution比对,因此任意一套合法终盘均可通关。不包含在线题库同步或排行榜。
数据存储与清理
- 通关进度仅存于应用沙箱内的
sudoku_progress.json(filesDir目录),只允许本应用读写,不涉及网络与云端,卸载应用即自动清除全部进度。 - 想在保留应用的同时重置进度:首页底部已内置「重置进度」入口(点击后弹出二次确认,确认即清空全部通关记录),其内部调用
SudokuStore.reset()(将进度重置为{ solvedIds: [] })。
官方资料与帮助
维护与版本
| 项目 | 内容 |
|---|---|
| 维护团队 | 鸿蒙实践案例开发团队 |
| 当前案例版本 | v1.0.0 |
| 最后验证日期 | 2026-08-19 |
| 兼容范围 | compatibleSdk 6.1.0(23);compileSdk/targetSdk 6.1.1(24) |
- v1.0.0(2026-08-19):首个版本,含 54 题题库、冲突校验、文件持久化、通关庆祝。
v1.0.0是案例内容的迭代记录,不是 Git 标签;读者直接克隆默认分支main的最新内容即可,无需切换到某个固定提交。
许可证
本案例采用 MIT。第三方依赖及素材遵循各自许可证。

