HarmonyOS应用开发实战：猫猫大作战-@private 封装与构造器初始化

david

228人浏览 · 2026-07-29 13:13:59

david · 2026-07-29 13:13:59 发布

文章配图：@private 封装与构造器初始化

页面预览

前言

在 ArkTS 中，private 是类的访问修饰符，用于封装内部实现细节。在「猫猫大作战」的 GameEngine 类中，棋盘数据、定时器、合并逻辑等内部状态都标记为 private，只暴露必要的公开方法。合理的封装能降低耦合、减少意外修改、提高代码可维护性。

本文以「猫猫大作战」的 GameEngine 为锚点，讲解 private 的封装原则、构造器初始化、以及公开 API 的设计。

一、private 封装

export class GameEngine {
  private board: (Cat | null)[][];   // 棋盘数据（外部不可直接修改）
  private score: number = 0;
  private combo: ComboInfo;
  private gameLoopTimer: number = -1;

  // 只读访问器
  getScore(): number { return this.score; }
  getCombo(): ComboInfo { return { ...this.combo }; }

  // 公开方法
  startGame(): void { /* ... */ }
  updateCats(): Cat[] { /* ... */ }
  isGameOver(): boolean { /* ... */ }
}

成员	可见性	为什么 private
`board`	private	棋盘只能通过引擎方法修改
`score`	private	得分通过 `getScore()` 只读访问
`combo`	private	返回副本防外部修改
`timer`	private	外部不应直接操作定时器

二、构造器初始化

export class GameEngine {
  private board: (Cat | null)[][];

  constructor() {
    // 初始化 5×8 空棋盘
    this.board = Array.from(
      { length: GameConfig.BOARD_HEIGHT },
      () => Array(GameConfig.BOARD_WIDTH).fill(null)
    );
    this.score = 0;
    this.combo = { count: 0, multiplier: 1, lastMergeTime: 0 };
  }

  reset(): void {
    this.board = Array.from(
      { length: GameConfig.BOARD_HEIGHT },
      () => Array(GameConfig.BOARD_WIDTH).fill(null)
    );
    this.score = 0;
    this.combo = { count: 0, multiplier: 1, lastMergeTime: 0 };
  }
}

三、公开 API 设计

export class GameEngine {
  // 只读查询
  getBoard(): (Cat | null)[][] { return this.board.map(row => [...row]); }
  getAllCats(): Cat[] { /* ... */ }
  getCatAt(x: number, y: number): Cat | null { /* ... */ }

  // 操作方法（外部触发）
  placeCat(col: number, level: CatLevel): boolean { /* ... */ }
  tryMergeAt(x: number, y: number): boolean { /* ... */ }
  updateCats(): Cat[] { /* ... */ }

  // 状态查询
  isGameOver(): boolean { /* ... */ }
  getScore(): number { return this.score; }
  getCombo(): ComboInfo { return { ...this.combo }; }
}

四、最佳实践

默认 private：除非需要外部访问，否则全部 private
返回只读副本：getCombo() 返回 { ...this.combo } 防外部修改
构造器初始化所有字段：避免字段未定义
reset() 复用初始化逻辑：提取为 initBoard() 方法共用

private initBoard(): (Cat | null)[][] {
  return Array.from(
    { length: GameConfig.BOARD_HEIGHT },
    () => Array(GameConfig.BOARD_WIDTH).fill(null)
  );
}

五、常见错误

错误	原因	修复
外部直接修改 `engine.board`	board 为 public	改为 private + getter
构造器未初始化	字段声明时赋默认值	`score: number = 0`
返回了内部引用	外部修改了引擎数据	返回深拷贝