HarmonyOS-APP-sudoku:使用华为云码道(CodeArts)鸿蒙开发智能体,从一句自然语言需求出发,创作一款内置 54 道分级题库、支持实时行列宫冲突校验与通关进度本地持久化的 HarmonyOS 数独小游戏App。

使用华为云码道(CodeArts)鸿蒙开发智能体,从一句自然语言需求出发,创作一款内置 54 道分级题库、支持实时行列宫冲突校验与通关进度本地持久化的 HarmonyOS 数独小游戏App。

分支1Tags0
文件最后提交记录最后更新时间
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. 进入首页 → 看到进度卡片(已通关数 / 总题数,按难度分项)与“随机一题”“按难度选择”入口
  2. 选择难度或随机出题 → 进入棋盘页,点击空格弹出 1~9 数字面板,填入后实时校验行列宫冲突并红色高亮冲突格
  3. 填满无冲突 → 弹出庆祝反馈卡片,返回首页后进度计数自动更新
首页 数独游戏页
首页 数独游戏页

完成本案例后,你已经:掌握 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。第三方依赖及素材遵循各自许可证。

项目介绍

使用华为云码道(CodeArts)鸿蒙开发智能体,从一句自然语言需求出发,创作一款内置 54 道分级题库、支持实时行列宫冲突校验与通关进度本地持久化的 HarmonyOS 数独小游戏App。

定制我的领域