1# @ohos.app.ability.UIAbility (带界面的应用组件) 2 3<!--Kit: Ability Kit--> 4<!--Subsystem: Ability--> 5<!--Owner: @littlejerry1; @Luobniz21--> 6<!--Designer: @ccllee1--> 7<!--Tester: @lixueqing513--> 8<!--Adviser: @huipeizi--> 9 10UIAbility是包含UI界面的应用组件，继承自[Ability](js-apis-app-ability-ability.md)，提供UIAbility组件创建、销毁、前后台切换等[生命周期](#uiability生命周期状态)回调，同时也具备[后台通信能力](#后台通信能力)。 11 12> **说明：** 13> 14> 本模块首批接口从API version 9 开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 15> 16> 本模块接口仅可在Stage模型下使用。 17 18各类Ability的继承关系详见[继承关系说明](./js-apis-app-ability-ability.md#ability的继承关系说明)。 19 20## UIAbility生命周期状态 21 22**图1** UIAbility生命周期状态 23 24 25 26- Create：表示UIAbility实例已创建。系统会在该状态下触发其[onCreate](#oncreate)回调函数，开发者可以在[onCreate](#oncreate)中执行初始化操作。 27- Foreground：表示UIAbility被拉到前台。系统会在该状态下触发其[onForeground](#onforeground)回调函数，开发者可以在[onForeground](#onforeground)中申请应用所需的资源。 28- Background：表示UIAbility被拉到后台。系统会在该状态下触发其[onBackground](#onbackground)回调函数，开发者可以在[onBackground](#onbackground)中释放一些应用资源。 29- Destroy：表示UIAbility实例要销毁。系统会在该状态下触发其[onDestroy](#ondestroy)回调函数，开发者可以在[onDestroy](#ondestroy)中执行数据保存等操作。 30 31## 后台通信能力 32 33通过Call调用可以与目标UIAbility进行后台通信。Call调用示意图如下所示。 34 35 36**图2** Call调用示意图 37 38 39 40- Caller UIAbility调用[startAbilityByCall()](js-apis-inner-application-uiAbilityContext.md#startabilitybycall)接口获取[Caller](#caller)对象，并使用Caller对象的[call](#call)方法向Callee UIAbility发送数据。 41 42- Callee UIAbility持有一个[Callee](#callee)对象，通过Callee的[on](#on)方法注册回调函数，用于接收Caller对象发送的数据。 43 44## 导入模块 45 46```ts 47import { UIAbility } from '@kit.AbilityKit'; 48``` 49 50## UIAbility 51 52表示包含UI界面的应用组件，提供组件创建、销毁、前后台切换等生命周期回调，同时也具备组件协同的能力。 53 54### 属性 55 56**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 57 58| 名称 | 类型 | 只读 | 可选 | 说明 | 59| -------- | -------- | -------- | -------- | -------- | 60| context | [UIAbilityContext](js-apis-inner-application-uiAbilityContext.md) | 否 | 否 | UIAbility的上下文。<br>**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 | 61| launchWant | [Want](js-apis-app-ability-want.md) | 否 | 否 | UIAbility冷启动时接收到的Want参数，取值为[onCreate](#oncreate)接收到的Want参数。<br>**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 | 62| lastRequestWant | [Want](js-apis-app-ability-want.md) | 否 | 否 | 最近一次拉起UIAbility请求的Want参数。<br>- 首次拉起UIAbility时，取值为[onCreate](#oncreate)接收到的Want参数。<br>- 重复拉起UIAbility时，取值为[onNewWant](#onnewwant)最近一次接收到的Want参数。<br>**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。| 63| callee | [Callee](#callee) | 否 | 否 | 系统为UIAbility创建的后台通信对象，Callee UIAbility（被调用方），可以通过Callee对象接收Caller对象发送的数据进。 | 64 65 66### onCreate 67 68onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void 69 70当UIAbility实例完成创建时，系统会触发该回调，开发者可在该回调中执行初始化逻辑（如定义变量、加载资源等）。该回调仅会在UIAbility[冷启动](../../application-models/uiability-intra-device-interaction.md#目标uiability冷启动)时触发。 71 72同步接口，不支持异步回调。 73 74**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 75 76**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 77 78**参数：** 79 80| 参数名 | 类型 | 必填 | 说明 | 81| -------- | -------- | -------- | -------- | 82| want | [Want](js-apis-app-ability-want.md) | 是 | 调用方拉起该UIAbility时传递的数据。 | 83| launchParam | [AbilityConstant.LaunchParam](js-apis-app-ability-abilityConstant.md#launchparam) | 是 | 应用启动参数，包含应用启动原因、应用上次退出原因等。 | 84 85**示例：** 86 87 88```ts 89import { UIAbility, AbilityConstant, Want } from '@kit.AbilityKit'; 90import { hilog } from '@kit.PerformanceAnalysisKit'; 91 92export default class MyUIAbility extends UIAbility { 93 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 94 // 执行异步任务 95 hilog.info(0x0000, 'testTag', `onCreate, want: ${want.abilityName}, the launchReason is ${launchParam.launchReason}, the lastExitReason is ${launchParam.lastExitReason}`); 96 } 97} 98``` 99 100 101### onWindowStageCreate 102 103onWindowStageCreate(windowStage: window.WindowStage): void 104 105当WindowStage实例创建完成后，系统会触发该回调。开发者可以在该回调中通过WindowStage加载页面。 106 107**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 108 109**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 110 111**参数：** 112 113| 参数名 | 类型 | 必填 | 说明 | 114| -------- | -------- | -------- | -------- | 115| windowStage | [window.WindowStage](../apis-arkui/arkts-apis-window-WindowStage.md) | 是 | WindowStage实例对象。 | 116 117**示例：** 118 119```ts 120import { UIAbility } from '@kit.AbilityKit'; 121import { hilog } from '@kit.PerformanceAnalysisKit'; 122import { window } from '@kit.ArkUI'; 123 124export default class MyUIAbility extends UIAbility { 125 // 主窗口已创建，为该UIAbility设置主页面 126 onWindowStageCreate(windowStage: window.WindowStage): void { 127 windowStage.loadContent('pages/Index', (err, data) => { 128 if (err.code) { 129 hilog.error(0x0000, 'testTag', `Failed to load the content. Cause: ${JSON.stringify(err)}`); 130 return; 131 } 132 hilog.info(0x0000, 'testTag', `Succeeded in loading the content. Data: ${JSON.stringify(data)}`); 133 }); 134 } 135} 136``` 137 138 139### onWindowStageWillDestroy<sup>12+</sup> 140 141onWindowStageWillDestroy(windowStage: window.WindowStage): void 142 143当WindowStage即将销毁时，系统触发该回调。开发者可以在该生命周期中取消windowStage事件的监听。 144 145**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 146 147**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 148 149**参数：** 150 151| 参数名 | 类型 | 必填 | 说明 | 152| -------- | -------- | -------- | -------- | 153| windowStage | [window.WindowStage](../apis-arkui/arkts-apis-window-WindowStage.md) | 是 | WindowStage实例对象。 | 154 155**示例：** 156 157```ts 158import { UIAbility } from '@kit.AbilityKit'; 159import { hilog } from '@kit.PerformanceAnalysisKit'; 160import { window } from '@kit.ArkUI'; 161 162export default class MyUIAbility extends UIAbility { 163 onWindowStageWillDestroy(windowStage: window.WindowStage) { 164 hilog.info(0x0000, 'testTag', `onWindowStageWillDestroy`); 165 } 166} 167``` 168 169 170### onWindowStageDestroy 171 172onWindowStageDestroy(): void 173 174当WindowStage销毁后，系统触发该回调。该回调用于通知开发者WindowStage对象已被销毁，不能再继续使用。 175 176仅当UIAbility正常退出时会触发该回调，异常退出场景（例如低内存查杀）不会触发该回调。 177 178**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 179 180**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 181 182**示例：** 183 184```ts 185import { UIAbility } from '@kit.AbilityKit'; 186import { hilog } from '@kit.PerformanceAnalysisKit'; 187 188export default class MyUIAbility extends UIAbility { 189 onWindowStageDestroy() { 190 // 主窗口已销毁，释放UI相关资源 191 hilog.info(0x0000, 'testTag', `onWindowStageDestroy`); 192 } 193} 194``` 195 196 197### onWindowStageRestore 198 199onWindowStageRestore(windowStage: window.WindowStage): void 200 201当UIAbility跨端迁移时，目标端UIAbility恢复页面栈时回调。 202 203> **说明：** 204> 205> 在应用迁移启动时，无论是冷启动还是热启动，都会在执行完[onCreate()](#oncreate)/[onNewWant()](#onnewwant)后，触发onWindowStageRestore()生命周期函数，不执行onWindowStageCreate()生命周期函数。 206 207 208**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 209 210**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 211 212**参数：** 213 214| 参数名 | 类型 | 必填 | 说明 | 215| -------- | -------- | -------- | -------- | 216| windowStage | [window.WindowStage](../apis-arkui/arkts-apis-window-WindowStage.md) | 是 | WindowStage实例对象。 | 217 218**示例：** 219 220```ts 221import { UIAbility } from '@kit.AbilityKit'; 222import { hilog } from '@kit.PerformanceAnalysisKit'; 223import { window } from '@kit.ArkUI'; 224 225export default class MyUIAbility extends UIAbility { 226 onWindowStageRestore(windowStage: window.WindowStage) { 227 hilog.info(0x0000, 'testTag', `onWindowStageRestore`); 228 } 229} 230``` 231 232 233### onDestroy 234 235onDestroy(): void | Promise<void> 236 237当UIAbility被销毁（例如使用[terminateSelf](js-apis-inner-application-uiAbilityContext.md#terminateself)接口停止UIAbility）时，系统触发该回调。开发者可以在该生命周期中执行资源清理、数据保存等相关操作。使用同步回调或Promise异步回调。 238 239在执行完onDestroy生命周期回调后，应用可能会退出，从而可能导致onDestroy中的异步函数未能正确执行，比如异步写入数据库。推荐使用Promise异步回调，避免因应用退出导致onDestroy中的异步函数（比如异步写入数据库）未能正确执行。 240 241仅当UIAbility正常退出时会触发该回调，异常退出场景（例如低内存查杀）不会触发该回调。 242 243**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 244 245**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 246 247**返回值：** 248 249| 类型 | 说明 | 250| -------- | -------- | 251| void \| Promise<void> | 无返回结果或无返回结果的Promise对象。 | 252 253**示例：** 254 255- 同步回调示例如下： 256 257 ```ts 258 import { UIAbility } from '@kit.AbilityKit'; 259 import { hilog } from '@kit.PerformanceAnalysisKit'; 260 261 export default class MyUIAbility extends UIAbility { 262 onDestroy() { 263 hilog.info(0x0000, 'testTag', `onDestroy`); 264 // 调用同步函数... 265 } 266 } 267 ``` 268 269- Promise异步回调示例如下： 270 271 ```ts 272 import { UIAbility } from '@kit.AbilityKit'; 273 import { hilog } from '@kit.PerformanceAnalysisKit'; 274 275 export default class MyUIAbility extends UIAbility { 276 async onDestroy() { 277 hilog.info(0x0000, 'testTag', `onDestroy`); 278 // 调用异步函数... 279 } 280 } 281 ``` 282 283 284### onWillForeground<sup>20+</sup> 285 286onWillForeground(): void 287 288UIAbility生命周期回调，应用转到前台前触发，在[onForeground](#onforeground)前被调用。可在该回调中实现采集应用开始进入前台的时间。如果与[onDidForeground](#ondidforeground20)配合使用，还可以统计出从应用开始进入前台到切换至前台状态的耗时。 289 290同步接口，不支持异步回调。 291 292**原子化服务API**：从API version 20开始，该接口支持在原子化服务中使用。 293 294**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 295 296**示例：** 297 298```ts 299import { UIAbility } from '@kit.AbilityKit'; 300import { hiAppEvent, hilog } from '@kit.PerformanceAnalysisKit'; 301import { BusinessError } from '@kit.BasicServicesKit'; 302 303export default class EntryAbility extends UIAbility { 304 // ... 305 306 onWillForeground(): void { 307 // 应用开始进入前台事件打点 308 let eventParams: Record<string, number> = { 'xxxx': 100 }; 309 let eventInfo: hiAppEvent.AppEventInfo = { 310 // 事件领域定义 311 domain: "lifecycle", 312 // 事件名称定义 313 name: "onwillforeground", 314 // 事件类型定义 315 eventType: hiAppEvent.EventType.BEHAVIOR, 316 // 事件参数定义 317 params: eventParams, 318 }; 319 hiAppEvent.write(eventInfo).then(() => { 320 hilog.info(0x0000, 'testTag', `HiAppEvent success to write event`); 321 }).catch((err: BusinessError) => { 322 hilog.error(0x0000, 'testTag', `HiAppEvent err.code: ${err.code}, err.message: ${err.message}`); 323 }); 324 } 325 // ... 326 327 onDidForeground(): void { 328 // 应用进入前台后事件打点 329 let eventParams: Record<string, number> = { 'xxxx': 100 }; 330 let eventInfo: hiAppEvent.AppEventInfo = { 331 // 事件领域定义 332 domain: "lifecycle", 333 // 事件名称定义 334 name: "ondidforeground", 335 // 事件类型定义 336 eventType: hiAppEvent.EventType.BEHAVIOR, 337 // 事件参数定义 338 params: eventParams, 339 }; 340 hiAppEvent.write(eventInfo).then(() => { 341 hilog.info(0x0000, 'testTag', `HiAppEvent success to write event`); 342 }).catch((err: BusinessError) => { 343 hilog.error(0x0000, 'testTag', `HiAppEvent err.code: ${err.code}, err.message: ${err.message}`); 344 }); 345 } 346} 347``` 348 349 350### onForeground 351 352onForeground(): void 353 354当应用首次启动到前台或者从后台转入到前台时，系统触发该回调。开发者可在该回调中实现系统所需资源的申请，如应用转到前台时申请定位服务等。 355 356同步接口，不支持异步回调。 357 358**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 359 360**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 361 362**示例：** 363 364 365```ts 366import { UIAbility } from '@kit.AbilityKit'; 367import { hilog } from '@kit.PerformanceAnalysisKit'; 368 369export default class MyUIAbility extends UIAbility { 370 onForeground() { 371 // 执行异步任务 372 hilog.info(0x0000, 'testTag', `onForeground`); 373 } 374} 375``` 376 377 378### onDidForeground<sup>20+</sup> 379 380onDidForeground(): void 381 382UIAbility生命周期回调，应用转到前台后触发，在[onForeground](#onforeground)后被调用，可在该回调中实现应用切换到前台后的时间打点。如果与[onWillForeground](#onwillforeground20)配合使用，还可以统计出从应用开始进入前台到切换至前台状态的耗时。 383 384同步接口，不支持异步回调。 385 386**原子化服务API**：从API version 20开始，该接口支持在原子化服务中使用。 387 388**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 389 390**示例：** 391 392参考[onWillForeground](#onwillforeground20)。 393 394 395### onWillBackground<sup>20+</sup> 396 397onWillBackground(): void 398 399UIAbility生命周期回调，当应用从前台转到后台前触发，在[onBackground](#onbackground)前被调用。可在该回调中实现数据打点，例如，打点应用运行过程中发生的故障信息、统计信息、安全信息、用户行为信息等。 400 401同步接口，不支持异步回调。 402 403**原子化服务API**：从API version 20开始，该接口支持在原子化服务中使用。 404 405**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 406 407**示例：** 408 409```ts 410import { UIAbility } from '@kit.AbilityKit'; 411import { hiAppEvent, hilog } from '@kit.PerformanceAnalysisKit'; 412import { BusinessError } from '@kit.BasicServicesKit'; 413 414export default class MyUIAbility extends UIAbility { 415 onWillBackground(): void { 416 let eventParams: Record<string, number | string> = { 417 "int_data": 100, 418 "str_data": "strValue", 419 }; 420 // 打点应用故障信息 421 hiAppEvent.write({ 422 domain: "test_domain", 423 name: "test_event", 424 eventType: hiAppEvent.EventType.FAULT, 425 params: eventParams, 426 }, (err: BusinessError) => { 427 if (err) { 428 hilog.error(0x0000, 'testTag', `hiAppEvent code: ${err.code}, message: ${err.message}`); 429 return; 430 } 431 hilog.info(0x0000, 'testTag', `hiAppEvent success to write event`); 432 }); 433 } 434} 435``` 436 437 438### onBackground 439 440onBackground(): void 441 442当应用从前台转入到后台时，系统触发该回调。开发者可在该回调中实现UI不可见时的资源释放操作，如停止定位功能等。 443 444同步接口，不支持异步回调。 445 446**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 447 448**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 449 450**示例：** 451 452```ts 453import { UIAbility } from '@kit.AbilityKit'; 454import { hilog } from '@kit.PerformanceAnalysisKit'; 455 456export default class MyUIAbility extends UIAbility { 457 onBackground() { 458 // UIAbility回到后台 459 hilog.info(0x0000, 'testTag', `onBackground`); 460 } 461} 462``` 463 464 465### onDidBackground<sup>20+</sup> 466 467onDidBackground(): void 468 469UIAbility生命周期回调，当应用从前台转到后台后触发，在[onBackground](#onbackground)之后被调用。可在该回调中实现应用进入后台之后的资源释放操作，如进入后台后停止音频播放等。 470 471同步接口，不支持异步回调。 472 473**原子化服务API**：从API version 20开始，该接口支持在原子化服务中使用。 474 475**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 476 477**示例：** 478 479```ts 480import { UIAbility } from '@kit.AbilityKit'; 481import { BusinessError } from '@kit.BasicServicesKit'; 482import { hilog } from '@kit.PerformanceAnalysisKit'; 483import { audio } from '@kit.AudioKit'; 484 485export default class MyUIAbility extends UIAbility { 486 static audioRenderer: audio.AudioRenderer; 487 // ... 488 onForeground(): void { 489 let audioStreamInfo: audio.AudioStreamInfo = { 490 samplingRate: audio.AudioSamplingRate.SAMPLE_RATE_48000, // 采样率。 491 channels: audio.AudioChannel.CHANNEL_2, // 通道。 492 sampleFormat: audio.AudioSampleFormat.SAMPLE_FORMAT_S16LE, // 采样格式。 493 encodingType: audio.AudioEncodingType.ENCODING_TYPE_RAW // 编码格式。 494 }; 495 496 let audioRendererInfo: audio.AudioRendererInfo = { 497 usage: audio.StreamUsage.STREAM_USAGE_MUSIC, // 音频流使用类型：音乐。根据业务场景配置，参考StreamUsage。 498 rendererFlags: 0 // 音频渲染器标志。 499 }; 500 501 let audioRendererOptions: audio.AudioRendererOptions = { 502 streamInfo: audioStreamInfo, 503 rendererInfo: audioRendererInfo 504 }; 505 506 // 在前台时申请audioRenderer，用于播放PCM（Pulse Code Modulation）音频数据 507 audio.createAudioRenderer(audioRendererOptions).then((data) => { 508 MyUIAbility.audioRenderer = data; 509 hilog.info(0x0000, 'testTag', `AudioRenderer Created : Success : Stream Type: SUCCESS.`); 510 }).catch((err: BusinessError) => { 511 hilog.error(0x0000, 'testTag', `AudioRenderer Created : F : ${JSON.stringify(err)}.`); 512 }); 513 } 514 515 onDidBackground() { 516 // 转到后台后，释放audioRenderer资源 517 MyUIAbility.audioRenderer.release((err: BusinessError) => { 518 if (err) { 519 hilog.error(0x0000, 'testTag', `AudioRenderer release failed, error: ${JSON.stringify(err)}.`); 520 } else { 521 hilog.info(0x0000, 'testTag', `AudioRenderer released.`); 522 } 523 }); 524 } 525} 526``` 527 528### onContinue 529 530onContinue(wantParam: Record<string, Object>): AbilityConstant.OnContinueResult | Promise<AbilityConstant.OnContinueResult> 531 532当Ability准备迁移时触发，保存数据。 533 534> **说明：** 535> 536> 从API version 12 开始，UIAbility.onContinue生命周期新增支持返回值为Promise\<[AbilityConstant.OnContinueResult](js-apis-app-ability-abilityConstant.md#oncontinueresult)\>形式。 537 538**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 539 540**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 541 542**参数：** 543 544| 参数名 | 类型 | 必填 | 说明 | 545| -------- | -------- | -------- | -------- | 546| wantParam | Record<string, Object> | 是 | 开发者通过该参数保存待迁移的数据。 | 547 548**返回值：** 549 550| 类型 | 说明 | 551| -------- | -------- | 552| [AbilityConstant.OnContinueResult](js-apis-app-ability-abilityConstant.md#oncontinueresult) \| Promise<[AbilityConstant.OnContinueResult](js-apis-app-ability-abilityConstant.md#oncontinueresult)> | 表示是否同意迁移的结果：<br>- AGREE：表示同意。<br>- REJECT：表示拒绝，如应用在onContinue中异常可以返回REJECT。<br>- MISMATCH：表示版本不匹配，接续源端应用可以在onContinue中获取到迁移对端应用的版本号，进行协商后，如果版本不匹配导致无法迁移，可以返回该结果。<br> 该回调与onWindowStageRestore成对出现。在接续场景下，源端的UIAbility触发onContinue保存自定义数据，在目标端UIAbility触发onWindowStageRestore恢复自定义数据。 | 553 554**示例：** 555 556- 应用迁移时使用同步接口进行数据保存，示例如下： 557 558 ```ts 559 import { UIAbility, AbilityConstant } from '@kit.AbilityKit'; 560 561 export default class MyUIAbility extends UIAbility { 562 onContinue(wantParams: Record<string, Object>) { 563 console.info('onContinue'); 564 wantParams['myData'] = 'my1234567'; 565 return AbilityConstant.OnContinueResult.AGREE; 566 } 567 } 568 ``` 569 570- 应用迁移时使用异步接口进行数据保存，示例如下： 571 572 ```ts 573 import { UIAbility, AbilityConstant } from '@kit.AbilityKit'; 574 575 export default class MyUIAbility extends UIAbility { 576 async setWant(wantParams: Record<string, Object>) { 577 console.info('setWant start'); 578 for (let time = 0; time < 1000; ++time) { 579 wantParams[time] = time; 580 } 581 console.info('setWant end'); 582 } 583 584 async onContinue(wantParams: Record<string, Object>) { 585 console.info('onContinue'); 586 return this.setWant(wantParams).then(() => { 587 return AbilityConstant.OnContinueResult.AGREE; 588 }); 589 } 590 } 591 ``` 592 593 594### onNewWant 595 596onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): void 597 598当已在前台运行过的UIAbility实例被再次拉起时，会触发该生命周期回调。若在特定场景下（参见[Scenarios](./js-apis-app-ability-contextConstant.md#scenarios20)），不需要触发该生命周期回调，可以使用[setOnNewWantSkipScenarios](./js-apis-inner-application-uiAbilityContext.md#setonnewwantskipscenarios20)接口设置。 599 600 601**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 602 603**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 604 605**参数：** 606 607| 参数名 | 类型 | 必填 | 说明 | 608| -------- | -------- | -------- | -------- | 609| want | [Want](js-apis-app-ability-want.md) | 是 | 调用方再次拉起该UIAbility时传递的数据。 | 610| launchParam | [AbilityConstant.LaunchParam](js-apis-app-ability-abilityConstant.md#launchparam) | 是 | UIAbility启动的原因。 | 611 612**示例：** 613 614```ts 615import { UIAbility, AbilityConstant, Want } from '@kit.AbilityKit'; 616 617export default class MyUIAbility extends UIAbility { 618 onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam) { 619 console.info(`onNewWant, want: ${want.abilityName}`); 620 console.info(`onNewWant, launchParam: ${JSON.stringify(launchParam)}`); 621 } 622} 623``` 624 625### onDump 626 627onDump(params: Array\<string>): Array\<string> 628 629应用调测场景下，通过命令行dump UIAbility转储UIAbility数据时回调。开发者可以在该回调中返回UIAbility要dump出的非敏感信息。 630 631**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 632 633**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 634 635**参数：** 636 637| 参数名 | 类型 | 必填 | 说明 | 638| -------- | -------- | -------- | -------- | 639| params | Array\<string> | 是 | 表示dump命令参数。| 640 641**返回值：** 642 643| 类型 | 说明 | 644| -------- | -------- | 645| Array\<string> | 返回的dump信息。| 646 647**示例：** 648 649```ts 650import { UIAbility } from '@kit.AbilityKit'; 651 652export default class MyUIAbility extends UIAbility { 653 onDump(params: Array<string>) { 654 console.info(`dump, params: ${JSON.stringify(params)}`); 655 return ['params']; 656 } 657} 658``` 659 660 661### onSaveState 662 663onSaveState(reason: AbilityConstant.StateType, wantParam: Record<string, Object>): AbilityConstant.OnSaveResult 664 665该API配合[appRecovery](js-apis-app-ability-appRecovery.md)使用。当应用出现故障时，如果已启用自动保存状态，框架将调用onSaveState来保存UIAbility的状态。 666 667如果应用已使能故障恢复功能（即[enableAppRecovery](js-apis-app-ability-appRecovery.md#apprecoveryenableapprecovery)接口中saveOccasion参数配置为SAVE_WHEN_ERROR），当应用出现故障时，将触发该回调来保存UIAbility的数据。 668 669> **说明：** 670> 671> 从API version 20开始，当[UIAbility.onSaveStateAsync](#onsavestateasync20)实现时，本回调函数将不执行。 672 673**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 674 675**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 676 677**参数：** 678 679| 参数名 | 类型 | 必填 | 说明 | 680| -------- | -------- | -------- | -------- | 681| reason | [AbilityConstant.StateType](js-apis-app-ability-abilityConstant.md#statetype) | 是 | 触发应用保存状态的原因，当前仅支持APP_RECOVERY（即应用故障恢复场景）。 | 682| wantParam | Record<string, Object> | 是 | 用户自定义的应用状态数据，应用再启动时被保存在onCreate中的Want.parameters中。 | 683 684**返回值：** 685 686| 类型 | 说明 | 687| -------- | -------- | 688| [AbilityConstant.OnSaveResult](js-apis-app-ability-abilityConstant.md#onsaveresult) | 返回一个数据保存策略的对象（如全部拒绝、全部允许、只允许故障恢复场景等）。 | 689 690**示例：** 691 692```ts 693import { UIAbility, AbilityConstant } from '@kit.AbilityKit'; 694 695export default class MyUIAbility extends UIAbility { 696 onSaveState(reason: AbilityConstant.StateType, wantParam: Record<string, Object>) { 697 console.info('onSaveState'); 698 wantParam['myData'] = 'my1234567'; 699 return AbilityConstant.OnSaveResult.RECOVERY_AGREE; 700 } 701} 702``` 703 704### onSaveStateAsync<sup>20+</sup> 705 706onSaveStateAsync(stateType: AbilityConstant.StateType, wantParam: Record<string, Object>): Promise\<AbilityConstant.OnSaveResult> 707 708如果应用已使能故障恢复功能（即[enableAppRecovery](js-apis-app-ability-appRecovery.md#apprecoveryenableapprecovery)接口中的saveOccasion参数设置为SAVE_WHEN_ERROR），当应用出现故障时，将触发该回调来保存UIAbility的数据。使用Promise异步回调。 709 710**原子化服务API**：从API version 20开始，该接口支持在原子化服务中使用。 711 712**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 713 714**参数：** 715 716| 参数名 | 类型 | 必填 | 说明 | 717| -------- | -------- | -------- | -------- | 718| stateType | [AbilityConstant.StateType](js-apis-app-ability-abilityConstant.md#statetype) | 是 | 触发应用保存状态的原因，当前仅支持`APP_RECOVERY`（即应用故障恢复场景）。 | 719| wantParam | Record<string, Object> | 是 | 用户自定义的应用状态数据，应用再启动时被保存在Want.parameters中。 | 720 721**返回值：** 722 723| 类型 | 说明 | 724| -------- | -------- | 725| Promise\<[AbilityConstant.OnSaveResult](js-apis-app-ability-abilityConstant.md#onsaveresult)> | Promise对象。返回一个数据保存策略的对象（如全部拒绝、全部允许、只允许故障恢复场景等）。 | 726 727**示例：** 728 729```ts 730import { UIAbility, AbilityConstant } from '@kit.AbilityKit'; 731 732class MyUIAbility extends UIAbility { 733 async onSaveStateAsync(reason: AbilityConstant.StateType, wantParam: Record<string, Object>) : Promise<AbilityConstant.OnSaveResult> { 734 await new Promise<string>((res, rej) => { 735 setTimeout(res, 1000); // 延时1秒后执行 736 }); 737 return AbilityConstant.OnSaveResult.RECOVERY_AGREE; 738 } 739} 740``` 741 742### onShare<sup>10+</sup> 743 744onShare(wantParam: Record<string, Object>): void 745 746当跨端分享原子化服务时，系统触发该回调。开发者可以在该回调中设置待分享原子化服务的标题、摘要和URL等数据。 747 748**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 749 750**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 751 752**参数：** 753 754| 参数名 | 类型 | 必填 | 说明 | 755| -------- | -------- | -------- | -------- | 756| wantParam | Record<string, Object> | 是 | 待分享的数据。 | 757 758**示例：** 759 760```ts 761import { UIAbility } from '@kit.AbilityKit'; 762 763export default class MyUIAbility extends UIAbility { 764 onShare(wantParams: Record<string, Object>) { 765 console.info('onShare'); 766 wantParams['ohos.extra.param.key.shareUrl'] = 'example.com'; 767 } 768} 769``` 770 771### onPrepareToTerminate<sup>10+</sup> 772 773onPrepareToTerminate(): boolean 774 775在UIAbility即将关闭前（例如用户通过点击应用窗口右上角的关闭按钮、或者通过Dock栏/托盘右键退出应用时），系统会触发该回调，用于在UIAbility正式关闭前执行其他操作。开发者可以在该回调中返回true阻拦此次关闭，然后在合适时机主动调用[terminateSelf](js-apis-inner-application-uiAbilityContext.md#terminateself)接口关闭。例如，询问用户是否确认关闭UIAbility，再主动销毁UIAbility。 776 777 778> **说明：** 779> 780> - 从API version 15开始，当[UIAbility.onPrepareToTerminateAsync](#onpreparetoterminateasync15)实现时，本回调函数将不执行。当[AbilityStage.onPrepareTerminationAsync](js-apis-app-ability-abilityStage.md#onprepareterminationasync15)或[AbilityStage.onPrepareTermination](js-apis-app-ability-abilityStage.md#onpreparetermination15)实现时，在dock栏或系统托盘处右键点击关闭，本回调函数将不执行。 781> - 如果应用本身或者所使用的三方框架注册了[window.WindowStage.on('windowStageClose')](../apis-arkui/arkts-apis-window-WindowStage.md#onwindowstageclose14)监听，本回调函数将不执行。 782 783**需要权限**：ohos.permission.PREPARE_APP_TERMINATE 784 785**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 786 787**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 788 789**设备行为差异**：该接口仅在2in1和Tablet设备中可正常执行回调，在其他设备上不执行回调。 790 791**返回值：** 792 793| 类型 | 说明 | 794| -- | -- | 795| boolean | 是否执行UIAbility关闭操作，返回true表示本次UIAbility关闭流程取消，返回false表示UIAbility继续正常关闭。 | 796 797**示例：** 798 799```ts 800import { UIAbility, Want } from '@kit.AbilityKit'; 801import { BusinessError } from '@kit.BasicServicesKit'; 802 803export default class EntryAbility extends UIAbility { 804 onPrepareToTerminate() { 805 // 开发者定义预关闭动作 806 // 例如拉起另一个ability，根据ability处理结果执行异步关闭 807 let want: Want = { 808 bundleName: "com.example.myapplication", 809 moduleName: "entry", 810 abilityName: "SecondAbility" 811 } 812 this.context.startAbilityForResult(want) 813 .then((result)=>{ 814 // 获取ability处理结果，当返回结果的resultCode为0关闭当前UIAbility 815 console.info('startAbilityForResult success, resultCode is ' + result.resultCode); 816 if (result.resultCode === 0) { 817 this.context.terminateSelf(); 818 } 819 }).catch((err: BusinessError)=>{ 820 // 异常处理 821 console.error('startAbilityForResult failed, err:' + JSON.stringify(err)); 822 this.context.terminateSelf(); 823 }) 824 825 return true; // 已定义预关闭操作后，返回true表示UIAbility取消关闭 826 } 827} 828``` 829 830### onPrepareToTerminateAsync<sup>15+</sup> 831 832onPrepareToTerminateAsync(): Promise\<boolean> 833 834在UIAbility关闭前（例如用户通过点击应用窗口右上角的关闭按钮、或者通过Dock栏/托盘右键退出应用时），系统会触发该回调，用于在UIAbility正式关闭前执行其他操作。 835 836开发者可以在该回调中返回true阻拦此次关闭，然后在合适时机主动调用[terminateSelf](js-apis-inner-application-uiAbilityContext.md#terminateself)接口关闭。例如，询问用户是否确认关闭UIAbility，再主动销毁UIAbility。 837 838 839> **说明：** 840> 841> - 当[AbilityStage.onPrepareTerminationAsync](js-apis-app-ability-abilityStage.md#onprepareterminationasync15)或[AbilityStage.onPrepareTermination](js-apis-app-ability-abilityStage.md#onpreparetermination15)实现时，在dock栏或系统托盘处右键点击关闭，本回调函数将不执行。 842> - 如果应用本身或者所使用的三方框架注册了[window.WindowStage.on('windowStageClose')](../apis-arkui/arkts-apis-window-WindowStage.md#onwindowstageclose14)监听，本回调函数将不执行。 843> 844> - 若异步回调内发生crash，按超时处理，执行等待超过10秒未响应，UIAbility将被强制关闭。 845 846**需要权限**：ohos.permission.PREPARE_APP_TERMINATE 847 848**原子化服务API**：从API version 15开始，该接口支持在原子化服务中使用。 849 850**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 851 852**设备行为差异**： 853- 从API version 15开始，该接口仅在2in1设备中可正常执行回调，在其他设备上不执行回调。 854- 从API version 19开始，该接口在2in1和Tablet设备中可正常执行回调，在其他设备上不执行回调。 855 856**返回值：** 857 858| 类型 | 说明 | 859| -- | -- | 860| Promise\<boolean> | Promise对象。表示是否执行UIAbility关闭操作，返回true表示本次UIAbility关闭流程取消，返回false表示UIAbility继续正常关闭。 | 861 862**示例：** 863 864```ts 865import { UIAbility } from '@kit.AbilityKit'; 866 867export default class EntryAbility extends UIAbility { 868 async onPrepareToTerminateAsync(): Promise<boolean> { 869 await new Promise<boolean>((res, rej) => { 870 setTimeout(res, 2000); // 延时2秒 871 }); 872 return true; // 已定义预关闭操作后，返回true表示UIAbility取消关闭 873 } 874} 875``` 876 877### onBackPressed<sup>10+</sup> 878 879onBackPressed(): boolean 880 881UIAbility生命周期回调，当UIAbility侧滑返回时触发，根据返回值决定是否销毁UIAbility。 882 883- 当targetSdkVersion<12时，默认返回值为false，会销毁UIAbility。 884- 当targetSdkVersion>=12时，默认返回值为true，会将UIAbility移动到后台不销毁。 885 886**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 887 888**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 889 890**返回值：** 891 892| 类型 | 说明 | 893| -- | -- | 894| boolean | 返回true表示UIAbility将会被移到后台不销毁，返回false表示UIAbility将正常销毁。 | 895 896**示例：** 897 898```ts 899import { UIAbility } from '@kit.AbilityKit'; 900 901export default class EntryAbility extends UIAbility { 902 onBackPressed() { 903 return true; 904 } 905} 906``` 907 908### onCollaborate<sup>18+</sup> 909 910onCollaborate(wantParam: Record<string, Object>): AbilityConstant.CollaborateResult 911 912UIAbility生命周期回调，在多设备协同场景下，协同方应用在被拉起的过程中返回是否接受协同。 913 914 **说明：** 915- 该生命周期回调不支持specified启动模式。 916- 通过startAbility()等方法拉起协同方应用时，需要在Want对象中设置协同标记[Flags](js-apis-ability-wantConstant.md#flags)为FLAG_ABILITY_ON_COLLABORATE。 917- 冷启动时，该回调在[onForeground](#onforeground)前或[onBackground](#onbackground)后调用；热启动时，该回调在[onNewWant](#onnewwant)前调用。 918 919 920**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 921 922**参数：** 923 924| 参数名 | 类型 | 必填 | 说明 | 925| --------- | --------------------------------- | ---- | ------------------------------------------------------------ | 926| wantParam | Record<string, Object> | 是 | want相关参数，仅支持key值取"ohos.extra.param.key.supportCollaborateIndex"。通过该key值可以可以获取到调用方传输的数据并进行相应的处理。| 927 928**返回值：** 929 930| 类型 | 说明 | 931| -------- | ---- | 932| [AbilityConstant.CollaborateResult](js-apis-app-ability-abilityConstant.md#collaborateresult18) | 协同方是否接受协同的结果。 | 933 934**示例：** 935 936```ts 937import { UIAbility, AbilityConstant } from '@kit.AbilityKit'; 938 939export default class MyAbility extends UIAbility { 940 onCollaborate(wantParam: Record<string, Object>) { 941 return AbilityConstant.CollaborateResult.ACCEPT; 942 } 943} 944``` 945 946## Caller 947 948调用方Caller UIAbility（仅支持系统应用）可以通过[startAbilityByCall](js-apis-inner-application-uiAbilityContext.md#startabilitybycall)接口拉起目标Callee UIAbility（可以为三方应用）。Callee UIAbility会返回一个Caller对象给到Caller UIAbility。Caller UIAbility拿到这个Caller对象后，就可以通过Caller对象与Callee UIAbility通讯，发送数据。 949 950### call 951 952call(method: string, data: rpc.Parcelable): Promise<void> 953 954Caller UIAbility向Callee UIAbility发送双方约定好的序列化的数据。使用Promise异步回调。 955 956**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 957 958**参数：** 959 960| 参数名 | 类型 | 必填 | 说明 | 961| -------- | -------- | -------- | -------- | 962| method | string | 是 | 由Caller和Callee双方约定好的方法名，Callee方通过该字段区分消息类型。 | 963| data | [rpc.Parcelable](../apis-ipc-kit/js-apis-rpc.md#parcelable9) | 是 | 由Caller向Callee发送的消息内容，消息内容是序列化的数据。 | 964 965**返回值：** 966 967| 类型 | 说明 | 968| -------- | -------- | 969| Promise<void> | Promise对象。无返回结果的Promise对象。 | 970 971**错误码：** 972 973以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 974 975| 错误码ID | 错误信息 | 976| ------- | -------------------------------- | 977| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 978| 16200001 | The caller has been released. | 979| 16200002 | The callee does not exist. | 980| 16000050 | Internal error. | 981 982**示例：** 983 984```ts 985import { UIAbility, Caller } from '@kit.AbilityKit'; 986import { window } from '@kit.ArkUI'; 987import { rpc } from '@kit.IPCKit'; 988import { BusinessError } from '@kit.BasicServicesKit'; 989 990class MyMessageAble implements rpc.Parcelable { // 自定义的Parcelable数据结构 991 name: string; 992 str: string; 993 num: number = 1; 994 constructor(name: string, str: string) { 995 this.name = name; 996 this.str = str; 997 } 998 marshalling(messageSequence: rpc.MessageSequence) { 999 messageSequence.writeInt(this.num); 1000 messageSequence.writeString(this.str); 1001 console.info(`MyMessageAble marshalling num[${this.num}] str[${this.str}]`); 1002 return true; 1003 } 1004 unmarshalling(messageSequence: rpc.MessageSequence) { 1005 this.num = messageSequence.readInt(); 1006 this.str = messageSequence.readString(); 1007 console.info(`MyMessageAble unmarshalling num[${this.num}] str[${this.str}]`); 1008 return true; 1009 } 1010} 1011let method = 'call_Function'; // 约定的通知消息字符串 1012 1013export default class MainUIAbility extends UIAbility { 1014 onWindowStageCreate(windowStage: window.WindowStage) { 1015 this.context.startAbilityByCall({ 1016 bundleName: 'com.example.myservice', 1017 abilityName: 'MainUIAbility', 1018 deviceId: '' 1019 }).then((obj) => { 1020 let caller: Caller = obj; 1021 let msg = new MyMessageAble('msg', 'world'); // 参考Parcelable数据定义 1022 caller.call(method, msg) 1023 .then(() => { 1024 console.info('Caller call() called'); 1025 }) 1026 .catch((callErr: BusinessError) => { 1027 console.error(`Caller.call catch error, error.code: ${callErr.code}, error.message: ${callErr.message}`); 1028 }); 1029 }).catch((err: BusinessError) => { 1030 console.error(`Caller GetCaller error, error.code: ${err.code}, error.message: ${err.message}`); 1031 }); 1032 } 1033} 1034``` 1035 1036 1037### callWithResult 1038 1039callWithResult(method: string, data: rpc.Parcelable): Promise<rpc.MessageSequence> 1040 1041Caller UIAbility向Callee UIAbility发送消息，Callee UIAbility处理完成后返回结果。使用Promise异步回调。 1042 1043**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 1044 1045**参数：** 1046 1047| 参数名 | 类型 | 必填 | 说明 | 1048| -------- | -------- | -------- | -------- | 1049| method | string | 是 | 由Caller和Calle双方约定好的方法名，Callee方通过该字段区分消息类型。 | 1050| data | [rpc.Parcelable](../apis-ipc-kit/js-apis-rpc.md#parcelable9) | 是 | 由Caller向Callee发送的消息内容，消息内容是序列化的数据。 | 1051 1052**返回值：** 1053 1054| 类型 | 说明 | 1055| -------- | -------- | 1056| Promise<[rpc.MessageSequence](../apis-ipc-kit/js-apis-rpc.md#messagesequence9)> | Promise对象，返回Callee UIAbility的应答数据。 | 1057 1058**错误码：** 1059 1060以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 1061 1062| 错误码ID | 错误信息 | 1063| ------- | -------------------------------- | 1064| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 1065| 16200001 | The caller has been released. | 1066| 16200002 | The callee does not exist. | 1067| 16000050 | Internal error. | 1068 1069**示例：** 1070 1071```ts 1072import { UIAbility, Caller } from '@kit.AbilityKit'; 1073import { window } from '@kit.ArkUI'; 1074import { rpc } from '@kit.IPCKit'; 1075import { BusinessError } from '@kit.BasicServicesKit'; 1076 1077class MyMessageAble implements rpc.Parcelable { 1078 name: string 1079 str: string 1080 num: number = 1 1081 1082 constructor(name: string, str: string) { 1083 this.name = name; 1084 this.str = str; 1085 } 1086 1087 marshalling(messageSequence: rpc.MessageSequence) { 1088 messageSequence.writeInt(this.num); 1089 messageSequence.writeString(this.str); 1090 console.info(`MyMessageAble marshalling num[${this.num}] str[${this.str}]`); 1091 return true; 1092 } 1093 1094 unmarshalling(messageSequence: rpc.MessageSequence) { 1095 this.num = messageSequence.readInt(); 1096 this.str = messageSequence.readString(); 1097 console.info(`MyMessageAble unmarshalling num[${this.num}] str[${this.str}]`); 1098 return true; 1099 } 1100} 1101let method = 'call_Function'; 1102let caller: Caller; 1103 1104export default class MainUIAbility extends UIAbility { 1105 onWindowStageCreate(windowStage: window.WindowStage) { 1106 this.context.startAbilityByCall({ 1107 bundleName: 'com.example.myservice', 1108 abilityName: 'MainUIAbility', 1109 deviceId: '' 1110 }).then((obj) => { 1111 caller = obj; 1112 let msg = new MyMessageAble('msg', 'world'); 1113 caller.callWithResult(method, msg) 1114 .then((data) => { 1115 console.info('Caller callWithResult() called'); 1116 let retMsg = new MyMessageAble('msg', 'world'); 1117 data.readParcelable(retMsg); 1118 }) 1119 .catch((callErr: BusinessError) => { 1120 console.error(`Caller.callWithResult catch error, error.code: ${callErr.code}, error.message: ${callErr.message}`); 1121 }); 1122 }).catch((err: BusinessError) => { 1123 console.error(`Caller GetCaller error, error.code: ${err.code}, error.message: ${err.message}`); 1124 }); 1125 } 1126} 1127``` 1128 1129 1130### release 1131 1132release(): void 1133 1134Caller主动释放与Callee UIAbility的连接。调用该接口后，Caller不能再使用call或callWithResult向Callee方发送消息。 1135 1136**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 1137 1138**错误码：** 1139 1140以下错误码详细介绍请参考[元能力子系统错误码](errorcode-ability.md)。 1141 1142| 错误码ID | 错误信息 | 1143| ------- | -------------------------------- | 1144| 16200001 | The caller has been released. | 1145| 16200002 | The callee does not exist. | 1146 1147**示例：** 1148 1149```ts 1150import { UIAbility, Caller } from '@kit.AbilityKit'; 1151import { window } from '@kit.ArkUI'; 1152import { BusinessError } from '@kit.BasicServicesKit'; 1153 1154let caller: Caller; 1155 1156export default class MainUIAbility extends UIAbility { 1157 onWindowStageCreate(windowStage: window.WindowStage) { 1158 this.context.startAbilityByCall({ 1159 bundleName: 'com.example.myservice', 1160 abilityName: 'MainUIAbility', 1161 deviceId: '' 1162 }).then((obj) => { 1163 caller = obj; 1164 try { 1165 caller.release(); 1166 } catch (releaseErr) { 1167 console.error(`Caller.release catch error, error.code: ${releaseErr.code}, error.message: ${releaseErr.message}`); 1168 } 1169 }).catch((err: BusinessError) => { 1170 console.error(`Caller GetCaller error, error.code: ${err.code}, error.message: ${err.message}`); 1171 }); 1172 } 1173} 1174``` 1175 1176### onRelease 1177 1178onRelease(callback: OnReleaseCallback): void 1179 1180Caller可使用该接口注册Callee UIAbility断开的通知，通过callback回调监听Callee UIAbility主动断开或异常断开事件。 1181 1182**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 1183 1184**参数：** 1185 1186| 参数名 | 类型 | 必填 | 说明 | 1187| -------- | -------- | -------- | -------- | 1188| callback | [OnReleaseCallback](#onreleasecallback) | 是 | 回调函数，返回onRelease回调结果。 | 1189 1190**错误码：** 1191 1192以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 1193 1194| 错误码ID | 错误信息 | 1195| ------- | -------------------------------- | 1196| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 1197| 16200001 | The caller has been released. | 1198 1199**示例：** 1200 1201```ts 1202import { UIAbility, Caller } from '@kit.AbilityKit'; 1203import { window } from '@kit.ArkUI'; 1204import { BusinessError } from '@kit.BasicServicesKit'; 1205 1206export default class MainUIAbility extends UIAbility { 1207 onWindowStageCreate(windowStage: window.WindowStage) { 1208 this.context.startAbilityByCall({ 1209 bundleName: 'com.example.myservice', 1210 abilityName: 'MainUIAbility', 1211 deviceId: '' 1212 }).then((obj) => { 1213 let caller: Caller = obj; 1214 try { 1215 caller.onRelease((str) => { 1216 console.info(`Caller OnRelease CallBack is called ${str}`); 1217 }); 1218 } catch (error) { 1219 console.error(`Caller.onRelease catch error, error.code: ${error.code}, error.message: ${error.message}`); 1220 } 1221 }).catch((err: BusinessError) => { 1222 console.error(`Caller GetCaller error, error.code: ${err.code}, error.message: ${err.message}`); 1223 }); 1224 } 1225} 1226``` 1227 1228### onRemoteStateChange<sup>10+</sup> 1229 1230onRemoteStateChange(callback: OnRemoteStateChangeCallback): void 1231 1232注册协同场景下跨设备组件状态变化监听通知。使用callback异步回调。 1233 1234**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 1235 1236**参数：** 1237 1238| 参数名 | 类型 | 必填 | 说明 | 1239| -------- | -------- | -------- | -------- | 1240| callback | [OnRemoteStateChangeCallback](#onremotestatechangecallback) | 是 | 回调函数，返回onRemoteStateChange回调结果。 | 1241 1242**错误码：** 1243 1244以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 1245 1246| 错误码ID | 错误信息 | 1247| ------- | -------------------------------- | 1248| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 1249| 16200001 | The caller has been released. | 1250 1251**示例：** 1252 1253```ts 1254import { UIAbility, Caller } from '@kit.AbilityKit'; 1255import { window } from '@kit.ArkUI'; 1256import { BusinessError } from '@kit.BasicServicesKit'; 1257 1258export default class MainAbility extends UIAbility { 1259 onWindowStageCreate(windowStage: window.WindowStage) { 1260 let dstDeviceId: string = 'xxxxx'; 1261 this.context.startAbilityByCall({ 1262 bundleName: 'com.example.myservice', 1263 abilityName: 'MainUIAbility', 1264 deviceId: dstDeviceId 1265 }).then((obj) => { 1266 let caller: Caller = obj; 1267 try { 1268 caller.onRemoteStateChange((str) => { 1269 console.info('Remote state changed ' + str); 1270 }); 1271 } catch (error) { 1272 console.error(`Caller.onRemoteStateChange catch error, error.code: ${JSON.stringify(error.code)}, error.message: ${JSON.stringify(error.message)}`); 1273 } 1274 }).catch((err: BusinessError) => { 1275 console.error(`Caller GetCaller error, error.code: ${JSON.stringify(err.code)}, error.message: ${JSON.stringify(err.message)}`); 1276 }); 1277 } 1278} 1279``` 1280 1281### on('release') 1282 1283on(type: 'release', callback: OnReleaseCallback): void 1284 1285Caller可使用该接口注册Callee UIAbility断开的通知，通过callback回调监听Callee UIAbility主动断开或异常断开事件。 1286 1287**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 1288 1289**参数：** 1290 1291| 参数名 | 类型 | 必填 | 说明 | 1292| -------- | -------- | -------- | -------- | 1293| type | string | 是 | 监听releaseCall事件，固定为'release'。 | 1294| callback | [OnReleaseCallback](#onreleasecallback) | 是 | 回调函数，返回on回调结果。 | 1295 1296**错误码：** 1297 1298以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 1299 1300| 错误码ID | 错误信息 | 1301| ------- | -------------------------------- | 1302| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1303| 16200001 | The caller has been released. | 1304 1305**示例：** 1306 1307```ts 1308import { UIAbility, Caller } from '@kit.AbilityKit'; 1309import { window } from '@kit.ArkUI'; 1310import { BusinessError } from '@kit.BasicServicesKit'; 1311 1312export default class MainUIAbility extends UIAbility { 1313 onWindowStageCreate(windowStage: window.WindowStage) { 1314 let dstDeviceId: string = 'xxxx'; 1315 this.context.startAbilityByCall({ 1316 bundleName: 'com.example.myservice', 1317 abilityName: 'MainUIAbility', 1318 deviceId: dstDeviceId 1319 }).then((obj) => { 1320 let caller: Caller = obj; 1321 try { 1322 caller.on('release', (str) => { 1323 console.info(`Caller OnRelease CallBack is called ${str}`); 1324 }); 1325 } catch (error) { 1326 console.error(`Caller.on catch error, error.code: ${error.code}, error.message: ${error.message}`); 1327 } 1328 }).catch((err: BusinessError) => { 1329 console.error(`Caller GetCaller error, error.code: ${err.code}, error.message: ${err.message}`); 1330 }); 1331 } 1332} 1333``` 1334 1335### off('release') 1336 1337off(type: 'release', callback: OnReleaseCallback): void 1338 1339取消注册Callee UIAbility断开的通知，与[Caller.on('release')](#onrelease-1)是反向操作，当前暂未支持。 1340 1341**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 1342 1343**参数：** 1344 1345| 参数名 | 类型 | 必填 | 说明 | 1346| -------- | -------- | -------- | -------- | 1347| type | string | 是 | 监听releaseCall事件，固定为'release'。 | 1348| callback | [OnReleaseCallback](#onreleasecallback) | 是 | 回调函数，返回off回调结果。 | 1349 1350**错误码：** 1351 1352以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 1353 1354| 错误码ID | 错误信息 | 1355| ------- | -------------------------------- | 1356| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1357 1358**示例：** 1359 1360```ts 1361import { UIAbility, Caller, OnReleaseCallback } from '@kit.AbilityKit'; 1362import { window } from '@kit.ArkUI'; 1363import { BusinessError } from '@kit.BasicServicesKit'; 1364 1365export default class MainUIAbility extends UIAbility { 1366 onWindowStageCreate(windowStage: window.WindowStage) { 1367 this.context.startAbilityByCall({ 1368 bundleName: 'com.example.myservice', 1369 abilityName: 'MainUIAbility', 1370 deviceId: '' 1371 }).then((obj) => { 1372 let caller: Caller = obj; 1373 try { 1374 let onReleaseCallBack: OnReleaseCallback = (str) => { 1375 console.info(`Caller OnRelease CallBack is called ${str}`); 1376 }; 1377 caller.on('release', onReleaseCallBack); 1378 caller.off('release', onReleaseCallBack); 1379 } catch (error) { 1380 console.error(`Caller.on or Caller.off catch error, error.code: ${error.code}, error.message: ${error.message}`); 1381 } 1382 }).catch((err: BusinessError) => { 1383 console.error(`Caller GetCaller error, error.code: ${err.code}, error.message: ${err.message}`); 1384 }); 1385 } 1386} 1387``` 1388 1389### off('release') 1390 1391off(type: 'release'): void 1392 1393取消注册Callee UIAbility断开的通知，与[Caller.on('release')](#onrelease-1)是反向操作，当前暂未支持。 1394 1395**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 1396 1397**参数：** 1398 1399| 参数名 | 类型 | 必填 | 说明 | 1400| -------- | -------- | -------- | -------- | 1401| type | string | 是 | 监听releaseCall事件，固定为'release'。 | 1402 1403**错误码：** 1404 1405以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 1406 1407| 错误码ID | 错误信息 | 1408| ------- | -------------------------------- | 1409| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1410 1411**示例：** 1412 1413```ts 1414import { UIAbility, Caller, OnReleaseCallback } from '@kit.AbilityKit'; 1415import { window } from '@kit.ArkUI'; 1416import { BusinessError } from '@kit.BasicServicesKit'; 1417 1418let caller: Caller; 1419 1420export default class MainUIAbility extends UIAbility { 1421 onWindowStageCreate(windowStage: window.WindowStage) { 1422 this.context.startAbilityByCall({ 1423 bundleName: 'com.example.myservice', 1424 abilityName: 'MainUIAbility', 1425 deviceId: '' 1426 }).then((obj) => { 1427 caller = obj; 1428 try { 1429 let onReleaseCallBack: OnReleaseCallback = (str) => { 1430 console.info(`Caller OnRelease CallBack is called ${str}`); 1431 }; 1432 caller.on('release', onReleaseCallBack); 1433 caller.off('release'); 1434 } catch (error) { 1435 console.error(`Caller.on or Caller.off catch error, error.code: ${error.code}, error.message: ${error.message}`); 1436 } 1437 }).catch((err: BusinessError) => { 1438 console.error(`Caller GetCaller error, error.code: ${err.code}, error.message: ${err.message}`); 1439 }); 1440 } 1441} 1442``` 1443 1444## Callee 1445 1446通用组件服务端注册和解除客户端caller通知送信的callback接口。 1447 1448### on 1449 1450on(method: string, callback: CalleeCallback): void 1451 1452通用组件服务端注册消息通知callback。 1453 1454**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 1455 1456**参数：** 1457 1458| 参数名 | 类型 | 必填 | 说明 | 1459| -------- | -------- | -------- | -------- | 1460| method | string | 是 | 与客户端约定的通知消息字符串。 | 1461| callback | [CalleeCallback](#calleecallback) | 是 | 一个[rpc.MessageSequence](../apis-ipc-kit/js-apis-rpc.md#messagesequence9)类型入参的js通知同步回调函数, 回调函数至少要返回一个空的[rpc.Parcelable](../apis-ipc-kit/js-apis-rpc.md#parcelable9)数据对象, 其他视为函数执行错误。 | 1462 1463**错误码：** 1464 1465以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 1466 1467| 错误码ID | 错误信息 | 1468| ------- | -------------------------------- | 1469| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1470| 16200004 | The method has been registered. | 1471| 16000050 | Internal error. | 1472 1473**示例：** 1474 1475```ts 1476import { UIAbility, AbilityConstant, Want } from '@kit.AbilityKit'; 1477import { rpc } from '@kit.IPCKit'; 1478 1479class MyMessageAble implements rpc.Parcelable { 1480 name: string 1481 str: string 1482 num: number = 1 1483 constructor(name: string, str: string) { 1484 this.name = name; 1485 this.str = str; 1486 } 1487 marshalling(messageSequence: rpc.MessageSequence) { 1488 messageSequence.writeInt(this.num); 1489 messageSequence.writeString(this.str); 1490 console.info(`MyMessageAble marshalling num[${this.num}] str[${this.str}]`); 1491 return true; 1492 } 1493 unmarshalling(messageSequence: rpc.MessageSequence) { 1494 this.num = messageSequence.readInt(); 1495 this.str = messageSequence.readString(); 1496 console.info(`MyMessageAble unmarshalling num[${this.num}] str[${this.str}]`); 1497 return true; 1498 } 1499}; 1500let method = 'call_Function'; 1501 1502function funcCallBack(pdata: rpc.MessageSequence) { 1503 let msg = new MyMessageAble('test', ''); 1504 pdata.readParcelable(msg); 1505 return new MyMessageAble('test1', 'Callee test'); 1506} 1507export default class MainUIAbility extends UIAbility { 1508 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 1509 console.info('Callee onCreate is called'); 1510 try { 1511 this.callee.on(method, funcCallBack); 1512 } catch (error) { 1513 console.error(`Callee.on catch error, error.code: ${error.code}, error.message: ${error.message}`); 1514 } 1515 } 1516} 1517``` 1518 1519### off 1520 1521off(method: string): void 1522 1523解除通用组件服务端注册消息通知callback。 1524 1525**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 1526 1527**参数：** 1528 1529| 参数名 | 类型 | 必填 | 说明 | 1530| -------- | -------- | -------- | -------- | 1531| method | string | 是 | 已注册的通知事件字符串。 | 1532 1533**错误码：** 1534 1535以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 1536 1537| 错误码ID | 错误信息 | 1538| ------- | -------------------------------- | 1539| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1540| 16200005 | The method has not been registered. | 1541| 16000050 | Internal error. | 1542 1543**示例：** 1544 1545```ts 1546import { UIAbility, AbilityConstant, Want } from '@kit.AbilityKit'; 1547 1548let method = 'call_Function'; 1549 1550export default class MainUIAbility extends UIAbility { 1551 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 1552 console.info('Callee onCreate is called'); 1553 try { 1554 this.callee.off(method); 1555 } catch (error) { 1556 console.error(`Callee.off catch error, error.code: ${error.code}, error.message: ${error.message}`); 1557 } 1558 } 1559} 1560``` 1561 1562## OnReleaseCallback 1563 1564### (msg: string) 1565 1566(msg: string): void 1567 1568注册通用组件服务端Stub（桩）断开监听通知的回调函数类型。 1569 1570**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 1571 1572**参数：** 1573 1574| 参数名 | 类型 | 必填 | 说明 | 1575| --- | ----- | --- | -------- | 1576| msg | string | 是 | 用于传递释放消息。 | 1577 1578## OnRemoteStateChangeCallback 1579 1580### (msg: string)<sup>10+</sup> 1581 1582(msg: string): void 1583 1584注册协同场景下跨设备组件状态变化监听通知的回调函数类型。 1585 1586**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 1587 1588**参数：** 1589 1590| 参数名 | 类型 | 必填 | 说明 | 1591| --- | ----- | --- | -------- | 1592| msg | string | 是 | 用于传递释放消息。 | 1593 1594## CalleeCallback 1595 1596### (indata: rpc.MessageSequence) 1597 1598(indata: rpc.MessageSequence): rpc.Parcelable 1599 1600通用组件服务端注册消息通知的回调函数类型。 1601 1602**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 1603 1604**参数：** 1605 1606| 参数名 | 类型 | 必填 | 说明 | 1607| --- | ----- | --- | -------- | 1608| indata | [rpc.MessageSequence](../apis-ipc-kit/js-apis-rpc.md#messagesequence9) | 是 | 发送需传递的数据。 | 1609 1610**返回值：** 1611 1612| 类型 | 说明 | 1613| ------------ | ------------------------------------- | 1614| [rpc.Parcelable](../apis-ipc-kit/js-apis-rpc.md#parcelable9) | 返回的数据对象。 | 1615
