鸿蒙数独小游戏源码拆解:纯端侧 ArkUI 如何组织状态与渲染
为什么选数独做样本
数独看起来简单,但它的状态结构相当典型:一个 9×9 的二维网格,每个格子有「给定值 / 用户填入值 / 候选标记」三种状态,还要实时校验行、列、宫三重约束是否冲突。这套逻辑几乎涵盖了中后台表单类应用的所有状态管理难点。
而且数独是纯端侧应用,不依赖云服务,正好可以用来看清 ArkUI 本身的能力边界:它的状态装饰器怎么用、列表渲染怎么做、手势如何处理。
本文基于鸿蒙实践中心的数独小游戏案例(Harmony-APP-sudoku),拆解它的实现思路。
一、工程结构
典型的 HarmonyOS 应用目录大致是这样:
entry/src/main/ets/
├── pages/
│ └── Index.ets 入口页
├── model/
│ └── SudokuModel.ets 棋局数据结构与算法
├── view/
│ ├── BoardView.ets 棋盘视图
│ └── CellView.ets 单元格组件
└── common/
└── Constants.ets 常量与主题
把「数据模型」和「视图组件」分开是关键。数独的求解、校验、生成逻辑全在 model 层,视图只负责把数据渲染出来,并把手势事件回传。这样即使后面换 UI 主题,算法层不用改。
二、数据结构设计
2.1 单元格模型
最直观的做法是给每个格子一个对象:
class Cell {
value: number = 0; // 0 表示空
given: boolean = false; // 是否为题目给定
candidates: number[] = [];// 候选数标记
conflict: boolean = false;// 是否与同行列宫冲突
}
given 这个字段很重要。题目预设的数字不允许用户修改,界面上通常用不同颜色区分。用布尔标记而不是把「题目原始状态」和「当前状态」分两个数组存,能省掉不少同步逻辑。
2.2 棋盘状态
整个棋盘就是一个 9×9 的 Cell 数组,外加几个全局状态:
selectedRow/selectedCol:当前选中的格子history:操作历史,用于撤销elapsedSeconds:计时器isCompleted:是否已解出
历史记录用栈来实现,每步操作压入一条 {row, col, oldValue, newValue} 记录,撤销就是弹出并还原。
三、状态驱动渲染
3.1 装饰器的选择
ArkUI 提供了几种状态装饰器,用途不同:
| 装饰器 | 适用场景 |
|---|---|
| @State | 组件内部状态,变化触发自身重渲染 |
| @Prop | 父到子的单向数据传递 |
| @Link | 父子的双向绑定 |
| @Observed / @ObjectLink | 嵌套对象或数组内部元素变化时触发更新 |
数独这个场景有个坑:如果只用 @State 直接管理二维数组,修改数组里某个元素的值不会触发渲染。因为 @State 只监听引用变化,不监听内部深层属性的变化。
正确做法有两种:一是把 Cell 类用 @Observed 装饰,单元格组件用 @ObjectLink 接收;二是每次修改后整体替换数组(用扩展运算符生成新数组)。前者性能更好,后者写法更简单。
3.2 网格布局
9×9 的棋盘用 Grid 组件最自然:
Grid() {
ForEach(this.cells, (cell: Cell, index: number) => {
GridItem() {
CellView({ cell: cell })
}
})
}
.columnsTemplate('1fr 1fr 1fr 1fr 1fr 1fr 1fr 1fr 1fr')
.rowsTemplate('1fr 1fr 1fr 1fr 1fr 1fr 1fr 1fr 1fr')
用 1fr 而不是固定像素,棋盘能自适应不同屏幕宽度。ForEach 的第三个参数是 key 生成函数,一定要写,否则列表更新会错乱。
四、冲突校验的实现
数独的校验要分三个维度:同行、同列、同宫。写成一个函数统一处理:
checkConflict(row: number, col: number, value: number): boolean {
for (let i = 0; i < 9; i++) {
if (i !== col && this.cells[row][i].value === value) return true;
if (i !== row && this.cells[i][col].value === value) return true;
}
const br = Math.floor(row / 3) * 3;
const bc = Math.floor(col / 3) * 3;
for (let r = br; r < br + 3; r++) {
for (let c = bc; c < bc + 3; c++) {
if ((r !== row || c !== col) && this.cells[r][c].value === value) return true;
}
}
return false;
}
注意 Math.floor(row/3)*3 这个算法,它是定位当前格子所属宫左上角的标准写法。三个循环都是 O(27),一次校验的成本可以忽略,所以不必做缓存优化。
实际使用时,每次用户填入数字后,不只是校验当前格子,还要重新校验整个棋盘——因为填入一个数可能让之前合法的格子变成冲突。把所有冲突格标红,用户一眼就能看出问题在哪。
五、手势与输入
数独的交互有两部分:选格子和填数字。
- 选格子:点击棋盘某个格,设置
selectedRow/selectedCol - 填数字:底部数字键盘 1-9,点击后填入当前选中格
也可以支持滑动选择:用一个 PanGesture 监听拖动过程,经过的格子高亮。这个体验更接近真实笔纸做题,但要注意手势冲突——如果外层有滚动容器,需要设置 .gesture() 的优先级。
六、几个实用细节
6.1 高亮同行列宫
选中某个格子后,把它所在的整行、整列、整宫用浅色背景标出,同时把棋盘上所有相同数字的格子也高亮。这个小细节对做题体验提升很大,实现上只是在渲染时多判断几个条件。
6.2 自动清理候选数
如果实现了候选数标记功能,那么填入一个数字后,应该自动把它从同行列宫的候选列表里移除。这是数独解题的核心技巧之一,程序化实现后能省掉大量手动擦除。
6.3 计时与暂停
计时器用 setInterval 每秒更新一次显示即可。但要注意页面切到后台时应该暂停计时,否则时间不准。ArkUI 的 onPageHide / onPageShow 生命周期可以做这件事。
七、小结
数独案例的价值不在于游戏本身,而在于它完整演示了一类应用的骨架:
- 数据模型和视图分离,算法不依赖 UI 框架
- 状态管理用对装饰器,避免「改了数据但界面不动」的坑
- 校验逻辑集中在一处,渲染时统一读取
- 手势和布局用响应式单位,适配不同屏幕
把这套骨架吃透,再去做记账本、待办清单、日程表这类应用,结构上几乎是同一套东西换皮。这也是实践中心选这几个案例作为入门的原因——它们练的都是通用的工程能力。
- 点赞
- 收藏
- 关注作者
评论(0)