1# @ohos.app.ability.UIAbility (UIAbility) 2 3UIAbility是包含UI界面的应用组件，继承自[Ability](js-apis-app-ability-ability.md)，提供组件创建、销毁、前后台切换等生命周期回调，同时也具备组件协同的能力，组件协同主要提供如下常用功能： 4 5- [Caller](#caller)：由[startAbilityByCall](js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartabilitybycall)接口返回，CallerAbility(调用者)可使用Caller与CalleeAbility(被调用者)进行通信。 6- [Callee](#callee)：UIAbility的内部对象，CalleeAbility(被调用者)可以通过Callee与Caller进行通信。 7 8各类Ability的继承关系详见[继承关系说明](./js-apis-app-ability-ability.md#ability的继承关系说明)。 9 10> **说明：** 11> 12> 本模块首批接口从API version 9 开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 13> 14> 本模块接口仅可在Stage模型下使用。 15 16## 导入模块 17 18```ts 19import { UIAbility } from '@kit.AbilityKit'; 20``` 21 22## 属性 23 24**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 25 26| 名称 | 类型 | 只读 | 可选 | 说明 | 27| -------- | -------- | -------- | -------- | -------- | 28| context | [UIAbilityContext](js-apis-inner-application-uiAbilityContext.md) | 否 | 否 | 上下文。<br>**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 | 29| launchWant | [Want](js-apis-app-ability-want.md) | 否 | 否 | UIAbility启动时的参数。<br>**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 | 30| lastRequestWant | [Want](js-apis-app-ability-want.md) | 否 | 否 | 当前UIAbility被多次拉起时，通过[onCreate](#uiabilityoncreate)或[onNewWant](#uiabilityonnewwant)接收到的最近一次Want请求参数。<br>**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。| 31| callee | [Callee](#callee) | 否 | 否 | 调用Stub（桩）服务对象。| 32 33## UIAbility.onCreate 34 35onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void 36 37UIAbility实例处于完全关闭状态下被创建完成后进入该生命周期回调，执行初始化业务逻辑操作。即UIAbility实例[冷启动](../../application-models/uiability-intra-device-interaction.md#目标uiability冷启动)时进入该生命周期回调。同步接口，不支持异步回调。 38 39**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 40 41**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 42 43**参数：** 44 45| 参数名 | 类型 | 必填 | 说明 | 46| -------- | -------- | -------- | -------- | 47| want | [Want](js-apis-app-ability-want.md) | 是 | 当前UIAbility的Want类型信息，包括ability名称、bundle名称等。 | 48| launchParam | [AbilityConstant.LaunchParam](js-apis-app-ability-abilityConstant.md#launchparam) | 是 | 创建 ability、上次异常退出的原因信息。 | 49 50**示例：** 51 52```ts 53import { UIAbility, AbilityConstant, Want } from '@kit.AbilityKit'; 54 55class MyUIAbility extends UIAbility { 56 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 57 console.log(`onCreate, want: ${want.abilityName}`); 58 } 59} 60``` 61 62 63## UIAbility.onWindowStageCreate 64 65onWindowStageCreate(windowStage: window.WindowStage): void 66 67当WindowStage创建后调用。 68 69**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 70 71**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 72 73**参数：** 74 75| 参数名 | 类型 | 必填 | 说明 | 76| -------- | -------- | -------- | -------- | 77| windowStage | [window.WindowStage](../apis-arkui/js-apis-window.md#windowstage9) | 是 | WindowStage相关信息。 | 78 79**示例：** 80 81```ts 82import { UIAbility } from '@kit.AbilityKit'; 83import { window } from '@kit.ArkUI'; 84 85class MyUIAbility extends UIAbility { 86 onWindowStageCreate(windowStage: window.WindowStage) { 87 console.log('onWindowStageCreate'); 88 } 89} 90``` 91 92 93## UIAbility.onWindowStageWillDestroy<sup>12+</sup> 94 95onWindowStageWillDestroy(windowStage: window.WindowStage): void 96 97当WindowStage即将销毁时调用。 98 99**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 100 101**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 102 103**参数：** 104 105| 参数名 | 类型 | 必填 | 说明 | 106| -------- | -------- | -------- | -------- | 107| windowStage | [window.WindowStage](../apis-arkui/js-apis-window.md#windowstage9) | 是 | WindowStage相关信息。 | 108 109**示例：** 110 111```ts 112import { UIAbility } from '@kit.AbilityKit'; 113import { window } from '@kit.ArkUI'; 114 115class MyUIAbility extends UIAbility { 116 onWindowStageWillDestroy(windowStage: window.WindowStage) { 117 console.log('onWindowStageWillDestroy'); 118 } 119} 120``` 121 122 123## UIAbility.onWindowStageDestroy 124 125onWindowStageDestroy(): void 126 127当WindowStage销毁后调用。 128 129**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 130 131**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 132 133**示例：** 134 135```ts 136import { UIAbility } from '@kit.AbilityKit'; 137 138class MyUIAbility extends UIAbility { 139 onWindowStageDestroy() { 140 console.log('onWindowStageDestroy'); 141 } 142} 143``` 144 145 146## UIAbility.onWindowStageRestore 147 148onWindowStageRestore(windowStage: window.WindowStage): void 149 150当迁移多实例ability时，恢复WindowStage后调用。 151 152**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 153 154**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 155 156**参数：** 157 158| 参数名 | 类型 | 必填 | 说明 | 159| -------- | -------- | -------- | -------- | 160| windowStage | [window.WindowStage](../apis-arkui/js-apis-window.md#windowstage9) | 是 | WindowStage相关信息。 | 161 162**示例：** 163 164```ts 165import { UIAbility } from '@kit.AbilityKit'; 166import { window } from '@kit.ArkUI'; 167 168class MyUIAbility extends UIAbility { 169 onWindowStageRestore(windowStage: window.WindowStage) { 170 console.log('onWindowStageRestore'); 171 } 172} 173``` 174 175 176## UIAbility.onDestroy 177 178onDestroy(): void | Promise<void> 179 180UIAbility生命周期回调，在销毁时回调，执行资源清理等操作。使用同步回调或Promise异步回调。 181 182**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 183 184**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 185 186**返回值：** 187 188| 类型 | 说明 | 189| -------- | -------- | 190| void \| Promise<void> | 无返回结果或无返回结果的Promise对象。 | 191 192**示例：** 193 194```ts 195import { UIAbility } from '@kit.AbilityKit'; 196 197class MyUIAbility extends UIAbility { 198 onDestroy() { 199 console.log('onDestroy'); 200 } 201} 202``` 203 204在执行完onDestroy生命周期回调后，应用可能会退出，从而可能导致onDestroy中的异步函数未能正确执行，比如异步写入数据库。可以使用异步生命周期，以确保异步onDestroy完成后再继续后续的生命周期。 205 206```ts 207import { UIAbility } from '@kit.AbilityKit'; 208 209class MyUIAbility extends UIAbility { 210 async onDestroy() { 211 console.log('onDestroy'); 212 // 调用异步函数... 213 } 214} 215``` 216 217## UIAbility.onForeground 218 219onForeground(): void 220 221UIAbility生命周期回调，当应用从后台转到前台时触发。同步接口，不支持异步回调。 222 223**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 224 225**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 226 227**示例：** 228 229```ts 230import { UIAbility } from '@kit.AbilityKit'; 231 232class MyUIAbility extends UIAbility { 233 onForeground() { 234 console.log('onForeground'); 235 } 236} 237``` 238 239 240## UIAbility.onBackground 241 242onBackground(): void 243 244UIAbility生命周期回调，当应用从前台转到后台时触发。同步接口，不支持异步回调。 245 246**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 247 248**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 249 250**示例：** 251 252```ts 253import { UIAbility } from '@kit.AbilityKit'; 254 255class MyUIAbility extends UIAbility { 256 onBackground() { 257 console.log('onBackground'); 258 } 259} 260``` 261 262 263## UIAbility.onContinue 264 265onContinue(wantParam: Record<string, Object>): AbilityConstant.OnContinueResult | Promise<AbilityConstant.OnContinueResult> 266 267当Ability准备迁移时触发，保存数据。 268 269> **说明：** 270> 271> 从API version 12 开始，UIAbility.onContinue生命周期新增支持返回值为Promise\<[AbilityConstant.OnContinueResult](js-apis-app-ability-abilityConstant.md#oncontinueresult)\>形式。 272 273**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 274 275**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 276 277**参数：** 278 279| 参数名 | 类型 | 必填 | 说明 | 280| -------- | -------- | -------- | -------- | 281| wantParam | Record<string, Object> | 是 | want相关参数。 | 282 283**返回值：** 284 285| 类型 | 说明 | 286| -------- | -------- | 287| [AbilityConstant.OnContinueResult](js-apis-app-ability-abilityConstant.md#oncontinueresult) \| Promise<[AbilityConstant.OnContinueResult](js-apis-app-ability-abilityConstant.md#oncontinueresult)> | 接续的结果或带接续结果的Promise对象。 | 288 289**示例：** 290 291 ```ts 292 import { UIAbility, AbilityConstant } from '@kit.AbilityKit'; 293 294 class MyUIAbility extends UIAbility { 295 onContinue(wantParams: Record<string, Object>) { 296 console.log('onContinue'); 297 wantParams['myData'] = 'my1234567'; 298 return AbilityConstant.OnContinueResult.AGREE; 299 } 300 } 301 ``` 302 303支持应用在迁移时，使用异步接口进行数据保存。 304 305 ```ts 306 import { UIAbility, AbilityConstant } from '@kit.AbilityKit'; 307 308 class MyUIAbility extends UIAbility { 309 async setWant(wantParams: Record<string, Object>) { 310 console.log('setWant start'); 311 for (let time = 0; time < 1000; ++time) { 312 wantParams[time] = time; 313 } 314 console.log('setWant end'); 315 } 316 317 async onContinue(wantParams: Record<string, Object>) { 318 console.log('onContinue'); 319 return this.setWant(wantParams).then(()=>{ 320 return AbilityConstant.OnContinueResult.AGREE; 321 }); 322 } 323 } 324 ``` 325 326 327## UIAbility.onNewWant 328 329onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): void 330 331UIAbility实例已经启动并在前台运行过，由于某些原因切换到后台，再次启动该UIAbility实例时会回调执行该方法。即UIAbility实例[热启动](../../application-models/uiability-intra-device-interaction.md#目标uiability热启动)时进入该生命周期回调。 332 333**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 334 335**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 336 337**参数：** 338 339| 参数名 | 类型 | 必填 | 说明 | 340| -------- | -------- | -------- | -------- | 341| want | [Want](js-apis-app-ability-want.md) | 是 | Want类型参数，如ability名称，包名等。 | 342| launchParam | [AbilityConstant.LaunchParam](js-apis-app-ability-abilityConstant.md#launchparam) | 是 | UIAbility启动的原因、上次异常退出的原因信息。 | 343 344**示例：** 345 346```ts 347import { UIAbility, AbilityConstant, Want } from '@kit.AbilityKit'; 348 349class MyUIAbility extends UIAbility { 350 onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam) { 351 console.log(`onNewWant, want: ${want.abilityName}`); 352 console.log(`onNewWant, launchParam: ${JSON.stringify(launchParam)}`); 353 } 354} 355``` 356 357## UIAbility.onDump 358 359onDump(params: Array\<string>): Array\<string> 360 361转储客户端信息时调用，可用于转储非敏感信息。 362 363**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 364 365**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 366 367**参数：** 368 369| 参数名 | 类型 | 必填 | 说明 | 370| -------- | -------- | -------- | -------- | 371| params | Array\<string> | 是 | 表示命令形式的参数。| 372 373**返回值：** 374 375| 类型 | 说明 | 376| -------- | -------- | 377| Array\<string> | 转储信息数组。| 378 379**示例：** 380 381```ts 382import { UIAbility } from '@kit.AbilityKit'; 383 384class MyUIAbility extends UIAbility { 385 onDump(params: Array<string>) { 386 console.log(`dump, params: ${JSON.stringify(params)}`); 387 return ['params']; 388 } 389} 390``` 391 392 393## UIAbility.onSaveState 394 395onSaveState(reason: AbilityConstant.StateType, wantParam: Record<string, Object>): AbilityConstant.OnSaveResult 396 397该API配合[appRecovery](js-apis-app-ability-appRecovery.md)使用。在应用故障时，如果使能了自动保存状态，框架将回调onSaveState保存UIAbility状态。 398 399**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 400 401**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 402 403**参数：** 404 405| 参数名 | 类型 | 必填 | 说明 | 406| -------- | -------- | -------- | -------- | 407| reason | [AbilityConstant.StateType](js-apis-app-ability-abilityConstant.md#statetype) | 是 | 回调保存状态的原因。 | 408| wantParam | Record<string, Object> | 是 | want相关参数。 | 409 410**返回值：** 411 412| 类型 | 说明 | 413| -------- | -------- | 414| [AbilityConstant.OnSaveResult](js-apis-app-ability-abilityConstant.md#onsaveresult) | 是否同意保存当前UIAbility的状态。 | 415 416**示例：** 417 418```ts 419import { UIAbility, AbilityConstant } from '@kit.AbilityKit'; 420 421class MyUIAbility extends UIAbility { 422 onSaveState(reason: AbilityConstant.StateType, wantParam: Record<string, Object>) { 423 console.log('onSaveState'); 424 wantParam['myData'] = 'my1234567'; 425 return AbilityConstant.OnSaveResult.RECOVERY_AGREE; 426 } 427} 428``` 429 430## UIAbility.onShare<sup>10+</sup> 431 432onShare(wantParam: Record<string, Object>): void 433 434在跨端分享场景下，在UIAbility中设置分享方设备要分享的数据。 435 436**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 437 438**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 439 440**参数：** 441 442| 参数名 | 类型 | 必填 | 说明 | 443| -------- | -------- | -------- | -------- | 444| wantParam | Record<string, Object> | 是 | 待分享的数据。 | 445 446**示例：** 447 448```ts 449import { UIAbility } from '@kit.AbilityKit'; 450 451class MyUIAbility extends UIAbility { 452 onShare(wantParams: Record<string, Object>) { 453 console.log('onShare'); 454 wantParams['ohos.extra.param.key.shareUrl'] = 'example.com'; 455 } 456} 457``` 458 459## UIAbility.onPrepareToTerminate<sup>10+</sup> 460 461onPrepareToTerminate(): boolean 462 463UIAbility生命周期回调，在UIAbility关闭时触发，用于在UIAbility正式关闭前执行其他操作。例如，询问用户是否确认关闭UIAbility。如果用户确认关闭UIAbility，可配合[terminateSelf](js-apis-inner-application-uiAbilityContext.md#uiabilitycontextterminateself)接口关闭。 464 465当前仅在2in1设备上生效。 466 467> **说明：** 468> 469> - 从API version 15开始，当[UIAbility.onPrepareToTerminateAsync](#uiabilityonpreparetoterminateasync15)实现时，本回调函数将不执行。当[AbilityStage.onPrepareTerminationAsync](js-apis-app-ability-abilityStage.md#abilitystageonprepareterminationasync15)或[AbilityStage.onPrepareTermination](js-apis-app-ability-abilityStage.md#abilitystageonpreparetermination15)实现时，在dock栏或系统托盘处右键点击关闭，本回调函数将不执行。 470 471**需要权限**：ohos.permission.PREPARE_APP_TERMINATE 472 473**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 474 475**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 476 477**返回值：** 478 479| 类型 | 说明 | 480| -- | -- | 481| boolean | 是否执行UIAbility关闭操作，返回true表示本次UIAbility关闭流程取消，返回false表示UIAbility继续正常关闭。 | 482 483**示例：** 484 485```ts 486import { UIAbility, Want } from '@kit.AbilityKit'; 487import { BusinessError } from '@kit.BasicServicesKit'; 488 489export default class EntryAbility extends UIAbility { 490 onPrepareToTerminate() { 491 // 开发者定义预关闭动作 492 // 例如拉起另一个ability，根据ability处理结果执行异步关闭 493 let want: Want = { 494 bundleName: "com.example.myapplication", 495 moduleName: "entry", 496 abilityName: "SecondAbility" 497 } 498 this.context.startAbilityForResult(want) 499 .then((result)=>{ 500 // 获取ability处理结果，当返回结果的resultCode为0关闭当前UIAbility 501 console.log('startAbilityForResult success, resultCode is ' + result.resultCode); 502 if (result.resultCode === 0) { 503 this.context.terminateSelf(); 504 } 505 }).catch((err: BusinessError)=>{ 506 // 异常处理 507 console.error('startAbilityForResult failed, err:' + JSON.stringify(err)); 508 this.context.terminateSelf(); 509 }) 510 511 return true; // 已定义预关闭操作后，返回true表示UIAbility取消关闭 512 } 513} 514``` 515 516## UIAbility.onPrepareToTerminateAsync<sup>15+</sup> 517 518onPrepareToTerminateAsync(): Promise\<boolean> 519 520UIAbility生命周期异步回调，在UIAbility关闭时触发，通过使用Promise异步回调的方式，在UIAbility正式关闭前执行操作。例如，询问用户是否确认关闭UIAbility。如果用户确认关闭UIAbility，可配合[terminateSelf](js-apis-inner-application-uiAbilityContext.md#uiabilitycontextterminateself)接口关闭。 521 522当前仅在2in1设备上生效。 523 524> **说明：** 525> 526> - 当[AbilityStage.onPrepareTerminationAsync](js-apis-app-ability-abilityStage.md#abilitystageonprepareterminationasync15)或[AbilityStage.onPrepareTermination](js-apis-app-ability-abilityStage.md#abilitystageonpreparetermination15)实现时，在dock栏或系统托盘处右键点击关闭，本回调函数将不执行。 527> 528> - 若异步回调内发生crash，按超时处理，执行等待超过10秒未响应，UIAbility将被强制关闭。 529 530**需要权限**：ohos.permission.PREPARE_APP_TERMINATE 531 532**原子化服务API**：从API version 15开始，该接口支持在原子化服务中使用。 533 534**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 535 536**返回值：** 537 538| 类型 | 说明 | 539| -- | -- | 540| Promise\<boolean> | Promise对象。表示是否执行UIAbility关闭操作，返回true表示本次UIAbility关闭流程取消，返回false表示UIAbility继续正常关闭。 | 541 542**示例：** 543 544```ts 545import { UIAbility } from '@kit.AbilityKit'; 546 547export default class EntryAbility extends UIAbility { 548 async onPrepareToTerminateAsync(): Promise<boolean> { 549 await new Promise<boolean>((res, rej) => { 550 setTimeout(res, 2000); // 延时2秒 551 }); 552 return true; // 已定义预关闭操作后，返回true表示UIAbility取消关闭 553 } 554} 555``` 556 557## UIAbility.onBackPressed<sup>10+</sup> 558 559onBackPressed(): boolean 560 561UIAbility生命周期回调，当UIAbility侧滑返回时触发，根据返回值决定是否销毁UIAbility。 562 563- 当targetSdkVersion<12时，默认返回值为false，会销毁UIAbility。 564- 当targetSdkVersion>=12时，默认返回值为true，会将UIAbility移动到后台不销毁。 565 566**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 567 568**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 569 570**返回值：** 571 572| 类型 | 说明 | 573| -- | -- | 574| boolean | 返回true表示UIAbility将会被移到后台不销毁，返回false表示UIAbility将正常销毁。 | 575 576**示例：** 577 578```ts 579import { UIAbility } from '@kit.AbilityKit'; 580 581export default class EntryAbility extends UIAbility { 582 onBackPressed() { 583 return true; 584 } 585} 586``` 587 588## Caller 589 590通用组件Caller通信客户端调用接口, 用来向通用组件服务端发送约定数据。 591 592### Caller.call 593 594call(method: string, data: rpc.Parcelable): Promise<void> 595 596向通用组件服务端发送约定序列化数据。使用Promise异步回调。 597 598**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 599 600**参数：** 601 602| 参数名 | 类型 | 必填 | 说明 | 603| -------- | -------- | -------- | -------- | 604| method | string | 是 | 约定的服务端注册事件字符串。 | 605| data | [rpc.Parcelable](../apis-ipc-kit/js-apis-rpc.md#parcelable9) | 是 | 由开发者实现的Parcelable可序列化数据。 | 606 607**返回值：** 608 609| 类型 | 说明 | 610| -------- | -------- | 611| Promise<void> | Promise对象。无返回结果的Promise对象。 | 612 613**错误码：** 614 615以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 616 617| 错误码ID | 错误信息 | 618| ------- | -------------------------------- | 619| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 620| 16200001 | Caller released. The caller has been released. | 621| 16200002 | The callee does not exist. | 622| 16000050 | Internal error. | 623 624**示例：** 625 626```ts 627import { UIAbility, Caller } from '@kit.AbilityKit'; 628import { window } from '@kit.ArkUI'; 629import { rpc } from '@kit.IPCKit'; 630import { BusinessError } from '@kit.BasicServicesKit'; 631 632class MyMessageAble implements rpc.Parcelable { // 自定义的Parcelable数据结构 633 name: string 634 str: string 635 num: number = 1 636 constructor(name: string, str: string) { 637 this.name = name; 638 this.str = str; 639 } 640 marshalling(messageSequence: rpc.MessageSequence) { 641 messageSequence.writeInt(this.num); 642 messageSequence.writeString(this.str); 643 console.log(`MyMessageAble marshalling num[${this.num}] str[${this.str}]`); 644 return true; 645 } 646 unmarshalling(messageSequence: rpc.MessageSequence) { 647 this.num = messageSequence.readInt(); 648 this.str = messageSequence.readString(); 649 console.log(`MyMessageAble unmarshalling num[${this.num}] str[${this.str}]`); 650 return true; 651 } 652}; 653let method = 'call_Function'; // 约定的通知消息字符串 654let caller: Caller; 655 656export default class MainUIAbility extends UIAbility { 657 onWindowStageCreate(windowStage: window.WindowStage) { 658 this.context.startAbilityByCall({ 659 bundleName: 'com.example.myservice', 660 abilityName: 'MainUIAbility', 661 deviceId: '' 662 }).then((obj) => { 663 caller = obj; 664 let msg = new MyMessageAble('msg', 'world'); // 参考Parcelable数据定义 665 caller.call(method, msg) 666 .then(() => { 667 console.log('Caller call() called'); 668 }) 669 .catch((callErr: BusinessError) => { 670 console.error(`Caller.call catch error, error.code: ${callErr.code}, error.message: ${callErr.message}`); 671 }); 672 }).catch((err: BusinessError) => { 673 console.error(`Caller GetCaller error, error.code: ${err.code}, error.message: ${err.message}`); 674 }); 675 } 676} 677``` 678 679 680### Caller.callWithResult 681 682callWithResult(method: string, data: rpc.Parcelable): Promise<rpc.MessageSequence> 683 684向通用组件服务端发送约定序列化数据, 并将服务端返回的约定序列化数据带回。使用Promise异步回调。 685 686**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 687 688**参数：** 689 690| 参数名 | 类型 | 必填 | 说明 | 691| -------- | -------- | -------- | -------- | 692| method | string | 是 | 约定的服务端注册事件字符串。 | 693| data | [rpc.Parcelable](../apis-ipc-kit/js-apis-rpc.md#parcelable9) | 是 | 由开发者实现的Parcelable可序列化数据。 | 694 695**返回值：** 696 697| 类型 | 说明 | 698| -------- | -------- | 699| Promise<[rpc.MessageSequence](../apis-ipc-kit/js-apis-rpc.md#messagesequence9)> | Promise对象，返回通用组件服务端应答数据。 | 700 701**错误码：** 702 703以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 704 705| 错误码ID | 错误信息 | 706| ------- | -------------------------------- | 707| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 708| 16200001 | Caller released. The caller has been released. | 709| 16200002 | The callee does not exist. | 710| 16000050 | Internal error. | 711 712**示例：** 713 714```ts 715import { UIAbility, Caller } from '@kit.AbilityKit'; 716import { window } from '@kit.ArkUI'; 717import { rpc } from '@kit.IPCKit'; 718import { BusinessError } from '@kit.BasicServicesKit'; 719 720class MyMessageAble implements rpc.Parcelable { 721 name: string 722 str: string 723 num: number = 1 724 constructor(name: string, str: string) { 725 this.name = name; 726 this.str = str; 727 } 728 marshalling(messageSequence: rpc.MessageSequence) { 729 messageSequence.writeInt(this.num); 730 messageSequence.writeString(this.str); 731 console.log(`MyMessageAble marshalling num[${this.num}] str[${this.str}]`); 732 return true; 733 } 734 unmarshalling(messageSequence: rpc.MessageSequence) { 735 this.num = messageSequence.readInt(); 736 this.str = messageSequence.readString(); 737 console.log(`MyMessageAble unmarshalling num[${this.num}] str[${this.str}]`); 738 return true; 739 } 740}; 741let method = 'call_Function'; 742let caller: Caller; 743 744export default class MainUIAbility extends UIAbility { 745 onWindowStageCreate(windowStage: window.WindowStage) { 746 this.context.startAbilityByCall({ 747 bundleName: 'com.example.myservice', 748 abilityName: 'MainUIAbility', 749 deviceId: '' 750 }).then((obj) => { 751 caller = obj; 752 let msg = new MyMessageAble('msg', 'world'); 753 caller.callWithResult(method, msg) 754 .then((data) => { 755 console.log('Caller callWithResult() called'); 756 let retmsg = new MyMessageAble('msg', 'world'); 757 data.readParcelable(retmsg); 758 }) 759 .catch((callErr: BusinessError) => { 760 console.error(`Caller.callWithResult catch error, error.code: ${callErr.code}, error.message: ${callErr.message}`); 761 }); 762 }).catch((err: BusinessError) => { 763 console.error(`Caller GetCaller error, error.code: ${err.code}, error.message: ${err.message}`); 764 }); 765 } 766} 767``` 768 769 770### Caller.release 771 772release(): void 773 774主动释放通用组件服务端的通信接口。 775 776**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 777 778**错误码：** 779 780以下错误码详细介绍请参考[元能力子系统错误码](errorcode-ability.md)。 781 782| 错误码ID | 错误信息 | 783| ------- | -------------------------------- | 784| 16200001 | Caller released. The caller has been released. | 785| 16200002 | The callee does not exist. | 786 787**示例：** 788 789```ts 790import { UIAbility, Caller } from '@kit.AbilityKit'; 791import { window } from '@kit.ArkUI'; 792import { BusinessError } from '@kit.BasicServicesKit'; 793 794let caller: Caller; 795 796export default class MainUIAbility extends UIAbility { 797 onWindowStageCreate(windowStage: window.WindowStage) { 798 this.context.startAbilityByCall({ 799 bundleName: 'com.example.myservice', 800 abilityName: 'MainUIAbility', 801 deviceId: '' 802 }).then((obj) => { 803 caller = obj; 804 try { 805 caller.release(); 806 } catch (releaseErr) { 807 console.error(`Caller.release catch error, error.code: ${releaseErr.code}, error.message: ${releaseErr.message}`); 808 } 809 }).catch((err: BusinessError) => { 810 console.error(`Caller GetCaller error, error.code: ${err.code}, error.message: ${err.message}`); 811 }); 812 } 813} 814``` 815 816### Caller.onRelease 817 818 onRelease(callback: OnReleaseCallback): void 819 820注册通用组件服务端Stub（桩）断开监听通知。使用callback异步回调。 821 822**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 823 824**参数：** 825 826| 参数名 | 类型 | 必填 | 说明 | 827| -------- | -------- | -------- | -------- | 828| callback | [OnReleaseCallback](#onreleasecallback) | 是 | 回调函数，返回onRelease回调结果。 | 829 830**错误码：** 831 832以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 833 834| 错误码ID | 错误信息 | 835| ------- | -------------------------------- | 836| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 837| 16200001 | Caller released. The caller has been released. | 838 839**示例：** 840 841```ts 842import { UIAbility, Caller } from '@kit.AbilityKit'; 843import { window } from '@kit.ArkUI'; 844import { BusinessError } from '@kit.BasicServicesKit'; 845 846let caller: Caller; 847 848export default class MainUIAbility extends UIAbility { 849 onWindowStageCreate(windowStage: window.WindowStage) { 850 this.context.startAbilityByCall({ 851 bundleName: 'com.example.myservice', 852 abilityName: 'MainUIAbility', 853 deviceId: '' 854 }).then((obj) => { 855 caller = obj; 856 try { 857 caller.onRelease((str) => { 858 console.log(`Caller OnRelease CallBack is called ${str}`); 859 }); 860 } catch (error) { 861 console.error(`Caller.onRelease catch error, error.code: $error.code}, error.message: ${error.message}`); 862 } 863 }).catch((err: BusinessError) => { 864 console.error(`Caller GetCaller error, error.code: ${err.code}, error.message: ${err.message}`); 865 }); 866 } 867} 868``` 869 870### Caller.onRemoteStateChange<sup>10+</sup> 871 872onRemoteStateChange(callback: OnRemoteStateChangeCallback): void 873 874注册协同场景下跨设备组件状态变化监听通知。使用callback异步回调。 875 876**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 877 878**参数：** 879 880| 参数名 | 类型 | 必填 | 说明 | 881| -------- | -------- | -------- | -------- | 882| callback | [OnRemoteStateChangeCallback](#onremotestatechangecallback10) | 是 | 回调函数，返回onRemoteStateChange回调结果。 | 883 884**错误码：** 885 886以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 887 888| 错误码ID | 错误信息 | 889| ------- | -------------------------------- | 890| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 891| 16200001 | Caller released. The caller has been released. | 892 893**示例：** 894 895```ts 896import { UIAbility, Caller } from '@kit.AbilityKit'; 897import { window } from '@kit.ArkUI'; 898import { BusinessError } from '@kit.BasicServicesKit'; 899 900let caller: Caller; 901let dstDeviceId: string; 902 903export default class MainAbility extends UIAbility { 904 onWindowStageCreate(windowStage: window.WindowStage) { 905 this.context.startAbilityByCall({ 906 bundleName: 'com.example.myservice', 907 abilityName: 'MainUIAbility', 908 deviceId: dstDeviceId 909 }).then((obj) => { 910 caller = obj; 911 try { 912 caller.onRemoteStateChange((str) => { 913 console.log('Remote state changed ' + str); 914 }); 915 } catch (error) { 916 console.error(`Caller.onRemoteStateChange catch error, error.code: ${JSON.stringify(error.code)}, error.message: ${JSON.stringify(error.message)}`); 917 } 918 }).catch((err: BusinessError) => { 919 console.error(`Caller GetCaller error, error.code: ${JSON.stringify(err.code)}, error.message: ${JSON.stringify(err.message)}`); 920 }) 921 } 922} 923``` 924 925### Caller.on('release') 926 927on(type: 'release', callback: OnReleaseCallback): void 928 929注册通用组件服务端Stub（桩）断开监听通知。使用callback异步回调。 930 931**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 932 933**参数：** 934 935| 参数名 | 类型 | 必填 | 说明 | 936| -------- | -------- | -------- | -------- | 937| type | string | 是 | 监听releaseCall事件，固定为'release'。 | 938| callback | [OnReleaseCallback](#onreleasecallback) | 是 | 回调函数，返回on回调结果。 | 939 940**错误码：** 941 942以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 943 944| 错误码ID | 错误信息 | 945| ------- | -------------------------------- | 946| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 947| 16200001 | Caller released. The caller has been released. | 948 949**示例：** 950 951```ts 952import { UIAbility, Caller } from '@kit.AbilityKit'; 953import { window } from '@kit.ArkUI'; 954import { BusinessError } from '@kit.BasicServicesKit'; 955 956let caller: Caller; 957 958export default class MainUIAbility extends UIAbility { 959 onWindowStageCreate(windowStage: window.WindowStage) { 960 this.context.startAbilityByCall({ 961 bundleName: 'com.example.myservice', 962 abilityName: 'MainUIAbility', 963 deviceId: '' 964 }).then((obj) => { 965 caller = obj; 966 try { 967 caller.on('release', (str) => { 968 console.log(`Caller OnRelease CallBack is called ${str}`); 969 }); 970 } catch (error) { 971 console.error(`Caller.on catch error, error.code: ${error.code}, error.message: ${error.message}`); 972 } 973 }).catch((err: BusinessError) => { 974 console.error(`Caller GetCaller error, error.code: ${err.code}, error.message: ${err.message}`); 975 }); 976 } 977} 978``` 979 980### Caller.off('release') 981 982off(type: 'release', callback: OnReleaseCallback): void 983 984取消注册通用组件服务端Stub（桩）断开监听通知。预留能力，当前暂未支持。使用callback异步回调。 985 986**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 987 988**参数：** 989 990| 参数名 | 类型 | 必填 | 说明 | 991| -------- | -------- | -------- | -------- | 992| type | string | 是 | 监听releaseCall事件，固定为'release'。 | 993| callback | [OnReleaseCallback](#onreleasecallback) | 是 | 回调函数，返回off回调结果。 | 994 995**错误码：** 996 997以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 998 999| 错误码ID | 错误信息 | 1000| ------- | -------------------------------- | 1001| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1002 1003**示例：** 1004 1005```ts 1006import { UIAbility, Caller, OnReleaseCallback } from '@kit.AbilityKit'; 1007import { window } from '@kit.ArkUI'; 1008import { BusinessError } from '@kit.BasicServicesKit'; 1009 1010let caller: Caller; 1011 1012export default class MainUIAbility extends UIAbility { 1013 onWindowStageCreate(windowStage: window.WindowStage) { 1014 this.context.startAbilityByCall({ 1015 bundleName: 'com.example.myservice', 1016 abilityName: 'MainUIAbility', 1017 deviceId: '' 1018 }).then((obj) => { 1019 caller = obj; 1020 try { 1021 let onReleaseCallBack: OnReleaseCallback = (str) => { 1022 console.log(`Caller OnRelease CallBack is called ${str}`); 1023 }; 1024 caller.on('release', onReleaseCallBack); 1025 caller.off('release', onReleaseCallBack); 1026 } catch (error) { 1027 console.error(`Caller.on or Caller.off catch error, error.code: ${error.code}, error.message: ${error.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### Caller.off('release') 1037 1038off(type: 'release'): void 1039 1040取消注册通用组件服务端Stub（桩）断开监听通知。预留能力，当前暂未支持。 1041 1042**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 1043 1044**参数：** 1045 1046| 参数名 | 类型 | 必填 | 说明 | 1047| -------- | -------- | -------- | -------- | 1048| type | string | 是 | 监听releaseCall事件，固定为'release'。 | 1049 1050**错误码：** 1051 1052以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 1053 1054| 错误码ID | 错误信息 | 1055| ------- | -------------------------------- | 1056| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1057 1058**示例：** 1059 1060```ts 1061import { UIAbility, Caller, OnReleaseCallback } from '@kit.AbilityKit'; 1062import { window } from '@kit.ArkUI'; 1063import { BusinessError } from '@kit.BasicServicesKit'; 1064 1065let caller: Caller; 1066 1067export default class MainUIAbility extends UIAbility { 1068 onWindowStageCreate(windowStage: window.WindowStage) { 1069 this.context.startAbilityByCall({ 1070 bundleName: 'com.example.myservice', 1071 abilityName: 'MainUIAbility', 1072 deviceId: '' 1073 }).then((obj) => { 1074 caller = obj; 1075 try { 1076 let onReleaseCallBack: OnReleaseCallback = (str) => { 1077 console.log(`Caller OnRelease CallBack is called ${str}`); 1078 }; 1079 caller.on('release', onReleaseCallBack); 1080 caller.off('release'); 1081 } catch (error) { 1082 console.error(`Caller.on or Caller.off catch error, error.code: ${error.code}, error.message: ${error.message}`); 1083 } 1084 }).catch((err: BusinessError) => { 1085 console.error(`Caller GetCaller error, error.code: ${err.code}, error.message: ${err.message}`); 1086 }); 1087 } 1088} 1089``` 1090 1091## Callee 1092 1093通用组件服务端注册和解除客户端caller通知送信的callback接口。 1094 1095### Callee.on 1096 1097on(method: string, callback: CalleeCallback): void 1098 1099通用组件服务端注册消息通知callback。 1100 1101**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 1102 1103**参数：** 1104 1105| 参数名 | 类型 | 必填 | 说明 | 1106| -------- | -------- | -------- | -------- | 1107| method | string | 是 | 与客户端约定的通知消息字符串。 | 1108| callback | [CalleeCallback](#calleecallback) | 是 | 一个[rpc.MessageSequence](../apis-ipc-kit/js-apis-rpc.md#messagesequence9)类型入参的js通知同步回调函数, 回调函数至少要返回一个空的[rpc.Parcelable](../apis-ipc-kit/js-apis-rpc.md#parcelable9)数据对象, 其他视为函数执行错误。 | 1109 1110**错误码：** 1111 1112以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 1113 1114| 错误码ID | 错误信息 | 1115| ------- | -------------------------------- | 1116| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1117| 16200004 | The method has been registered. | 1118| 16000050 | Internal error. | 1119 1120**示例：** 1121 1122```ts 1123import { UIAbility, AbilityConstant, Want } from '@kit.AbilityKit'; 1124import { rpc } from '@kit.IPCKit'; 1125 1126class MyMessageAble implements rpc.Parcelable { 1127 name: string 1128 str: string 1129 num: number = 1 1130 constructor(name: string, str: string) { 1131 this.name = name; 1132 this.str = str; 1133 } 1134 marshalling(messageSequence: rpc.MessageSequence) { 1135 messageSequence.writeInt(this.num); 1136 messageSequence.writeString(this.str); 1137 console.log(`MyMessageAble marshalling num[${this.num}] str[${this.str}]`); 1138 return true; 1139 } 1140 unmarshalling(messageSequence: rpc.MessageSequence) { 1141 this.num = messageSequence.readInt(); 1142 this.str = messageSequence.readString(); 1143 console.log(`MyMessageAble unmarshalling num[${this.num}] str[${this.str}]`); 1144 return true; 1145 } 1146}; 1147let method = 'call_Function'; 1148 1149function funcCallBack(pdata: rpc.MessageSequence) { 1150 console.log(`Callee funcCallBack is called ${pdata}`); 1151 let msg = new MyMessageAble('test', ''); 1152 pdata.readParcelable(msg); 1153 return new MyMessageAble('test1', 'Callee test'); 1154} 1155export default class MainUIAbility extends UIAbility { 1156 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 1157 console.log('Callee onCreate is called'); 1158 try { 1159 this.callee.on(method, funcCallBack); 1160 } catch (error) { 1161 console.error(`Callee.on catch error, error.code: ${error.code}, error.message: ${error.message}`); 1162 } 1163 } 1164} 1165``` 1166 1167### Callee.off 1168 1169off(method: string): void 1170 1171解除通用组件服务端注册消息通知callback。 1172 1173**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 1174 1175**参数：** 1176 1177| 参数名 | 类型 | 必填 | 说明 | 1178| -------- | -------- | -------- | -------- | 1179| method | string | 是 | 已注册的通知事件字符串。 | 1180 1181**错误码：** 1182 1183以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 1184 1185| 错误码ID | 错误信息 | 1186| ------- | -------------------------------- | 1187| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1188| 16200005 | The method has not been registered. | 1189| 16000050 | Internal error. | 1190 1191**示例：** 1192 1193```ts 1194import { UIAbility, AbilityConstant, Want } from '@kit.AbilityKit'; 1195 1196let method = 'call_Function'; 1197 1198export default class MainUIAbility extends UIAbility { 1199 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 1200 console.log('Callee onCreate is called'); 1201 try { 1202 this.callee.off(method); 1203 } catch (error) { 1204 console.error(`Callee.off catch error, error.code: ${error.code}, error.message: ${error.message}`); 1205 } 1206 } 1207} 1208``` 1209 1210## OnReleaseCallback 1211 1212### (msg: string) 1213 1214(msg: string): void 1215 1216注册通用组件服务端Stub（桩）断开监听通知的回调函数类型。 1217 1218**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 1219 1220**参数：** 1221 1222| 参数名 | 类型 | 必填 | 说明 | 1223| --- | ----- | --- | -------- | 1224| msg | string | 是 | 用于传递释放消息。 | 1225 1226## OnRemoteStateChangeCallback<sup>10+</sup> 1227 1228### (msg: string) 1229 1230(msg: string): void 1231 1232注册协同场景下跨设备组件状态变化监听通知的回调函数类型。 1233 1234**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 1235 1236**参数：** 1237 1238| 参数名 | 类型 | 必填 | 说明 | 1239| --- | ----- | --- | -------- | 1240| msg | string | 是 | 用于传递释放消息。 | 1241 1242## CalleeCallback 1243 1244### (indata: rpc.MessageSequence) 1245 1246(indata: rpc.MessageSequence): rpc.Parcelable 1247 1248通用组件服务端注册消息通知的回调函数类型。 1249 1250**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 1251 1252**参数：** 1253 1254| 参数名 | 类型 | 必填 | 说明 | 1255| --- | ----- | --- | -------- | 1256| indata | [rpc.MessageSequence](../apis-ipc-kit/js-apis-rpc.md#messagesequence9) | 是 | 发送需传递的数据。 | 1257 1258**返回值：** 1259 1260| 类型 | 说明 | 1261| ------------ | ------------------------------------- | 1262| [rpc.Parcelable](../apis-ipc-kit/js-apis-rpc.md#parcelable9) | 返回的数据对象。 | 1263