鸿蒙应用开发UI基础第三节：UIAbility生命周期全解析

【学习目标】

掌握UIAbility核心生命周期方法的触发时机、系统行为及约束规则；
理解生命周期与WindowStage的深度联动逻辑，明确页面加载、事件订阅的时机；
掌握onDestroy回调的特殊触发规则（含API 13一键清理、调试模式、terminateSelf调用场景）；
能通过实操验证生命周期执行顺序，掌握WindowStage事件监听的正确方式，避免新手常见混淆；
区分"应用退后台"与"应用销毁"的核心差异，规避生命周期相关的开发误区。

【本节重点】

1. 核心问题导入

应用启动、切后台、切前台、退出时，UIAbility会经历哪些状态变化？
窗口的获焦/失焦、前台/后台状态该如何通过WindowStage事件监听？
WindowStage的事件订阅与解绑，分别应在哪个生命周期方法中执行？
不同关闭应用的方式（手动调用API、一键清理、调试模式移除任务）对onDestroy触发有何影响？
为什么页面只能在onWindowStageCreate中加载，不能在onCreate中加载？

2. 核心概念

UIAbility生命周期是指UIAbility从创建到销毁的全流程，由系统统一调度，包含创建、窗口管理、前后台切换、销毁等核心阶段。通过重写生命周期方法，可在特定时机完成初始化、资源申请/释放、页面加载等操作；

窗口的活动状态（获焦/失焦、前台/后台）需通过WindowStage事件监听实现，而非生命周期方法。
onDestroy作为生命周期最后一个方法，其触发与否受关闭应用的方式、API版本、应用类型（有无实况窗）、运行模式（调试/正式）等因素影响。

本节内容延用FirstApplication工程,无新增文件。使用默认启动模式singleton。

二、UIAbility生命周期核心阶段与方法

1. 生命周期可视化示意图

生命周期的完整流转逻辑可通过以下示意图直观理解，涵盖启动、前后台切换、关闭全流程的方法触发顺序与WindowStage事件关联：

示意图说明：左侧为UIAbility核心生命周期方法，右侧为关联的WindowStage事件，窗口的获焦/失焦、前台/后台状态需通过windowStageEvent事件监听实现；销毁阶段的onDestroy触发规则需结合关闭应用的方式判断。

2. 核心方法

以下是UIAbility核心生命周期方法的详细说明，聚焦各方法的触发时机、核心作用与执行次数：

`onCreate(want, launchParam)`

触发时机：UIAbility实例首次创建时触发；
核心作用 ：完成应用全局初始化工作，比如建立数据库连接、初始化全局配置参数、日志模块、网络配置、创建全局通用工具类等，这些资源会在onDestroy中对应释放；
执行次数：整个UIAbility实例生命周期内仅触发1次。

`onWindowStageCreate(windowStage)`

触发时机：UIAbility实例创建完成后、应用进入前台前，且系统首次创建WindowStage（窗口容器）时触发；
核心作用：负责页面加载、订阅WindowStage相关事件（如窗口焦点变化、显示/隐藏事件）；
执行次数：单实例（singleton）模式下仅触发1次（多实例模式下每次创建新实例都会触发）。

`onForeground()`

触发时机：UIAbility从后台切换至前台、界面即将可见之前触发；
核心作用：恢复前台运行所需资源，比如重启暂停的定时器、重新开启定位服务、恢复网络请求轮询等；
执行次数：可多次触发（每次切前台都会执行）。

`onBackground()`

触发时机：UIAbility界面完全不可见（如按Home键切后台、打开其他应用覆盖当前界面）后触发；
核心作用 ：暂停前台资源以节省系统开销，比如停止定时器、关闭定位服务、保存用户操作数据（作为onDestroy未触发时的兜底方案）；
执行次数：可多次触发（每次切后台都会执行）。

`onWindowStageWillDestroy(windowStage)`

触发时机：WindowStage（窗口容器）即将被销毁前触发；
核心作用 ：解绑在onWindowStageCreate中订阅的WindowStage事件、清理窗口相关缓存资源，避免内存泄漏；
执行次数 ：仅在应用"优雅销毁"（如调用terminateSelf()、正常退出）时触发1次，一键清理等强制销毁场景不触发。

`onWindowStageDestroy()`

触发时机：WindowStage（窗口容器）销毁完成后触发；
核心作用：确认窗口相关资源已释放，做最终的窗口状态校验；
执行次数：仅在应用"优雅销毁"时触发1次，强制销毁场景不触发。

`onDestroy()`

