鸿蒙UIAbility组件概述
UIAbility组件基本用法
指定UIAbility的启动页面
应用中的UIAbility在启动过程中，需要指定启动页面，否则应用启动后会因为没有默认加载页面而导致白屏。可以在UIAbility的onWindowStageCreate()生命周期回调中，通过WindowStage对象的loadContent()方法设置启动页面。
import { UIAbility } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
export default class EntryAbility extends UIAbility {
onWindowStageCreate(windowStage: window.WindowStage): void {
// Main window is created, set main page for this ability
windowStage.loadContent('pages/Index', (err, data) => {
// ...
});
}
// ...
}
获取UIAbility的上下文信息
UIAbility类拥有自身的上下文信息，该信息为UIAbilityContext类的实例，UIAbilityContext类拥有abilityInfo、currentHapModuleInfo等属性。通过UIAbilityContext可以获取UIAbility的相关配置信息，如包代码路径、Bundle名称、Ability名称和应用程序需要的环境状态等属性信息，以及可以获取操作UIAbility实例的方法（如startAbility()、connectServiceExtensionAbility()、terminateSelf()等）。
如果需要在页面中获得当前Ability的Context，可调用getContext接口获取当前页面关联的UIAbilityContext或ExtensionContext。
-
在UIAbility中可以通过this.context获取UIAbility实例的上下文信息。
import { UIAbility, AbilityConstant, Want } from '@kit.AbilityKit'; export default class EntryAbility extends UIAbility { onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { // 获取UIAbility实例的上下文 let context = this.context; // ... } } -
在页面中获取UIAbility实例的上下文信息，包括导入依赖资源context模块和在组件中定义一个context变量两个部分。
import { common, Want } from '@kit.AbilityKit'; @Entry @Component struct Page_EventHub { private context = getContext(this) as common.UIAbilityContext; startAbilityTest(): void { let want: Want = { // Want参数信息 }; this.context.startAbility(want); } // 页面展示 build() { // ... } }
UIAbility组件与UI的数据同步
使用EventHub进行数据通信
EventHub为UIAbility组件提供了事件机制，使它们能够进行订阅、取消订阅和触发事件等数据通信能力。
在基类Context中，提供了EventHub对象，可用于在UIAbility组件实例内通信。
-
在UIAbility中调用eventHub.on()方法注册一个自定义事件"event1"，eventHub.on()有如下两种调用方式，使用其中一种即可。
import { hilog } from '@kit.PerformanceAnalysisKit'; import { UIAbility, Context, Want, AbilityConstant } from '@kit.AbilityKit'; const DOMAIN_NUMBER: number = 0xFF00; const TAG: string = '[EventAbility]'; export default class EntryAbility extends UIAbility { onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { // 获取eventHub let eventhub = this.context.eventHub; // 执行订阅操作 eventhub.on('event1', this.eventFunc); eventhub.on('event1', (data: string) => { // 触发事件，完成相应的业务操作 }); hilog.info(DOMAIN_NUMBER, TAG, '%{public}s', 'Ability onCreate'); } // ... eventFunc(argOne: Context, argTwo: Context): void { hilog.info(DOMAIN_NUMBER, TAG, '1. ' + `${argOne}, ${argTwo}`); return; } } -
在UI中通过eventHub.emit()方法触发该事件，在触发事件的同时，根据需要传入参数信息。
import { common } from '@kit.AbilityKit'; import { promptAction } from '@kit.ArkUI'; @Entry @Component struct Page_EventHub { private context = getContext(this) as common.UIAbilityContext; eventHubFunc(): void { // 不带参数触发自定义"event1"事件 this.context.eventHub.emit('event1'); // 带1个参数触发自定义"event1"事件 this.context.eventHub.emit('event1', 1); // 带2个参数触发自定义"event1"事件 this.context.eventHub.emit('event1', 2, 'test'); // 开发者可以根据实际的业务场景设计事件传递的参数 } build() { Column() { // ... List({ initialIndex: 0 }) { ListItem() { Row() { // ... } .onClick(() => { this.eventHubFunc(); promptAction.showToast({ message: $r('app.string.EventHubFuncA') }); }) } // ... ListItem() { Row() { // ... } .onClick(() => { this.context.eventHub.off('event1'); promptAction.showToast({ message: $r('app.string.EventHubFuncB') }); }) } // ... } // ... } // ... } } -
在UIAbility的注册事件回调中可以得到对应的触发事件结果，运行日志结果如下所示。
[Example].[Entry].[EntryAbility] 1. [] [Example].[Entry].[EntryAbility] 1. [1] [Example].[Entry].[EntryAbility] 1. [2,"test"] -
在自定义事件"event1"使用完成后，可以根据需要调用eventHub.off()方法取消该事件的订阅。
import { UIAbility } from '@kit.AbilityKit'; export default class EntryAbility extends UIAbility { // ... onDestroy(): void { this.context.eventHub.off('event1'); } }
使用AppStorage/LocalStorage进行数据同步
ArkUI提供了AppStorage和LocalStorage两种应用级别的状态管理方案，可用于实现应用级别和UIAbility级别的数据同步。使用这些方案可以方便地管理应用状态，提高应用性能和用户体验。其中，AppStorage是一个全局的状态管理器，适用于多个UIAbility共享同一状态数据的情况；而LocalStorage则是一个局部的状态管理器，适用于单个UIAbility内部使用的状态数据。通过这两种方案，开发者可以更加灵活地控制应用状态，提高应用的可维护性和可扩展性。
UIAbility组件间交互（设备内）
启动应用内的UIAbility
- 在EntryAbility中，通过调用startAbility()方法启动UIAbility，want为UIAbility实例启动的入口参数，其中bundleName为待启动应用的Bundle名称，abilityName为待启动的Ability名称，moduleName在待启动的UIAbility属于不同的Module时添加，parameters为自定义信息参数。
- 在FuncAbility的onCreate()或者onNewWant()生命周期回调文件中接收EntryAbility传递过来的参数。
- 在FuncAbility业务完成之后，如需要停止当前UIAbility实例，在FuncAbility中通过调用terminateSelf()方法实现。
- 如需要关闭应用所有的UIAbility实例，可以调用ApplicationContext的killAllProcesses()方法实现关闭应用所有的进程。
调用terminateSelf()方法停止当前UIAbility实例时，默认会保留该实例的快照（Snapshot），即在最近任务列表中仍然能查看到该实例对应的任务。如不需要保留该实例的快照，可以在其对应UIAbility的module.json5配置文件中，将abilities标签的removeMissionAfterTerminate字段配置为true。
启动应用内的UIAbility并获取返回结果
在一个EntryAbility启动另外一个FuncAbility时，希望在被启动的FuncAbility完成相关业务后，能将结果返回给调用方。例如在应用中将入口功能和帐号登录功能分别设计为两个独立的UIAbility，在帐号登录UIAbility中完成登录操作后，需要将登录的结果返回给入口UIAbility。
-
在EntryAbility中，调用startAbilityForResult()接口启动FuncAbility，异步回调中的data用于接收FuncAbility停止自身后返回给EntryAbility的信息。
import { common, Want } from '@kit.AbilityKit'; import { hilog } from '@kit.PerformanceAnalysisKit'; import { promptAction } from '@kit.ArkUI'; import { BusinessError } from '@kit.BasicServicesKit'; const TAG: string = '[Page_UIAbilityComponentsInteractive]'; const DOMAIN_NUMBER: number = 0xFF00; @Entry @Component struct Page_UIAbilityComponentsInteractive { build() { Column() { //... List({ initialIndex: 0 }) { ListItem() { Row() { //... } .onClick(() => { let context: common.UIAbilityContext = getContext(this) as common.UIAbilityContext; // UIAbilityContext const RESULT_CODE: number = 1001; let want: Want = { deviceId: '', // deviceId为空表示本设备 bundleName: 'com.samples.stagemodelabilitydevelop', moduleName: 'entry', // moduleName非必选 abilityName: 'FuncAbilityA', parameters: { // 自定义信息 info: '来自EntryAbility UIAbilityComponentsInteractive页面' } }; context.startAbilityForResult(want).then((data) => { if (data?.resultCode === RESULT_CODE) { // 解析被调用方UIAbility返回的信息 let info = data.want?.parameters?.info; hilog.info(DOMAIN_NUMBER, TAG, JSON.stringify(info) ?? ''); if (info !== null) { promptAction.showToast({ message: JSON.stringify(info) }); } } hilog.info(DOMAIN_NUMBER, TAG, JSON.stringify(data.resultCode) ?? ''); }).catch((err: BusinessError) => { hilog.error(DOMAIN_NUMBER, TAG, `Failed to start ability for result. Code is ${err.code}, message is ${err.message}`); }); }) } //... } //... } //... } } -
在FuncAbility停止自身时，需要调用terminateSelfWithResult()方法，入参abilityResult为FuncAbility需要返回给EntryAbility的信息。
启动UIAbility的指定页面
一个UIAbility可以对应多个页面，在不同的场景下启动该UIAbility时需要展示不同的页面，例如从一个UIAbility的页面中跳转到另外一个UIAbility时，希望启动目标UIAbility的指定页面。
UIAbility的启动分为两种情况：UIAbility冷启动和UIAbility热启动。
- UIAbility冷启动：指的是UIAbility实例处于完全关闭状态下被启动，这需要完整地加载和初始化UIAbility实例的代码、资源等。
- UIAbility热启动：指的是UIAbility实例已经启动并在前台运行过，由于某些原因切换到后台，再次启动该UIAbility实例，这种情况下可以快速恢复UIAbility实例的状态。