ArkTS + ArkUI 实战:用 HarmonyOS 写一个纯端侧数独小游戏
为什么要在端侧做一局数独
数独是个特别适合练手的题材:规则清楚、没有网络依赖、但又能把声明式 UI 渲染、纯函数逻辑设计、确定性随机和本地文件持久化四件事一次串起来。本文用一个在 HarmonyOS 上实际跑通的纯端侧数独为例,按「数据模型 → 棋盘渲染 → 冲突校验 → 题库生成 → 进度存档 → 编译打包」的顺序,把关键设计讲清楚,代码可直接参考。
整个应用只有三个页面:首页显示通关进度和出题入口,游戏页渲染 9×9 棋盘并处理填数,选题列表按难度列出 54 道题。全程离线、不登录、不联网,是理解 ArkTS 工程结构的典型小项目。
一、先把工程结构摆正
ArkTS 工程按「页面 pages / 组件 components / 领域逻辑 sudoku」分层,逻辑层完全不依赖 UI,这样后面写单元测试、复用到别的小游戏都很方便。
harmony_app/
├── entry/src/main/ets/
│ ├── pages/
│ │ ├── Index.ets // 首页:进度卡片 + 出题入口
│ │ ├── GamePage.ets // 游戏页:棋盘 + 数字面板
│ │ └── PuzzleList.ets // 选题列表:简单/中等/困难
│ ├── components/
│ │ ├── SudokuBoard.ets // 9×9 棋盘渲染
│ │ └── NumberPad.ets // 1-9 数字输入面板
│ ├── sudoku/
│ │ ├── SudokuTypes.ets // 类型与枚举
│ │ ├── SudokuLogic.ets // computeConflicts / isSolved
│ │ ├── SudokuPuzzleLibrary.ets // 54 题确定性生成
│ │ └── SudokuStore.ets // 进度文件持久化
│ └── entryability/EntryAbility.ets
└── oh-package.json5
数据模型先定清楚,后面所有代码都围绕它转。棋盘用长度 81 的一维数组而不是二维数组,原因是一维下标在 Grid 的 ForEach 里更直接,算行列宫也只需一次除法取整。
// SudokuTypes.ets —— 数据模型先定清楚,后面所有逻辑都围绕它
export interface CellData {
value: number; // 0 表示空格
given: boolean; // 题目预填,不可修改
conflict: boolean; // 是否与同行/列/宫冲突
}
export interface Puzzle {
id: number;
level: 'easy' | 'medium' | 'hard';
cells: number[]; // 长度 81 的一维数组,0 为空
}
export interface ProgressData {
solvedIds: number[]; // 已通关的题目 id
}
二、声明式渲染:只描述数据长什么样
ArkUI 的核心是「状态变了,界面自己更新」。棋盘不需要手动操作任何节点,只要把 CellData[] 喂给 Grid,冲突格和预填格的颜色由数据字段决定。
// SudokuBoard.ets —— 声明式渲染:只描述「数据长什么样」
@Component
export struct SudokuBoard {
@Prop board: CellData[]; // 81 个格子
onCellTap: (index: number) => void = () => {};
build() {
Grid() {
ForEach(this.board, (cell: CellData, index: number) => {
GridItem() {
Text(cell.value === 0 ? '' : cell.value.toString())
.fontSize(22)
.fontWeight(cell.given ? FontWeight.Bold : FontWeight.Normal)
.fontColor(cell.conflict ? '#E84026' : '#1A1A1A')
.width('100%')
.height('100%')
.textAlign(TextAlign.Center)
}
.backgroundColor(this.bgColor(index, cell))
.borderWidth(this.borderWidth(index))
.borderColor('#C9CDD4')
.onClick(() => this.onCellTap(index))
}, (cell: CellData, index: number) => index.toString())
}
.columnsTemplate('1fr 1fr 1fr 1fr 1fr 1fr 1fr 1fr 1fr')
.rowsTemplate('1fr 1fr 1fr 1fr 1fr 1fr 1fr 1fr 1fr')
.width('100%')
.aspectRatio(1)
}
// 3×3 宫之间加粗边框,其余细线
private borderWidth(index: number): EdgeWidths {
const r = Math.floor(index / 9);
const c = index % 9;
return {
top: r % 3 === 0 ? 2 : 0.5,
bottom: (r + 1) % 3 === 0 ? 2 : 0.5,
left: c % 3 === 0 ? 2 : 0.5,
right: (c + 1) % 3 === 0 ? 2 : 0.5
};
}
private bgColor(index: number, cell: CellData): ResourceColor {
if (cell.conflict) return '#FDECEA';
if (cell.given) return '#F2F3F5';
return Color.White;
}
}
几个细节值得注意:Grid 用 columnsTemplate / rowsTemplate 各切 9 等份,配合 aspectRatio(1) 保证棋盘是正方形;3×3 宫的粗边框通过 borderWidth 按行列下标取模判断,不用额外嵌套容器;ForEach 的第三个参数是 key 生成函数,用下标做 key 能让复用更稳定——数独格子数量固定,不会因为增删导致整盘重绘。
还有一个容易忽略的点:@Prop 是单向同步,父组件改 board 时子组件会刷新;但子组件内部不要直接改 @Prop,所有变更都通过回调 onCellTap 交回父页面处理,数据流保持单向,排查问题会轻松很多。
三、冲突校验写成纯函数
最容易写坏的地方,是把「判断这一格能不能填」直接写在点击事件里,夹杂 UI 判断。正确做法是抽一个纯函数:输入 81 个数字,输出 81 个布尔值,表示每格是否冲突。
// SudokuLogic.ets —— 纯函数:输入棋盘,输出冲突掩码,不碰任何 UI
export function computeConflicts(values: number[]): boolean[] {
const conflict = new Array<boolean>(81).fill(false);
// 收集每个数字在行/列/宫中出现的次数
const markGroup = (indices: number[]) => {
const pos = new Map<number, number[]>();
for (const i of indices) {
const v = values[i];
if (v === 0) continue;
if (!pos.has(v)) pos.set(v, []);
pos.get(v)!.push(i);
}
pos.forEach((list: number[]) => {
if (list.length > 1) list.forEach(i => conflict[i] = true);
});
};
for (let r = 0; r < 9; r++) {
markGroup(Array.from({ length: 9 }, (_, c) => r * 9 + c)); // 行
markGroup(Array.from({ length: 9 }, (_, r2) => r2 * 9 + r)); // 列
}
for (let br = 0; br < 3; br++) {
for (let bc = 0; bc < 3; bc++) {
const cells: number[] = [];
for (let r = 0; r < 3; r++) {
for (let c = 0; c < 3; c++) {
cells.push((br * 3 + r) * 9 + (bc * 3 + c)); // 3×3 宫
}
}
markGroup(cells);
}
}
return conflict;
}
export function isSolved(values: number[]): boolean {
if (values.some(v => v === 0)) return false;
return !computeConflicts(values).some(Boolean);
}
思路很简单:行、列、3×3 宫三类分组,各自统计 1-9 每个数字出现的位置,出现两次以上就把这些位置全部标为冲突。返回的是掩码而不是「第一个冲突」,这样界面上所有冲突格能同时红色高亮,体验一致。
isSolved 则复用同一套逻辑:先判有没有空格,再判有没有冲突。纯函数的好处是可测试——给定一个固定棋盘,输出必然固定,写几条断言就能锁住行为,比在模拟器里手点可靠得多。
四、确定性题库:随机但可复现
54 道题不可能手写,但如果用 Math.random() 每次生成都不一样,用户退出再进就换了题,体验很差。解决办法是用确定性 PRNG:给定同一个种子,永远产生同一串随机数。
// SudokuPuzzleLibrary.ets —— 确定性 PRNG:同一 seed 永远生成同一套题
function mulberry32(seed: number): () => number {
return function (): number {
seed |= 0;
seed = (seed + 0x6D2B79F5) | 0;
let t = Math.imul(seed ^ (seed >>> 15), 1 | seed);
t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
};
}
// 基准解:一个合法的完整终盘(此处省略 81 个数字,仓库里直接写死)
// 生成流程:随机置换行、列、数字 -> 盲挖空格 -> 得到题目
export function buildPuzzle(seed: number, blanks: number): number[] {
const rand = mulberry32(seed);
const grid = BASE_SOLUTION.slice(); // 复制基准终盘
shuffle(grid, rand); // 行/列/数字置换,保持合法性
let removed = 0;
const result = grid.slice();
while (removed < blanks) {
const idx = Math.floor(rand() * 81);
if (result[idx] !== 0) {
result[idx] = 0;
removed++;
}
}
return result;
}
mulberry32 是常见的 32 位种子伪随机算法,实现短、分布够用。生成流程是「基准终盘 → 行/列/数字置换 → 盲挖空格」:置换不会破坏数独合法性,盲挖按难度控制空格数量(简单约 40 空、中等约 48、困难约 54)。这里刻意不做唯一解校验——唯一解校验开销大,而对练习类小游戏来说「有解即可」完全够用,这一点要在文档里写清楚,避免使用者误解。
题目 id 与种子绑定,进度只存 id 列表,重启后按 id 重新生成题目,得到的就是一模一样的盘面。这就是「确定性」带来的直接收益:不用把整盘题目存进文件,存档体积几乎为零。
五、进度持久化:直读文件,别踩缓存坑
进度只需要存一个已通关 id 数组,用 JSON 文件最省事。这里有个实际踩过的坑:dataPreferences 是单例 + 内存缓存,跨页面读取时可能拿到旧值,导致「刚通关、返回首页进度没变」。改用 @ohos.file.fs 直接读写文件,每次读都从磁盘取最新内容,行为可预期。
// SudokuStore.ets —— 用 @ohos.file.fs 直读文件,规避 dataPreferences 缓存
import fs from '@ohos.file.fs';
import util from '@ohos.util';
export class SudokuStore {
private static path(ctx: Context): string {
return ctx.filesDir + '/sudoku_progress.json';
}
static load(ctx: Context): ProgressData {
const p = SudokuStore.path(ctx);
try {
if (!fs.accessSync(p)) return { solvedIds: [] };
const file = fs.openSync(p, fs.OpenMode.READ_ONLY);
const stat = fs.statSync(p);
const buf = new ArrayBuffer(stat.size);
fs.readSync(file.fd, buf);
fs.closeSync(file);
const text = util.TextDecoder.create('utf-8')
.decodeToString(new Uint8Array(buf));
return JSON.parse(text) as ProgressData;
} catch (e) {
return { solvedIds: [] };
}
}
static save(ctx: Context, data: ProgressData): void {
const p = SudokuStore.path(ctx);
const file = fs.openSync(p,
fs.OpenMode.READ_WRITE | fs.OpenMode.CREATE | fs.OpenMode.TRUNC);
fs.writeSync(file.fd, JSON.stringify(data));
fs.closeSync(file);
}
static reset(ctx: Context): void {
SudokuStore.save(ctx, { solvedIds: [] });
}
}
写入时用 READ_WRITE | CREATE | TRUNC 组合,TRUNC 很关键——不加它,新内容比旧内容短时,文件尾部会残留旧数据,JSON 解析直接报错。这是文件写入最常见的问题之一。读取时先 accessSync 判断存在,再用 statSync 拿大小分配缓冲区,最后交给 TextDecoder 按 UTF-8 解码,避免中文乱码。
六、命令行编译打包与常见错误
在鸿蒙实践中心的云端环境里,构建不需要打开 IDE,直接用 ohpm 和 hvigorw 两条命令即可。
# 1) 安装依赖(在 harmony_app 目录)
ohpm install
# 2) 命令行编译打包 HAP(debug 模式)
hvigorw assembleHap --mode module \
-p module=entry -p product=default \
-p buildMode=debug --no-daemon
# 3) 产物位置
# entry/build/default/outputs/default/entry-default-unsigned.hap
实际执行时遇到过两个典型报错,值得记录:
- compileSdkVersion 与 DevEco Studio 版本不兼容:案例工程写的是旧版本号(如 6.1.1(24)),而环境自带的是更新版本,hvigor 会直接拒绝构建。提示里其实给了答案——删掉 compileSdkVersion 字段,让编译器用内置 SDK,或改成与环境一致的值。
- api version parameter is illegal:把版本写成带括号的形式(26.0.0(26))会解析失败,新版 hvigor 期望纯数字(如 26),改成纯数字即可。
另一个实用习惯:构建前先 ohpm install,确保 oh_modules 就绪;构建失败时优先看 .hvigor/outputs/build-logs 下的日志,比终端里滚动的摘要更完整。产物默认在 entry/build/default/outputs/default/ 下,debug 包未签名,需要装到设备时再补签名配置。
七、几个设计取舍
一维数组 vs 二维数组:一维在 Grid 的 ForEach 中更顺手,行列宫换算只是一次除法和取模;如果后续要做二维动画,再包一层映射即可。
冲突掩码 vs 单点判断:掩码让「所有冲突格同时高亮」成为可能,也让逻辑层更容易测试;代价是每次填数都重算一遍 81 格,但这个量级对现代设备完全可以忽略。
文件直读 vs 键值存储:数据量小、结构简单的场景,JSON 文件更透明、更好调试;如果要做多字段频繁读写,再考虑 Preferences 并注意其缓存行为。
确定性题库 vs 服务端下发:纯端侧零成本、离线可用;如果要做排行榜或云同步,再引入云函数和数据库,但那就是另一个量级的工程了。
小结
这个数独案例没有一行后端代码,却完整覆盖了鸿蒙端侧应用的四块基础能力:用声明式 UI 描述界面,用纯函数承载规则,用确定性随机生成内容,用文件 API 保存状态。把职责拆清楚之后,代码量不大,但每一层都能单独测试、单独替换。想练手 ArkTS 的同学,从这类「离线逻辑小游戏」入手,比一上来就做端云协同项目更容易跑通全流程。
本文为原创实践记录,示例代码已在 HarmonyOS 云端环境通过 hvigorw 编译验证,欢迎交流更优的棋盘渲染与题库生成方案。
- 点赞
- 收藏
- 关注作者
评论(0)