触发时机：UIAbility实例即将被销毁前触发；
核心作用 ：释放onCreate中初始化的全局资源，比如关闭数据库连接、清理全局缓存、保存最终的应用状态数据；
执行次数：仅在"优雅销毁"时触发1次（API 13+中，无实况窗应用被一键清理、调试模式移除任务时，系统直接终止进程，该方法不触发）。

`onNewWant(want, launchParam)`

触发时机：UIAbility实例已启动（未销毁）、再次被外部调用（如其他页面/应用跳转）时触发；
核心作用：处理新的启动参数，比如接收跳转传参、更新页面展示内容；
执行次数：按需触发（每次复用实例调用都会执行）。

注意：

onDestroy触发特殊规则：API 13及以上版本中，无实况窗应用被一键清理、调试模式下移除任务时，系统直接终止进程，该方法不会触发；仅terminateSelf()调用、正常返回退出、有实况窗应用被一键清理时触发。

3. WindowStage事件详解（监听窗口活动状态）

窗口的所有活动状态均通过windowStageEvent事件监听，核心事件说明：

SHOWN：窗口从后台切换到前台（可见），代表应用切前台；
HIDDEN：窗口从前台切换到后台（不可见），代表应用切后台；
ACTIVE：窗口获得焦点（可接收点击/输入），处于可交互状态；
INACTIVE：窗口失去焦点（无法接收输入），处于不可交互状态；
RESUMED：窗口进入前台可交互状态，应用正常运行；
PAUSED：窗口进入前台不可交互状态。

三、完整生命周期代码示例

javascript 复制代码

import { UIAbility, AbilityConstant, Want, common } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
import { hilog } from '@kit.LogKit';
import { BusinessError } from '@ohos.base';

const TAG = 'UIAbility_Lifecycle';
const DOMAIN = 0x0000;

export default class EntryAbility extends UIAbility {
  // 1. 创建阶段（仅1次）
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
    hilog.info(DOMAIN, TAG, '--- onCreate 触发（全局初始化）---');
    // 资源初始化：全局配置、数据库连接等（对应释放：onDestroy）
  }

  // 2. 窗口创建阶段（窗口首次创建/重建）
  onWindowStageCreate(windowStage: window.WindowStage): void {
    hilog.info(DOMAIN, TAG, '--- onWindowStageCreate 触发（加载页面）---');
    // 订阅WindowStage事件
    this.registerWindowStageEvent(windowStage);
    // 加载页面（唯一合法时机）
    windowStage.loadContent('pages/Index').then(()=>{
      hilog.info(DOMAIN, TAG, 'Index页面加载成功');
    }).catch((err:BusinessError)=>{
      hilog.error(DOMAIN, TAG, `页面加载失败：code=${err.code}, message=${err.message}`);
    })
  }

  // 3. 前台阶段（切前台时）
  onForeground() {
    hilog.info(DOMAIN, TAG, '--- onForeground 触发（恢复前台资源）---');
    // 启动前台专属资源（定时器、定位等）
  }

  // 4. 后台阶段（切后台时）
  onBackground() {
    hilog.info(DOMAIN, TAG, '--- onBackground 触发（释放后台资源）---');
    // 暂停前台资源，保存关键数据（兜底）
  }

  // 5. 窗口预销毁阶段（窗口即将销毁）
  onWindowStageWillDestroy(windowStage: window.WindowStage) {
    hilog.info(DOMAIN, TAG, '--- onWindowStageWillDestroy 触发（窗口预销毁）---');
    // 解绑WindowStage事件，避免内存泄漏
    this.unregisterWindowStageEvent(windowStage);
  }

  // 6. 窗口销毁阶段（窗口已销毁）
  onWindowStageDestroy() {
    hilog.info(DOMAIN, TAG, '--- onWindowStageDestroy 触发（销毁窗口）---');
    // 窗口实例失效，无需额外操作
  }

  // 7. 销毁阶段（仅1次，存在不触发场景）
  onDestroy() {
    hilog.info(DOMAIN, TAG, '--- onDestroy 触发（销毁应用）---');
    // 释放全局资源、保存最终数据
  }

  // 8. 新参数阶段（已启动后接收新请求）
  onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam) {
    hilog.info(DOMAIN, TAG, `--- onNewWant 触发（新参数：${JSON.stringify(want)}）---`);
    // 处理新的启动参数
  }
  /**
   * 订阅WindowStage事件（监听窗口活动状态）
   * @param windowStage - 当前窗口实例
   */
  private registerWindowStageEvent(windowStage: window.WindowStage): void {
    try {
      windowStage.on('windowStageEvent', (data) => {
        const stageEventType: window.WindowStageEventType = data;
        switch (stageEventType) {
          case window.WindowStageEventType.SHOWN:
            hilog.info(DOMAIN, TAG, `windowStage foreground`);
            break;
          case window.WindowStageEventType.ACTIVE:
            hilog.info(DOMAIN, TAG, `windowStage active`);
            break;
          case window.WindowStageEventType.INACTIVE:
            hilog.info(DOMAIN, TAG, `windowStage inactive`);
            break;
          case window.WindowStageEventType.HIDDEN:
            hilog.info(DOMAIN, TAG, `windowStage background`);
            break;
          case window.WindowStageEventType.RESUMED:
            hilog.info(DOMAIN, TAG, `windowStage resumed`);
            break;
          case window.WindowStageEventType.PAUSED:
            hilog.info(DOMAIN, TAG, `windowStage paused.`);
            break;
          default:
            break;
        }
      });
      hilog.info(DOMAIN, TAG, 'WindowStage事件订阅成功');
    } catch (exception) {
      hilog.error(DOMAIN, TAG, `订阅窗口事件失败：${JSON.stringify(exception)}`);
    }
  }

  /**
   * 解绑WindowStage事件（资源释放）
   */
  private unregisterWindowStageEvent(windowStage: window.WindowStage): void {
    try {
      windowStage.off('windowStageEvent');
      hilog.info(DOMAIN, TAG, '窗口事件解绑成功');
    } catch (err) {
      hilog.error(DOMAIN, TAG, `解绑窗口事件失败：code=${err.code}, message=${err.message}`);
    }
  }
}

