【HarmonyOS 5】鸿蒙中的 UIAbility 详解（一）
一、UIAbility 是什么？
Stage 模型中的组件类型名，即 UIAbility 组件，包含 UI，提供展示 UI 的能力，主要用于和用户交互。
UIAbility 类似于传统移动开发 Android 中的 Activity 或者 Fragment。类似 IOS 开发中的 UIViewController。
UIAbility 是 HarmonyOS 应用框架的核心组件，负责管理应用的用户界面生命周期和上下文信息。
二、设置指定启动页面
启动页面必须设置：否则应用启动后会白屏。
避免应用启动后白屏，需在onWindowStageCreate生命周期中设置默认加载页面。通过WindowStage的loadContent()方法指定页面路径。
export default class EntryAbility extends UIAbility { onWindowStageCreate(windowStage: window.WindowStage): void { windowStage.loadContent('pages/Index', (err, data) => { /* 处理回调 */ }); } }
复制代码
DevEco Studio 默认生成的项目会自动加载Index页面，可按需修改路径。
三、获取上下文信息（UIAbilityContext）
获取应用配置信息（如包名、Ability 名称等），或调用操作 Ability 的方法（如启动、终止 Ability）。通过this.context直接访问。
export default class EntryAbility extends UIAbility { onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { const context = this.context; // 直接获取上下文 } }
复制代码
在页面组件中获取：通过getUIContext().getHostContext()转换为UIAbilityContext。
@Entry @Component struct Page { private context = this.getUIContext().getHostContext() as common.UIAbilityContext; startAbilityTest() { this.context.startAbility(want); } // 启动其他Ability }
复制代码
启动页面设置与上下文使用代码示例
// UIAbility定义export default class EntryAbility extends UIAbility { onWindowStageCreate(windowStage: window.WindowStage) { windowStage.loadContent('pages/Main', () => {}); // 设置启动页面 }
onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { const context = this.context; // 获取上下文 context.startAbility({ abilityName: 'OtherAbility' }); // 启动其他Ability }}
// 页面组件中使用上下文@Entry@Componentstruct MainPage { private context = this.getUIContext().getHostContext() as common.UIAbilityContext; build() { Button('终止当前Ability').onClick(() => this.context.terminateSelf()); }}
复制代码
四、UIAbility 生命周期与操作
UIAbility 的生命周期包含 Create（创建）、Foreground（前台）、Background（后台）、Destroy（销毁） 四个核心状态，以及与窗口（WindowStage）相关的子状态。通过生命周期回调钩子函数，可监听状态变化并执行对应操作。
生命周期状态流转图
创建实例 窗口创建 进入前台 切到后台 窗口销毁 实例销毁 ↓ ↓ ↓ ↓ ↓ ↓onCreate() → onWindowStageCreate() → onForeground() → onBackground() → onWindowStageDestroy() → onDestroy() ↑ ↖ ↗ ↖ ↑ └─────── WindowStageWillDestroy() ────────────────────────┘
复制代码
1、onCreate
UIAbility 实例创建完成时触发。初始化页面数据、加载资源（如定义变量、获取上下文this.context）。
export default class EntryAbility extends UIAbility { onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { // 初始化操作（如获取上下文、配置数据） const context = this.context; } }
复制代码
2、WindowStageCreate
UIAbility 实例创建后，进入前台前，系统创建 WindowStage 时触发。设置启动页面（loadContent()）、订阅窗口事件（如前后台切换、焦点变化）。
onWindowStageCreate(windowStage: window.WindowStage) { windowStage.loadContent('pages/Index'); // 设置启动页面 windowStage.on('windowStageEvent', (event) => { // 订阅窗口事件 switch (event) { case window.WindowStageEventType.SHOWN: // 切到前台 console.log('窗口切到前台'); break; } }); }
复制代码
3、WindowStageWillDestroy
WindowStage 销毁前触发（此时窗口仍可用）。释放通过 WindowStage 获取的资源，注销事件订阅（off('windowStageEvent')）。
4、WindowStageDestroy
WindowStage 销毁时触发（UI 资源释放）。释放 UI 相关资源（如临时文件、图形对象）。
5、Foreground
UIAbility 切换至前台、UI 可见前触发。申请系统资源（如定位、传感器权限）、恢复后台释放的资源。
onForeground() { // 开启定位功能 location.start(); }
复制代码
6、Background
UIAbility 切换至后台、UI 完全不可见后触发。释放无用资源、执行耗时操作（如数据持久化）。
onBackground() { // 停止定位、保存当前状态 location.stop(); saveDataToLocal(); }
复制代码
7、onDestroy
UIAbility 实例被终止时触发（如调用terminateSelf()）。释放全局资源、清理内存（如关闭网络连接、注销监听器）。
onDestroy() { // 释放数据库连接、取消定时器 db.close(); clearInterval(timer); }
复制代码
注意：API 13+中，若用户通过最近任务一键清理应用，不会触发onDestroy()，而是直接终止进程。
四、UIAbility 的常用函数操作
1. 终止 UIAbility 实例
调用terminateSelf()终止当前 Ability。
context.terminateSelf((err) => { if (err) { console.error('终止失败:', err); } else { console.info('终止成功'); } });
复制代码
2. 获取拉起方信息
当 UIAbilityA 通过startAbility启动 UIAbilityB 时，UIAbilityB 可获取调用方信息。
export default class UIAbilityB extends UIAbility { onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { console.log(`调用方Pid: ${want.parameters?.['ohos.aafwk.param.callerPid']}`); } }
复制代码
跨 Ability 信息传递代码示例
// UIAbilityA中启动UIAbilityB@Entry@Componentstruct UIAbilityAPage { private context = this.getUIContext().getHostContext() as common.UIAbilityContext; build() { Button('拉起UIAbilityB').onClick(() => { this.context.startAbility({ bundleName: this.context.abilityInfo.bundleName, abilityName: 'UIAbilityB' }); }); }}
// UIAbilityB中获取调用方信息export default class UIAbilityB extends UIAbility { onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { console.log(`调用方包名: ${want.parameters?.['ohos.aafwk.param.callerBundleName']}`); }}
复制代码
注意
当 UIAbility 设置为singleton启动模式时，重复调用startAbility()启动同一实例，不会重新走onCreate和onWindowStageCreate流程，而是触发onNewWant回调。
onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam) { // 根据新的Want参数更新页面数据 this.data = want.parameters?.data; }
复制代码
评论