1# @ohos.app.ability.UIExtensionAbility (带界面的ExtensionAbility组件) 2 3<!--Kit: Ability Kit--> 4<!--Subsystem: Ability--> 5<!--Owner: @zhangyafei-echo; @xuzhihao666--> 6<!--Designer: @zhangyafei-echo--> 7<!--Tester: @lixueqing513--> 8<!--Adviser: @huipeizi--> 9 10 11UIExtensionAbility组件是带界面的ExtensionAbility组件，继承自[ExtensionAbility](js-apis-app-ability-extensionAbility.md)，提供了组件创建、销毁、前后台切换等基础生命周期。和UIAbility组件不同，UIExtensionAbility组件不会作为单独的任务在任务视图中体现。UIExtensionAbility组件被宿主窗口启动，该组件的前后台切换状态、以及是否可见均跟随宿主窗口。 12 13开发者不可以直接继承UIExtensionAbility组件，但可以根据实际业务场景选择使用继承自UIExtensionAbility组件的其他组件。例如，开发者处理其他应用分享的数据时，可以使用[ShareExtensionAbility组件](./js-apis-app-ability-shareExtensionAbility.md)；开发者提供卡片编辑功能时，可以使用[FormEditExtensionAbility组件](../apis-form-kit/js-apis-app-form-formEditExtensionAbility.md)。 14 15各类Ability组件的继承关系详见[继承关系说明](./js-apis-app-ability-ability.md#ability的继承关系说明)。 16 17> **说明：** 18> 19> 本模块首批接口从API version 10 开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 20> 21> 本模块接口仅可在Stage模型下使用。 22 23## 导入模块 24 25```ts 26import { UIExtensionAbility } from '@kit.AbilityKit'; 27``` 28 29## UIExtensionAbility 30 31表示包含UI界面的扩展组件，提供组件创建、销毁、前后台切换等生命周期回调。 32 33### 属性 34 35**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 36 37| 名称 | 类型 | 只读 | 可选 | 说明 | 38| -------- | -------- | -------- | -------- | -------- | 39| context | [UIExtensionContext](js-apis-inner-application-uiExtensionContext.md) | 否 | 否 | UIExtensionAbility组件的上下文。 | 40 41### onCreate 42 43onCreate(launchParam: AbilityConstant.LaunchParam): void 44 45当UIExtensionAbility组件实例完成创建时，系统会触发该回调。开发者可在该回调中执行初始化逻辑（如定义变量、加载资源等）。 46 47**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 48 49**参数：** 50 51| 参数名 | 类型 | 必填 | 说明 | 52| -------- | -------- | -------- | -------- | 53| launchParam<sup>12+</sup> | [AbilityConstant.LaunchParam](js-apis-app-ability-abilityConstant.md#launchparam) | 是 | 应用启动参数，包含应用启动原因、应用上次退出原因等。 | 54 55**示例：** 56 57```ts 58// UIExtensionAbility组件不支持三方应用直接继承，故以派生类ShareExtensionAbility举例说明。 59import { ShareExtensionAbility, AbilityConstant } from '@kit.AbilityKit'; 60 61const TAG: string = '[testTag] ShareExtAbility'; 62 63export default class ShareExtAbility extends ShareExtensionAbility { 64 onCreate(launchParam: AbilityConstant.LaunchParam) { 65 console.info(TAG, `onCreate, launchParam: ${JSON.stringify(launchParam)}`); 66 } 67} 68``` 69 70### onSessionCreate 71 72onSessionCreate(want: Want, session: UIExtensionContentSession): void 73 74当[UIExtensionContentSession](js-apis-app-ability-uiExtensionContentSession.md)实例创建完成后，系统会触发该回调。开发者可在该回调中通过UIExtensionContentSession实例加载页面。 75 76**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 77 78**参数：** 79 80| 参数名 | 类型 | 必填 | 说明 | 81| -------- | -------- | -------- | -------- | 82| want | [Want](js-apis-app-ability-want.md) | 是 | 调用方拉起该UIExtensionAbility组件时传递的数据。 | 83| session | [UIExtensionContentSession](js-apis-app-ability-uiExtensionContentSession.md) | 是 | UIExtensionContentSession实例对象。 | 84 85**示例：** 86 87```ts 88// UIExtensionAbility组件不支持三方应用直接继承，故以派生类ShareExtensionAbility举例说明。 89import { ShareExtensionAbility, UIExtensionContentSession, Want } from '@kit.AbilityKit'; 90import { BusinessError } from '@kit.BasicServicesKit'; 91 92const TAG: string = '[testTag] ShareExtAbility'; 93 94export default class ShareExtAbility extends ShareExtensionAbility { 95 onSessionCreate(want: Want, session: UIExtensionContentSession) { 96 console.info(TAG, `onSessionCreate, want: ${JSON.stringify(want)}`); 97 try { 98 session.loadContent('pages/Index'); 99 } catch (error) { 100 let code = (error as BusinessError).code; 101 let message = (error as BusinessError).message; 102 console.error(`Failed to load content, code: ${code}, msg: ${message}`); 103 } 104 } 105} 106``` 107 108### onSessionDestroy 109 110onSessionDestroy(session: UIExtensionContentSession): void 111 112当UIExtensionContentSession实例销毁后，系统触发该回调。该回调用于通知开发者UIExtensionContentSession实例已被销毁，不能再继续使用。 113 114**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 115 116**参数：** 117 118| 参数名 | 类型 | 必填 | 说明 | 119| -------- | -------- | -------- | -------- | 120| session | [UIExtensionContentSession](js-apis-app-ability-uiExtensionContentSession.md) | 是 | UIExtensionContentSession实例对象。 | 121 122**示例：** 123 124```ts 125// UIExtensionAbility组件不支持三方应用直接继承，故以派生类ShareExtensionAbility举例说明。 126import { ShareExtensionAbility, UIExtensionContentSession } from '@kit.AbilityKit'; 127 128const TAG: string = '[testTag] ShareExtAbility'; 129 130export default class ShareExtAbility extends ShareExtensionAbility { 131 onSessionDestroy(session: UIExtensionContentSession) { 132 console.info(TAG, `onSessionDestroy`); 133 } 134} 135``` 136 137### onForeground 138 139onForeground(): void 140 141当UIExtensionAbility组件首次启动到前台或者从后台转入到前台时，系统触发该回调。开发者可在该回调中实现UI可见时的资源申请操作。 142 143**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 144 145**示例：** 146 147```ts 148// UIExtensionAbility组件不支持三方应用直接继承，故以派生类ShareExtensionAbility举例说明。 149import { ShareExtensionAbility } from '@kit.AbilityKit'; 150 151const TAG: string = '[testTag] ShareExtAbility'; 152 153export default class ShareExtAbility extends ShareExtensionAbility { 154 onForeground() { 155 console.info(TAG, `onForeground`); 156 } 157} 158``` 159 160### onBackground 161 162onBackground(): void 163 164当UIExtensionAbility组件从前台转入到后台时，系统触发该回调。开发者可在该回调中实现UI不可见时的资源释放操作。 165 166**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 167 168**示例：** 169 170```ts 171// UIExtensionAbility组件不支持三方应用直接继承，故以派生类ShareExtensionAbility举例说明。 172import { ShareExtensionAbility } from '@kit.AbilityKit'; 173 174const TAG: string = '[testTag] ShareExtAbility'; 175 176export default class ShareExtAbility extends ShareExtensionAbility { 177 onBackground() { 178 console.info(TAG, `onBackground`); 179 } 180} 181``` 182 183### onDestroy 184 185onDestroy(): void | Promise<void> 186 187当UIExtensionAbility组件被销毁时，系统触发该回调。开发者可以在该生命周期中执行资源清理、数据保存等相关操作。使用同步回调或Promise异步回调。 188 189在执行完onDestroy生命周期回调后，应用可能会退出，从而可能导致onDestroy中的异步函数未能正确执行，比如异步写入数据库。推荐使用Promise异步回调，避免因应用退出导致onDestroy中的异步函数（比如异步写入数据库）未能正确执行。 190 191**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 192 193**返回值：** 194 195| 类型 | 说明 | 196| ----------------- | ------------------------------------------------------------ | 197| void \| Promise\<void> | 无返回结果或无返回结果的Promise对象。 | 198 199**示例：** 200 201- 同步回调示例如下： 202 ```ts 203 // UIExtensionAbility组件不支持三方应用直接继承，故以派生类ShareExtensionAbility举例说明。 204 import { ShareExtensionAbility } from '@kit.AbilityKit'; 205 206 const TAG: string = '[testTag] ShareExtAbility'; 207 208 export default class ShareExtAbility extends ShareExtensionAbility { 209 onDestroy() { 210 console.info(TAG, `onDestroy`); 211 } 212 } 213 ``` 214 215- 异步回调示例如下： 216 ```ts 217 // UIExtensionAbility组件不支持三方应用直接继承，故以派生类ShareExtensionAbility举例说明。 218 import { ShareExtensionAbility } from '@kit.AbilityKit'; 219 220 const TAG: string = '[testTag] ShareExtAbility'; 221 222 export default class ShareExtAbility extends ShareExtensionAbility { 223 // 实现异步回调需要使用async/await语法糖，通过async声明onDestroy是一个异步函数。 224 async onDestroy(): Promise<void> { 225 console.info(TAG, `onDestroy begin`); 226 try { 227 const result: string = await new Promise((resolve: Function) => { 228 setTimeout(() => { 229 resolve('Hello, world!'); 230 }, 3000); 231 }); 232 console.info(TAG, result); // result is 'Hello, world!' 233 } catch (e) { 234 console.error(TAG, `Get exception: ${e}`); 235 } 236 console.info(TAG, `onDestroy end`); 237 } 238 } 239 ```