/**
 * 手动停止当前UIAbility实例（触发onDestroy）
 */
export function stopCurrentAbility(context: common.UIAbilityContext): void {
  context.terminateSelf().then(()=>{
    hilog.info(DOMAIN, TAG, 'terminateSelf调用成功，将触发onDestroy');
  }).catch((err: BusinessError) => {
    hilog.error(DOMAIN, TAG, `停止UIAbility失败：code=${err.code}, message=${err.message}`);
  });
}

四、新增手动关闭应用Index.ets

javascript 复制代码

import { common } from '@kit.AbilityKit';
import { stopCurrentAbility } from '../entryability/EntryAbility';

@Entry
@Component
struct Index {
  @State message: string = '第一个应用';
  private context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext;

  aboutToAppear(): void {}

  build() {
    Column() {
      Text(this.message)
        .fontSize($r('app.float.page_text_font_size'))
        .fontWeight(FontWeight.Bold);

      Button("关闭应用程序")
        .onClick(()=>{
          stopCurrentAbility(this.context);
        });
    }
    .height('100%')
    .width('100%');
  }
}

五、实战实操：验证生命周期执行顺序

目标

通过手动操作应用，在Logcat中观察生命周期方法和WindowStage事件的触发顺序，重点验证不同场景下onDestroy的触发情况。

环境说明：开发工具最低支持API 13，无法测试API 12及以下版本，所有测试基于API 13 手机模拟器。

不同类型的设备监听窗口活动状态输出日志会有差异。

场景1：启动应用 → 返回桌面 → 再次打开应用

日志输出：

复制代码

<!-- 启动应用 -->
--- onCreate 触发（全局初始化）---
--- onWindowStageCreate 触发（加载页面）---
WindowStage事件订阅成功
--- onForeground 触发（恢复前台资源）---
windowStage foreground
windowStage active
Index页面加载成功

<!-- 返回桌面 -->
windowStage paused.
windowStage inactive
--- onBackground 触发（释放后台资源）---
windowStage background


<!-- 再次打开应用 -->
--- onNewWant 触发（新参数：{"deviceId":"","bundleName":"com.example.FirstApplication","abilityName":"EntryAbility","moduleName":"entry","uri":"","type":"","flags":0,"action":"action.system.home","parameters":{"debugApp":true,"moduleName":"entry","ohos.aafwk.param.displayId":0},"fds":{},"entities":["entity.system.home"]}）---
--- onForeground 触发（恢复前台资源）---
windowStage foreground
windowStage active

场景2：点击"关闭应用程序"按钮（调用terminateSelf）

日志输出：

复制代码

<!-- terminateSelf调用成功，将触发onDestroy -->
windowStage inactive
--- onBackground 触发（释放后台资源）---
windowStage background
--- onWindowStageWillDestroy 触发（窗口预销毁）---
窗口事件解绑成功
--- onWindowStageDestroy 触发（销毁窗口）---
--- onDestroy 触发（销毁应用）---

场景3：启动应用 → 切后台 → 一键清理无实况窗应用

日志输出：

复制代码

