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