鸿蒙原生开发手记：徒步迹 - 应用生命周期与AbilityStage

掌握应用级生命周期，构建稳健的鸿蒙应用

---

一、前言

应用生命周期管理是保证 App 稳定运行的基础。在鸿蒙 Stage 模型中，除了每个 Ability 的生命周期，还提供了 AbilityStage 来管理应用级生命周期事件。

本文将详细介绍鸿蒙应用的生命周期体系，包括 AbilityStage、应用状态保存与恢复、内存管理等关键话题。

---

二、AbilityStage 详解

AbilityStage 是 Stage 模型中的应用级生命周期入口，类似于 Android 的 Application。

2.1 创建 AbilityStage

// MyAbilityStage.ets
import { AbilityStage, Want } from '@kit.AbilityKit';

export default class MyAbilityStage extends AbilityStage {
  // 应用创建时调用（首次启动）
  onCreate(): void {
    console.info('[徒步迹] AbilityStage onCreate');

    // 初始化全局配置
    this.initGlobalConfig();

    // 初始化日志系统
    Logger.init();

    // 初始化崩溃收集
    CrashCollector.init();

    // 预加载数据
    this.preloadData();
  }

  // 多实例模式下，指定实例标识
  onAcceptWant(want: Want): string {
    // 根据 Want 参数返回实例 key
    if (want.parameters) {
      const type = want.parameters['instanceType'] as string;
      if (type === 'tracking') {
        return `tracking_${Date.now()}`;
      }
      if (type === 'route') {
        const routeId = want.parameters['routeId'] as number;
        return `route_${routeId}`;
      }
    }
    return `default_${Date.now()}`;
  }

  // 配置文件中声明
  // module.json5 中配置 srcEntry 指向此文件
  // "srcEntry": "./ets/myabilitystage/MyAbilityStage.ets"

  private initGlobalConfig(): void {
    // 初始化全局存储
    if (!AppStorage.get('initialized')) {
      AppStorage.setOrCreate('initialized', true);
      AppStorage.setOrCreate('appVersion', '1.0.0');
      AppStorage.setOrCreate('stepGoal', 10000);
      AppStorage.setOrCreate('themeMode', 'light');
    }
  }

  private preloadData(): void {
    // 预加载必要配置
    // 例如从 Preferences 读取用户设置
    console.info('[徒步迹] 预加载完成');
  }
}

2.2 配置 module.json5

{
  "module": {
    "name": "entry",
    "type": "entry",
    "srcEntry": "./ets/myabilitystage/MyAbilityStage.ets",
    "abilities": [
      {
        "name": "EntryAbility",
        "srcEntry": "./ets/entryability/EntryAbility.ets"
      }
    ]
  }
}

---

三、应用生命周期完整流程

3.1 启动流程

用户点击图标
     ↓
系统创建 Application Process
     ↓
AbilityStage.onCreate()     ← 应用级初始化
     ↓
UIAbility.onCreate()        ← 页面级初始化
     ↓
UIAbility.onWindowStageCreate()  ← 加载页面
     ↓
UIAbility.onForeground()    ← 用户可见
     ↓
页面 aboutToAppear()         ← 页面准备显示
     ↓
应用正常启动完成 ✅

3.2 后台运行流程

用户按 Home 键 / 切换到其他 App
     ↓
UIAbility.onBackground()    ← 进入后台
     ↓
页面 aboutToDisappear()     ← 页面隐藏
     ↓
系统可能保留或回收进程

3.3 回到前台流程

用户从最近任务切回 App
     ↓
UIAbility.onForeground()    ← 回到前台
     ↓
页面 aboutToAppear()        ← 重新显示

3.4 销毁流程

用户划掉 App / 系统回收
     ↓
UIAbility.onWindowStageDestroy()
     ↓
UIAbility.onDestroy()       ← Ability 销毁
     ↓
AbilityStage.onDestroy()    ← 应用销毁（进程结束）

---

四、应用状态保存与恢复

4.1 保存状态

在 onBackground 中保存关键状态：