--- onCreate 触发（全局初始化）---
--- onWindowStageCreate 触发（加载页面）---
WindowStage事件订阅成功
--- onForeground 触发（恢复前台资源）---
windowStage foreground
windowStage active
Index页面加载成功
windowStage inactive
--- onBackground 触发（释放后台资源）---
windowStage background

关键结论 ：一键清理时系统直接终止进程，未触发onWindowStageWillDestroy/onWindowStageDestroy/onDestroy。

六、内容总结

生命周期分工 ：onCreate做全局初始化（仅1次），onWindowStageCreate负责页面加载/事件订阅（单实例模式下仅首次启动触发1次），onDestroy释放全局资源（API 13+一键清理无实况窗应用不触发）；
WindowStage核心规则 ：事件订阅/解绑必须成对出现在onWindowStageCreate/onWindowStageWillDestroy，避免内存泄漏；
数据安全兜底 ：因onDestroy存在不触发场景，关键数据需在onBackground中保存；
前后台切换链路 ：切后台先触发PAUSED/INACTIVE→onBackground→HIDDEN；切前台先触发SHOWN→onForeground→ACTIVE/RESUMED。

核心问题解答：为什么页面只能在`onWindowStageCreate`中加载？

页面加载的本质是将 UI 组件挂载到系统的窗口容器（WindowStage）上，两个生命周期阶段的核心差异决定了加载时机：

onCreate阶段：UIAbility 实例刚创建，系统尚未分配 WindowStage（无页面承载载体），此时调用loadContent会因无窗口容器而失败，甚至导致应用崩溃；
onWindowStageCreate阶段：系统已创建 WindowStage 并作为参数传入，此时拥有了页面渲染所需的窗口容器，是加载页面的时机。

新手避坑指南

禁止在onCreate中加载页面（无WindowStage实例）；
不要依赖onDestroy保存关键数据，优先在onBackground兜底；
生命周期回调是在应用主线程执行，为了确保应用性能，建议在生命周期回调中，仅执行必要的轻量级操作。对于耗时任务，推荐采用异步处理或交由子线程执行，避免阻塞主线程。
如果需要感知UIAbility生命周期变化，开发者可以使用ApplicationContext注册接口监听UIAbility生命周期变化。

javascript 复制代码

  // 定义生命周期ID
  private lifecycleId: number = -1;
  
  // 定义生命周期回调对象
  let abilityLifecycleCallback: AbilityLifecycleCallback = {
    // 各回调方法
  }
    // 获取应用上下文
  let applicationContext = this.context.getApplicationContext();
   // 注册应用内生命周期回调
  this.lifecycleId = applicationContext.on('abilityLifecycle', abilityLifecycleCallback);

七、代码仓库

工程名称：FirstApplication
仓库地址：https://gitee.com/HarmonyOS-UI-Basics/harmony-os-ui-basics.git

八、下节预告

下一节我们将系统学习UIAbility的全量启动模式，重点掌握：

multiton（多实例）、singleton（单实例）、specified（指定实例）三种启动模式的核心差异与实例创建规则；
不同启动模式的配置方法（module.json5配置+代码层面参数传递）和适用业务场景；
多实例/指定实例模式与生命周期的联动关系（分析onCreate/onNewWant/onWindowStageCreate的差异化触发逻辑）；
实操验证不同启动模式的效果，解决实例冲突、参数传递异常等开发常见问题。

鸿蒙应用开发UI基础第三节：UIAbility生命周期全解析

【学习目标】

【本节重点】

1. 核心问题导入

2. 核心概念

二、UIAbility生命周期核心阶段与方法

1. 生命周期可视化示意图

2. 核心方法

onCreate(want, launchParam)

onWindowStageCreate(windowStage)

onForeground()

onBackground()

onWindowStageWillDestroy(windowStage)

onWindowStageDestroy()

onDestroy()

onNewWant(want, launchParam)

3. WindowStage事件详解（监听窗口活动状态）

三、完整生命周期代码示例

四、新增手动关闭应用Index.ets

五、实战实操：验证生命周期执行顺序

目标

场景1：启动应用 → 返回桌面 → 再次打开应用

场景2：点击"关闭应用程序"按钮（调用terminateSelf）

场景3：启动应用 → 切后台 → 一键清理无实况窗应用

六、内容总结

核心问题解答：为什么页面只能在onWindowStageCreate中加载？

新手避坑指南

七、代码仓库

八、下节预告

`onCreate(want, launchParam)`

`onWindowStageCreate(windowStage)`

`onForeground()`

`onBackground()`

`onWindowStageWillDestroy(windowStage)`

`onWindowStageDestroy()`

`onDestroy()`

`onNewWant(want, launchParam)`

核心问题解答：为什么页面只能在`onWindowStageCreate`中加载？