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最后请求时的参数。<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生命周期回调，当系统预关闭开关打开后（配置系统参数persist.sys.prepare_terminate为true打开），在UIAbility关闭时触发，可在回调中定义操作来决定是否继续执行关闭UIAbility的操作。如果UIAbility在退出时需要与用户交互确认是否关闭UIAbility，可在此生命周期回调中定义预关闭操作配合[terminateSelf](js-apis-inner-application-uiAbilityContext.md#uiabilitycontextterminateself)接口退出，如弹窗确认是否关闭，并配置预关闭生命周期返回true取消正常关闭。 464 465**需要权限**：ohos.permission.PREPARE_APP_TERMINATE 466 467**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 468 469**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 470 471**返回值：** 472 473| 类型 | 说明 | 474| -- | -- | 475| boolean | 是否执行UIAbility关闭操作，返回true表示本次UIAbility关闭流程取消，不再退出，返回false表示UIAbility继续正常关闭。 | 476 477**示例：** 478 479```ts 480import { UIAbility, Want } from '@kit.AbilityKit'; 481import { BusinessError } from '@kit.BasicServicesKit'; 482 483export default class EntryAbility extends UIAbility { 484 onPrepareToTerminate() { 485 // 开发者定义预关闭动作 486 // 例如拉起另一个ability，根据ability处理结果执行异步关闭 487 let want: Want = { 488 bundleName: "com.example.myapplication", 489 moduleName: "entry", 490 abilityName: "SecondAbility" 491 } 492 this.context.startAbilityForResult(want) 493 .then((result)=>{ 494 // 获取ability处理结果，当返回结果的resultCode为0关闭当前UIAbility 495 console.log('startAbilityForResult success, resultCode is ' + result.resultCode); 496 if (result.resultCode === 0) { 497 this.context.terminateSelf(); 498 } 499 }).catch((err: BusinessError)=>{ 500 // 异常处理 501 console.error('startAbilityForResult failed, err:' + JSON.stringify(err)); 502 this.context.terminateSelf(); 503 }) 504 505 return true; // 已定义预关闭操作后，返回true表示UIAbility取消关闭 506 } 507} 508``` 509 510## UIAbility.onBackPressed<sup>10+</sup> 511 512onBackPressed(): boolean 513 514UIAbility生命周期回调，当UIAbility侧滑返回时触发，根据返回值决定是否销毁UIAbility。 515 516- 当targetSdkVersion<12时，默认返回值为false，会销毁UIAbility。 517- 当targetSdkVersion>=12时，默认返回值为true，会将UIAbility移动到后台不销毁。 518 519**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 520 521**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 522 523**返回值：** 524 525| 类型 | 说明 | 526| -- | -- | 527| boolean | 返回true表示UIAbility将会被移到后台不销毁，返回false表示UIAbility将正常销毁。 | 528 529**示例：** 530 531```ts 532import { UIAbility } from '@kit.AbilityKit'; 533 534export default class EntryAbility extends UIAbility { 535 onBackPressed() { 536 return true; 537 } 538} 539``` 540 541## Caller 542 543通用组件Caller通信客户端调用接口, 用来向通用组件服务端发送约定数据。 544 545### Caller.call 546 547call(method: string, data: rpc.Parcelable): Promise<void> 548 549向通用组件服务端发送约定序列化数据。使用Promise异步回调。 550 551**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 552 553**参数：** 554 555| 参数名 | 类型 | 必填 | 说明 | 556| -------- | -------- | -------- | -------- | 557| method | string | 是 | 约定的服务端注册事件字符串。 | 558| data | [rpc.Parcelable](../apis-ipc-kit/js-apis-rpc.md#parcelable9) | 是 | 由开发者实现的Parcelable可序列化数据。 | 559 560**返回值：** 561 562| 类型 | 说明 | 563| -------- | -------- | 564| Promise<void> | Promise对象。无返回结果的Promise对象。 | 565 566**错误码：** 567 568以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 569 570| 错误码ID | 错误信息 | 571| ------- | -------------------------------- | 572| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 573| 16200001 | Caller released. The caller has been released. | 574| 16200002 | The callee does not exist. | 575| 16000050 | Internal error. | 576 577**示例：** 578 579```ts 580import { UIAbility, Caller } from '@kit.AbilityKit'; 581import { window } from '@kit.ArkUI'; 582import { rpc } from '@kit.IPCKit'; 583import { BusinessError } from '@kit.BasicServicesKit'; 584 585class MyMessageAble implements rpc.Parcelable { // 自定义的Parcelable数据结构 586 name: string 587 str: string 588 num: number = 1 589 constructor(name: string, str: string) { 590 this.name = name; 591 this.str = str; 592 } 593 marshalling(messageSequence: rpc.MessageSequence) { 594 messageSequence.writeInt(this.num); 595 messageSequence.writeString(this.str); 596 console.log(`MyMessageAble marshalling num[${this.num}] str[${this.str}]`); 597 return true; 598 } 599 unmarshalling(messageSequence: rpc.MessageSequence) { 600 this.num = messageSequence.readInt(); 601 this.str = messageSequence.readString(); 602 console.log(`MyMessageAble unmarshalling num[${this.num}] str[${this.str}]`); 603 return true; 604 } 605}; 606let method = 'call_Function'; // 约定的通知消息字符串 607let caller: Caller; 608 609export default class MainUIAbility extends UIAbility { 610 onWindowStageCreate(windowStage: window.WindowStage) { 611 this.context.startAbilityByCall({ 612 bundleName: 'com.example.myservice', 613 abilityName: 'MainUIAbility', 614 deviceId: '' 615 }).then((obj) => { 616 caller = obj; 617 let msg = new MyMessageAble('msg', 'world'); // 参考Parcelable数据定义 618 caller.call(method, msg) 619 .then(() => { 620 console.log('Caller call() called'); 621 }) 622 .catch((callErr: BusinessError) => { 623 console.error(`Caller.call catch error, error.code: ${callErr.code}, error.message: ${callErr.message}`); 624 }); 625 }).catch((err: BusinessError) => { 626 console.error(`Caller GetCaller error, error.code: ${err.code}, error.message: ${err.message}`); 627 }); 628 } 629} 630``` 631 632 633### Caller.callWithResult 634 635callWithResult(method: string, data: rpc.Parcelable): Promise<rpc.MessageSequence> 636 637向通用组件服务端发送约定序列化数据, 并将服务端返回的约定序列化数据带回。使用Promise异步回调。 638 639**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 640 641**参数：** 642 643| 参数名 | 类型 | 必填 | 说明 | 644| -------- | -------- | -------- | -------- | 645| method | string | 是 | 约定的服务端注册事件字符串。 | 646| data | [rpc.Parcelable](../apis-ipc-kit/js-apis-rpc.md#parcelable9) | 是 | 由开发者实现的Parcelable可序列化数据。 | 647 648**返回值：** 649 650| 类型 | 说明 | 651| -------- | -------- | 652| Promise<[rpc.MessageSequence](../apis-ipc-kit/js-apis-rpc.md#messagesequence9)> | Promise对象，返回通用组件服务端应答数据。 | 653 654**错误码：** 655 656以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 657 658| 错误码ID | 错误信息 | 659| ------- | -------------------------------- | 660| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 661| 16200001 | Caller released. The caller has been released. | 662| 16200002 | The callee does not exist. | 663| 16000050 | Internal error. | 664 665**示例：** 666 667```ts 668import { UIAbility, Caller } from '@kit.AbilityKit'; 669import { window } from '@kit.ArkUI'; 670import { rpc } from '@kit.IPCKit'; 671import { BusinessError } from '@kit.BasicServicesKit'; 672 673class MyMessageAble implements rpc.Parcelable { 674 name: string 675 str: string 676 num: number = 1 677 constructor(name: string, str: string) { 678 this.name = name; 679 this.str = str; 680 } 681 marshalling(messageSequence: rpc.MessageSequence) { 682 messageSequence.writeInt(this.num); 683 messageSequence.writeString(this.str); 684 console.log(`MyMessageAble marshalling num[${this.num}] str[${this.str}]`); 685 return true; 686 } 687 unmarshalling(messageSequence: rpc.MessageSequence) { 688 this.num = messageSequence.readInt(); 689 this.str = messageSequence.readString(); 690 console.log(`MyMessageAble unmarshalling num[${this.num}] str[${this.str}]`); 691 return true; 692 } 693}; 694let method = 'call_Function'; 695let caller: Caller; 696 697export default class MainUIAbility extends UIAbility { 698 onWindowStageCreate(windowStage: window.WindowStage) { 699 this.context.startAbilityByCall({ 700 bundleName: 'com.example.myservice', 701 abilityName: 'MainUIAbility', 702 deviceId: '' 703 }).then((obj) => { 704 caller = obj; 705 let msg = new MyMessageAble('msg', 'world'); 706 caller.callWithResult(method, msg) 707 .then((data) => { 708 console.log('Caller callWithResult() called'); 709 let retmsg = new MyMessageAble('msg', 'world'); 710 data.readParcelable(retmsg); 711 }) 712 .catch((callErr: BusinessError) => { 713 console.error(`Caller.callWithResult catch error, error.code: ${callErr.code}, error.message: ${callErr.message}`); 714 }); 715 }).catch((err: BusinessError) => { 716 console.error(`Caller GetCaller error, error.code: ${err.code}, error.message: ${err.message}`); 717 }); 718 } 719} 720``` 721 722 723### Caller.release 724 725release(): void 726 727主动释放通用组件服务端的通信接口。 728 729**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 730 731**错误码：** 732 733以下错误码详细介绍请参考[元能力子系统错误码](errorcode-ability.md)。 734 735| 错误码ID | 错误信息 | 736| ------- | -------------------------------- | 737| 16200001 | Caller released. The caller has been released. | 738| 16200002 | The callee does not exist. | 739 740**示例：** 741 742```ts 743import { UIAbility, Caller } from '@kit.AbilityKit'; 744import { window } from '@kit.ArkUI'; 745import { BusinessError } from '@kit.BasicServicesKit'; 746 747let caller: Caller; 748 749export default class MainUIAbility extends UIAbility { 750 onWindowStageCreate(windowStage: window.WindowStage) { 751 this.context.startAbilityByCall({ 752 bundleName: 'com.example.myservice', 753 abilityName: 'MainUIAbility', 754 deviceId: '' 755 }).then((obj) => { 756 caller = obj; 757 try { 758 caller.release(); 759 } catch (releaseErr) { 760 console.error(`Caller.release catch error, error.code: ${releaseErr.code}, error.message: ${releaseErr.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### Caller.onRelease 770 771 onRelease(callback: OnReleaseCallback): void 772 773注册通用组件服务端Stub（桩）断开监听通知。使用callback异步回调。 774 775**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 776 777**参数：** 778 779| 参数名 | 类型 | 必填 | 说明 | 780| -------- | -------- | -------- | -------- | 781| callback | [OnReleaseCallback](#onreleasecallback) | 是 | 回调函数，返回onRelease回调结果。 | 782 783**错误码：** 784 785以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 786 787| 错误码ID | 错误信息 | 788| ------- | -------------------------------- | 789| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 790| 16200001 | Caller released. The caller has been released. | 791 792**示例：** 793 794```ts 795import { UIAbility, Caller } from '@kit.AbilityKit'; 796import { window } from '@kit.ArkUI'; 797import { BusinessError } from '@kit.BasicServicesKit'; 798 799let caller: Caller; 800 801export default class MainUIAbility extends UIAbility { 802 onWindowStageCreate(windowStage: window.WindowStage) { 803 this.context.startAbilityByCall({ 804 bundleName: 'com.example.myservice', 805 abilityName: 'MainUIAbility', 806 deviceId: '' 807 }).then((obj) => { 808 caller = obj; 809 try { 810 caller.onRelease((str) => { 811 console.log(`Caller OnRelease CallBack is called ${str}`); 812 }); 813 } catch (error) { 814 console.error(`Caller.onRelease catch error, error.code: $error.code}, error.message: ${error.message}`); 815 } 816 }).catch((err: BusinessError) => { 817 console.error(`Caller GetCaller error, error.code: ${err.code}, error.message: ${err.message}`); 818 }); 819 } 820} 821``` 822 823### Caller.onRemoteStateChange<sup>10+</sup> 824 825onRemoteStateChange(callback: OnRemoteStateChangeCallback): void 826 827注册协同场景下跨设备组件状态变化监听通知。使用callback异步回调。 828 829**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 830 831**参数：** 832 833| 参数名 | 类型 | 必填 | 说明 | 834| -------- | -------- | -------- | -------- | 835| callback | [OnRemoteStateChangeCallback](#onremotestatechangecallback10) | 是 | 回调函数，返回onRemoteStateChange回调结果。 | 836 837**错误码：** 838 839以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 840 841| 错误码ID | 错误信息 | 842| ------- | -------------------------------- | 843| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 844| 16200001 | Caller released. The caller has been released. | 845 846**示例：** 847 848```ts 849import { UIAbility, Caller } from '@kit.AbilityKit'; 850import { window } from '@kit.ArkUI'; 851import { BusinessError } from '@kit.BasicServicesKit'; 852 853let caller: Caller; 854let dstDeviceId: string; 855 856export default class MainAbility extends UIAbility { 857 onWindowStageCreate(windowStage: window.WindowStage) { 858 this.context.startAbilityByCall({ 859 bundleName: 'com.example.myservice', 860 abilityName: 'MainUIAbility', 861 deviceId: dstDeviceId 862 }).then((obj) => { 863 caller = obj; 864 try { 865 caller.onRemoteStateChange((str) => { 866 console.log('Remote state changed ' + str); 867 }); 868 } catch (error) { 869 console.error(`Caller.onRemoteStateChange catch error, error.code: ${JSON.stringify(error.code)}, error.message: ${JSON.stringify(error.message)}`); 870 } 871 }).catch((err: BusinessError) => { 872 console.error(`Caller GetCaller error, error.code: ${JSON.stringify(err.code)}, error.message: ${JSON.stringify(err.message)}`); 873 }) 874 } 875} 876``` 877 878### Caller.on('release') 879 880on(type: 'release', callback: OnReleaseCallback): void 881 882注册通用组件服务端Stub（桩）断开监听通知。使用callback异步回调。 883 884**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 885 886**参数：** 887 888| 参数名 | 类型 | 必填 | 说明 | 889| -------- | -------- | -------- | -------- | 890| type | string | 是 | 监听releaseCall事件，固定为'release'。 | 891| callback | [OnReleaseCallback](#onreleasecallback) | 是 | 回调函数，返回on回调结果。 | 892 893**错误码：** 894 895以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 896 897| 错误码ID | 错误信息 | 898| ------- | -------------------------------- | 899| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 900| 16200001 | Caller released. The caller has been released. | 901 902**示例：** 903 904```ts 905import { UIAbility, Caller } from '@kit.AbilityKit'; 906import { window } from '@kit.ArkUI'; 907import { BusinessError } from '@kit.BasicServicesKit'; 908 909let caller: Caller; 910 911export default class MainUIAbility extends UIAbility { 912 onWindowStageCreate(windowStage: window.WindowStage) { 913 this.context.startAbilityByCall({ 914 bundleName: 'com.example.myservice', 915 abilityName: 'MainUIAbility', 916 deviceId: '' 917 }).then((obj) => { 918 caller = obj; 919 try { 920 caller.on('release', (str) => { 921 console.log(`Caller OnRelease CallBack is called ${str}`); 922 }); 923 } catch (error) { 924 console.error(`Caller.on catch error, error.code: ${error.code}, error.message: ${error.message}`); 925 } 926 }).catch((err: BusinessError) => { 927 console.error(`Caller GetCaller error, error.code: ${err.code}, error.message: ${err.message}`); 928 }); 929 } 930} 931``` 932 933### Caller.off('release') 934 935off(type: 'release', callback: OnReleaseCallback): void 936 937取消注册通用组件服务端Stub（桩）断开监听通知。预留能力，当前暂未支持。使用callback异步回调。 938 939**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 940 941**参数：** 942 943| 参数名 | 类型 | 必填 | 说明 | 944| -------- | -------- | -------- | -------- | 945| type | string | 是 | 监听releaseCall事件，固定为'release'。 | 946| callback | [OnReleaseCallback](#onreleasecallback) | 是 | 回调函数，返回off回调结果。 | 947 948**错误码：** 949 950以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 951 952| 错误码ID | 错误信息 | 953| ------- | -------------------------------- | 954| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 955 956**示例：** 957 958```ts 959import { UIAbility, Caller, OnReleaseCallback } from '@kit.AbilityKit'; 960import { window } from '@kit.ArkUI'; 961import { BusinessError } from '@kit.BasicServicesKit'; 962 963let caller: Caller; 964 965export default class MainUIAbility extends UIAbility { 966 onWindowStageCreate(windowStage: window.WindowStage) { 967 this.context.startAbilityByCall({ 968 bundleName: 'com.example.myservice', 969 abilityName: 'MainUIAbility', 970 deviceId: '' 971 }).then((obj) => { 972 caller = obj; 973 try { 974 let onReleaseCallBack: OnReleaseCallback = (str) => { 975 console.log(`Caller OnRelease CallBack is called ${str}`); 976 }; 977 caller.on('release', onReleaseCallBack); 978 caller.off('release', onReleaseCallBack); 979 } catch (error) { 980 console.error(`Caller.on or Caller.off catch error, error.code: ${error.code}, error.message: ${error.message}`); 981 } 982 }).catch((err: BusinessError) => { 983 console.error(`Caller GetCaller error, error.code: ${err.code}, error.message: ${err.message}`); 984 }); 985 } 986} 987``` 988 989### Caller.off('release') 990 991off(type: 'release'): void 992 993取消注册通用组件服务端Stub（桩）断开监听通知。预留能力，当前暂未支持。 994 995**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 996 997**参数：** 998 999| 参数名 | 类型 | 必填 | 说明 | 1000| -------- | -------- | -------- | -------- | 1001| type | string | 是 | 监听releaseCall事件，固定为'release'。 | 1002 1003**错误码：** 1004 1005以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 1006 1007| 错误码ID | 错误信息 | 1008| ------- | -------------------------------- | 1009| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1010 1011**示例：** 1012 1013```ts 1014import { UIAbility, Caller, OnReleaseCallback } from '@kit.AbilityKit'; 1015import { window } from '@kit.ArkUI'; 1016import { BusinessError } from '@kit.BasicServicesKit'; 1017 1018let caller: Caller; 1019 1020export default class MainUIAbility extends UIAbility { 1021 onWindowStageCreate(windowStage: window.WindowStage) { 1022 this.context.startAbilityByCall({ 1023 bundleName: 'com.example.myservice', 1024 abilityName: 'MainUIAbility', 1025 deviceId: '' 1026 }).then((obj) => { 1027 caller = obj; 1028 try { 1029 let onReleaseCallBack: OnReleaseCallback = (str) => { 1030 console.log(`Caller OnRelease CallBack is called ${str}`); 1031 }; 1032 caller.on('release', onReleaseCallBack); 1033 caller.off('release'); 1034 } catch (error) { 1035 console.error(`Caller.on or Caller.off catch error, error.code: ${error.code}, error.message: ${error.message}`); 1036 } 1037 }).catch((err: BusinessError) => { 1038 console.error(`Caller GetCaller error, error.code: ${err.code}, error.message: ${err.message}`); 1039 }); 1040 } 1041} 1042``` 1043 1044## Callee 1045 1046通用组件服务端注册和解除客户端caller通知送信的callback接口。 1047 1048### Callee.on 1049 1050on(method: string, callback: CalleeCallback): void 1051 1052通用组件服务端注册消息通知callback。 1053 1054**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 1055 1056**参数：** 1057 1058| 参数名 | 类型 | 必填 | 说明 | 1059| -------- | -------- | -------- | -------- | 1060| method | string | 是 | 与客户端约定的通知消息字符串。 | 1061| callback | [CalleeCallback](#calleecallback) | 是 | 一个[rpc.MessageSequence](../apis-ipc-kit/js-apis-rpc.md#messagesequence9)类型入参的js通知同步回调函数, 回调函数至少要返回一个空的[rpc.Parcelable](../apis-ipc-kit/js-apis-rpc.md#parcelable9)数据对象, 其他视为函数执行错误。 | 1062 1063**错误码：** 1064 1065以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 1066 1067| 错误码ID | 错误信息 | 1068| ------- | -------------------------------- | 1069| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1070| 16200004 | The method has been registered. | 1071| 16000050 | Internal error. | 1072 1073**示例：** 1074 1075```ts 1076import { UIAbility, AbilityConstant, Want } from '@kit.AbilityKit'; 1077import { rpc } from '@kit.IPCKit'; 1078 1079class MyMessageAble implements rpc.Parcelable { 1080 name: string 1081 str: string 1082 num: number = 1 1083 constructor(name: string, str: string) { 1084 this.name = name; 1085 this.str = str; 1086 } 1087 marshalling(messageSequence: rpc.MessageSequence) { 1088 messageSequence.writeInt(this.num); 1089 messageSequence.writeString(this.str); 1090 console.log(`MyMessageAble marshalling num[${this.num}] str[${this.str}]`); 1091 return true; 1092 } 1093 unmarshalling(messageSequence: rpc.MessageSequence) { 1094 this.num = messageSequence.readInt(); 1095 this.str = messageSequence.readString(); 1096 console.log(`MyMessageAble unmarshalling num[${this.num}] str[${this.str}]`); 1097 return true; 1098 } 1099}; 1100let method = 'call_Function'; 1101 1102function funcCallBack(pdata: rpc.MessageSequence) { 1103 console.log(`Callee funcCallBack is called ${pdata}`); 1104 let msg = new MyMessageAble('test', ''); 1105 pdata.readParcelable(msg); 1106 return new MyMessageAble('test1', 'Callee test'); 1107} 1108export default class MainUIAbility extends UIAbility { 1109 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 1110 console.log('Callee onCreate is called'); 1111 try { 1112 this.callee.on(method, funcCallBack); 1113 } catch (error) { 1114 console.error(`Callee.on catch error, error.code: ${error.code}, error.message: ${error.message}`); 1115 } 1116 } 1117} 1118``` 1119 1120### Callee.off 1121 1122off(method: string): void 1123 1124解除通用组件服务端注册消息通知callback。 1125 1126**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 1127 1128**参数：** 1129 1130| 参数名 | 类型 | 必填 | 说明 | 1131| -------- | -------- | -------- | -------- | 1132| method | string | 是 | 已注册的通知事件字符串。 | 1133 1134**错误码：** 1135 1136以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 1137 1138| 错误码ID | 错误信息 | 1139| ------- | -------------------------------- | 1140| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1141| 16200005 | The method has not been registered. | 1142| 16000050 | Internal error. | 1143 1144**示例：** 1145 1146```ts 1147import { UIAbility, AbilityConstant, Want } from '@kit.AbilityKit'; 1148 1149let method = 'call_Function'; 1150 1151export default class MainUIAbility extends UIAbility { 1152 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 1153 console.log('Callee onCreate is called'); 1154 try { 1155 this.callee.off(method); 1156 } catch (error) { 1157 console.error(`Callee.off catch error, error.code: ${error.code}, error.message: ${error.message}`); 1158 } 1159 } 1160} 1161``` 1162 1163## OnReleaseCallback 1164 1165### (msg: string) 1166 1167(msg: string): void 1168 1169注册通用组件服务端Stub（桩）断开监听通知的回调函数类型。 1170 1171**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 1172 1173**参数：** 1174 1175| 参数名 | 类型 | 必填 | 说明 | 1176| --- | ----- | --- | -------- | 1177| msg | string | 是 | 用于传递释放消息。 | 1178 1179## OnRemoteStateChangeCallback<sup>10+</sup> 1180 1181### (msg: string) 1182 1183(msg: string): void 1184 1185注册协同场景下跨设备组件状态变化监听通知的回调函数类型。 1186 1187**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 1188 1189**参数：** 1190 1191| 参数名 | 类型 | 必填 | 说明 | 1192| --- | ----- | --- | -------- | 1193| msg | string | 是 | 用于传递释放消息。 | 1194 1195## CalleeCallback 1196 1197### (indata: rpc.MessageSequence) 1198 1199(indata: rpc.MessageSequence): rpc.Parcelable 1200 1201通用组件服务端注册消息通知的回调函数类型。 1202 1203**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore 1204 1205**参数：** 1206 1207| 参数名 | 类型 | 必填 | 说明 | 1208| --- | ----- | --- | -------- | 1209| indata | [rpc.MessageSequence](../apis-ipc-kit/js-apis-rpc.md#messagesequence9) | 是 | 发送需传递的数据。 | 1210 1211**返回值：** 1212 1213| 类型 | 说明 | 1214| ------------ | ------------------------------------- | 1215| [rpc.Parcelable](../apis-ipc-kit/js-apis-rpc.md#parcelable9) | 返回的数据对象。 | 1216