export default class EntryAbility extends UIAbility {
  onBackground(): void {
    console.info('[徒步迹] 进入后台，保存状态');

    // 保存页面状态
    let stepCount = AppStorage.get<number>('stepCount');
    let distance = AppStorage.get<number>('todayDistance');

    // 保存到持久化存储
    let preferences = this.context.preferences;
    preferences.put('stepCount', stepCount ?? 0);
    preferences.put('todayDistance', distance ?? 0);
    preferences.flush();
  }
}

4.2 恢复状态

在 onCreate 或 onForeground 中恢复：

export default class EntryAbility extends UIAbility {
  async onForeground(): Promise<void> {
    console.info('[徒步迹] 回到前台，恢复状态');

    // 从持久化存储恢复
    let preferences = this.context.preferences;
    let savedSteps = await preferences.get('stepCount', 0);
    let savedDistance = await preferences.get('todayDistance', 0);

    AppStorage.setOrCreate('stepCount', savedSteps);
    AppStorage.setOrCreate('todayDistance', savedDistance);
  }
}

4.3 配置异常恢复

// module.json5 配置恢复策略
{
  "abilities": [
    {
      "name": "EntryAbility",
      "launchType": "singleton",
      "recovery": {
        "enabled": true,        // 启用异常恢复
        "maxRecoveryCount": 3,  // 最大恢复次数
      }
    }
  ]
}

---

五、页面生命周期

除了 Ability 生命周期，每个页面也有自己的生命周期：

@Entry
@Component
struct HomePage {
  // 页面即将显示
  aboutToAppear(): void {
    console.info('[徒步迹] HomePage aboutToAppear');
    // 加载数据、初始化状态
    this.loadTodayData();
  }

  // 页面即将消失
  aboutToDisappear(): void {
    console.info('[徒步迹] HomePage aboutToDisappear');
    // 释放资源、保存临时状态
  }

  // 页面尺寸变化（如折叠屏展开）
  onPageHide(): void {
    console.info('[徒步迹] HomePage onPageHide');
  }

  // 页面重新显示
  onPageShow(): void {
    console.info('[徒步迹] HomePage onPageShow');
    // 刷新数据
    this.refreshData();
  }

  // 返回键处理
  onBackPress(): boolean {
    console.info('[徒步迹] HomePage onBackPress');
    // 返回 true 表示拦截返回事件
    return false;
  }

  build() {
    // ...
  }
}

---

六、内存与进程管理

6.1 内存警告

应用可以监听系统内存警告，及时释放资源：

export default class EntryAbility extends UIAbility {
  // 系统内存不足时调用
  onMemoryLevel(level: number): void {
    if (level === MemoryLevel.MEMORY_LEVEL_MODERATE) {
      // 中等内存压力：释放缓存
      ImageCache.clear();
    } else if (level === MemoryLevel.MEMORY_LEVEL_CRITICAL) {
      // 严重内存压力：释放所有非必要资源
      this.releaseAllResources();
    }
  }

  private releaseAllResources(): void {
    AppStorage.delete('cachedRoutes');
    AppStorage.delete('cachedPhotos');
  }
}

6.2 配置进程优先级

// module.json5
{
  "module": {
    "name": "entry",
    "process": "com.hiking.tuji",
    "keepAlive": true  // 后台定位场景需保持活跃
  }
}

---

七、实践建议

7.1 初始化顺序

export default class MyAbilityStage extends AbilityStage {
  onCreate(): void {
    // 第1步：日志系统
    Logger.init();

    // 第2步：崩溃收集
    CrashCollector.init();

    // 第3步：全局配置
    ConfigManager.init();

    // 第4步：数据库
    DatabaseManager.init();

    // 第5步：用户信息
    UserManager.init();
  }
}

7.2 资源释放检查清单

□ 取消网络请求
□ 停止定时器
□ 释放图片缓存
□ 关闭数据库连接
□ 停止位置监听
□ 注销事件监听

---

八、总结

应用生命周期管理是 App 稳定性的基础。通过 AbilityStage 进行应用级初始化，通过 UIAbility 生命周期管理页面状态，通过页面生命周期控制 UI 行为，形成了一个完整的生命周期管理体系。

第一阶段（项目搭建与语言基础）到此全部完成。从下一篇文章开始，我们将正式进入"徒步迹"核心页面的实战开发。

---

下一篇预告：鸿蒙原生开发手记：徒步迹 - 启动页(Splash)设计与实现