ArkTS + ArkUI 实战:用 HarmonyOS 写一个纯端侧数独小游戏

举报
yd_246800664 发表于 2026/11/16 10:42:06 2026/11/16
【摘要】 从零实现一个离线可玩的鸿蒙数独:用声明式 UI 渲染 9×9 棋盘并实时高亮冲突,用纯函数把校验逻辑与界面解耦,用确定性 PRNG 生成 54 道可复现题库,用 @ohos.file.fs 直读 JSON 记录通关进度,并整理 hvigorw 命令行编译打包时 SDK 版本不匹配等常见错误。

为什么要在端侧做一局数独

数独是个特别适合练手的题材:规则清楚、没有网络依赖、但又能把声明式 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 编译验证,欢迎交流更优的棋盘渲染与题库生成方案。

【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0)

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。