1# UIAbilityContext 2 3<!--Kit: Ability Kit--> 4<!--Subsystem: Ability--> 5<!--Owner: @zhu-feimo--> 6<!--Designer: @ccllee1--> 7<!--Tester: @lixueqing513--> 8<!--Adviser: @huipeizi--> 9 10UIAbilityContext是[UIAbility](./js-apis-app-ability-uiAbility.md)组件的上下文，继承自[Context](./js-apis-inner-application-context.md)。各类Context之间的关联与差异详见[应用上下文Context](../../application-models/application-context-stage.md)。 11 12每个UIAbility组件实例化时，系统都会自动创建对应的UIAbilityContext。开发者可以通过UIAbilityContext获取组件信息AbilityInfo、获取应用信息ApplicationInfo、拉起其他UIAbility、连接系统服务、销毁UIAbility等。 13 14> **说明：** 15> 16> - 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 17> - 本模块接口仅可在Stage模型下使用。 18> - 在本文档的示例中，通过`this.context`来获取`UIAbilityContext`，其中`this`代表继承自`UIAbility`的实例。 19 20## 导入模块 21 22```ts 23import { common } from '@kit.AbilityKit'; 24``` 25 26## UIAbilityContext 27 28### 属性 29 30**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 31 32| 名称 | 类型 | 只读 | 可选 | 说明 | 33| -------- | -------- | -------- | -------- | -------- | 34| abilityInfo | [AbilityInfo](js-apis-bundleManager-abilityInfo.md) | 否 | 否 | UIAbility的相关信息。<br>**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 | 35| currentHapModuleInfo | [HapModuleInfo](js-apis-bundleManager-hapModuleInfo.md) | 否 | 否 | 当前UIAbility所属HAP的信息。<br>**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 | 36| config | [Configuration](js-apis-app-ability-configuration.md) | 否 | 否 | 与UIAbility相关的配置信息，如语言、颜色模式等。<br>**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 | 37| windowStage<sup>12+</sup> | [window.WindowStage](../apis-arkui/arkts-apis-window-WindowStage.md) | 否 | 否 | 当前WindowStage对象。仅支持在主线程调用。<br>**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。| 38 39### startAbility 40 41startAbility(want: Want, callback: AsyncCallback<void>): void 42 43启动一个Ability。使用callback异步回调。仅支持在主线程调用。 44 45> **说明：** 46> 47> 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md)。 48 49**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 50 51**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 52 53**参数：** 54 55| 参数名 | 类型 | 必填 | 说明 | 56| -------- | -------- | -------- | -------- | 57| want | [Want](js-apis-app-ability-want.md) | 是 | 启动Ability的必要信息。 | 58| callback | AsyncCallback<void> | 是 | callback形式返回启动结果。 | 59 60**错误码：** 61 62以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 63 64| 错误码ID | 错误信息 | 65| ------- | -------------------------------- | 66| 201 | The application does not have permission to call the interface. | 67| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 68| 16000001 | The specified ability does not exist. | 69| 16000002 | Incorrect ability type. | 70| 16000004 | Cannot start an invisible component. | 71| 16000005 | The specified process does not have the permission. | 72| 16000006 | Cross-user operations are not allowed. | 73| 16000008 | The crowdtesting application expires. | 74| 16000009 | An ability cannot be started or stopped in Wukong mode. | 75| 16000010 | The call with the continuation and prepare continuation flag is forbidden. | 76| 16000011 | The context does not exist. | 77| 16000012 | The application is controlled. | 78| 16000013 | The application is controlled by EDM. | 79| 16000018 | Redirection to a third-party application is not allowed in API version greater than 11. | 80| 16000019 | No matching ability is found. | 81| 16000050 | Internal error. | 82| 16000053 | The ability is not on the top of the UI. | 83| 16000055 | Installation-free timed out. | 84| 16000071 | App clone is not supported. | 85| 16000072 | App clone or multi-instance is not supported. | 86| 16000073 | The app clone index is invalid. | 87| 16000076 | The app instance key is invalid. | 88| 16000077 | The number of app instances reaches the limit. | 89| 16000078 | The multi-instance is not supported. | 90| 16000079 | The APP_INSTANCE_KEY cannot be specified. | 91| 16000080 | Creating a new instance is not supported. | 92| 16200001 | The caller has been released. | 93 94**示例：** 95 96```ts 97import { UIAbility, Want } from '@kit.AbilityKit'; 98import { BusinessError } from '@kit.BasicServicesKit'; 99 100export default class EntryAbility extends UIAbility { 101 onForeground() { 102 let want: Want = { 103 bundleName: 'com.example.myapplication', 104 abilityName: 'EntryAbility' 105 }; 106 107 try { 108 this.context.startAbility(want, (err: BusinessError) => { 109 if (err.code) { 110 // 处理业务逻辑错误 111 console.error(`startAbility failed, code is ${err.code}, message is ${err.message}`); 112 return; 113 } 114 // 执行正常业务 115 console.info('startAbility succeed'); 116 }); 117 } catch (err) { 118 // 处理入参错误异常 119 let code = (err as BusinessError).code; 120 let message = (err as BusinessError).message; 121 console.error(`startAbility failed, code is ${code}, message is ${message}`); 122 } 123 } 124} 125``` 126 127### startAbility 128 129startAbility(want: Want, options: StartOptions, callback: AsyncCallback<void>): void 130 131启动一个Ability。使用callback异步回调。仅支持在主线程调用。 132 133> **说明：** 134> 135> 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md)。 136 137**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 138 139**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 140 141**参数：** 142 143| 参数名 | 类型 | 必填 | 说明 | 144| -------- | -------- | -------- | -------- | 145| want | [Want](js-apis-app-ability-want.md) | 是 | 启动Ability的必要信息。 | 146| options | [StartOptions](js-apis-app-ability-startOptions.md) | 是 | 启动Ability所携带的参数。 | 147| callback | AsyncCallback<void> | 是 | callback形式返回启动结果。 | 148 149**错误码：** 150 151以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 152 153| 错误码ID | 错误信息 | 154| ------- | -------------------------------- | 155| 201 | The application does not have permission to call the interface. | 156| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 157| 801 | Capability not support. | 158| 16000001 | The specified ability does not exist. | 159| 16000004 | Cannot start an invisible component. | 160| 16000005 | The specified process does not have the permission. | 161| 16000006 | Cross-user operations are not allowed. | 162| 16000008 | The crowdtesting application expires. | 163| 16000009 | An ability cannot be started or stopped in Wukong mode. | 164| 16000011 | The context does not exist. | 165| 16000012 | The application is controlled. | 166| 16000013 | The application is controlled by EDM. | 167| 16000018 | Redirection to a third-party application is not allowed in API version greater than 11. | 168| 16000019 | No matching ability is found. | 169| 16000050 | Internal error. | 170| 16000053 | The ability is not on the top of the UI. | 171| 16000055 | Installation-free timed out. | 172| 16000067 | The StartOptions check failed. | 173| 16000068 | The ability is already running. | 174| 16300003 | The target application is not the current application. | 175| 16000071 | App clone is not supported. | 176| 16000072 | App clone or multi-instance is not supported. | 177| 16000073 | The app clone index is invalid. | 178| 16000076 | The app instance key is invalid. | 179| 16000077 | The number of app instances reaches the limit. | 180| 16000078 | The multi-instance is not supported. | 181| 16000079 | The APP_INSTANCE_KEY cannot be specified. | 182| 16000080 | Creating a new instance is not supported. | 183| 16200001 | The caller has been released. | 184 185**示例：** 186 187```ts 188import { UIAbility, Want, StartOptions } from '@kit.AbilityKit'; 189import { BusinessError } from '@kit.BasicServicesKit'; 190 191export default class EntryAbility extends UIAbility { 192 onForeground() { 193 let want: Want = { 194 deviceId: '', 195 bundleName: 'com.example.myapplication', 196 abilityName: 'EntryAbility' 197 }; 198 let options: StartOptions = { 199 displayId: 0 200 }; 201 202 try { 203 this.context.startAbility(want, options, (err: BusinessError) => { 204 if (err.code) { 205 // 处理业务逻辑错误 206 console.error(`startAbility failed, code is ${err.code}, message is ${err.message}`); 207 return; 208 } 209 // 执行正常业务 210 console.info('startAbility succeed'); 211 }); 212 } catch (err) { 213 // 处理入参错误异常 214 let code = (err as BusinessError).code; 215 let message = (err as BusinessError).message; 216 console.error(`startAbility failed, code is ${code}, message is ${message}`); 217 } 218 } 219} 220``` 221 222### startAbility 223 224startAbility(want: Want, options?: StartOptions): Promise<void> 225 226启动一个Ability。使用Promise异步回调。仅支持在主线程调用。 227 228> **说明：** 229> 230> 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md)。 231 232**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 233 234**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 235 236**参数：** 237 238| 参数名 | 类型 | 必填 | 说明 | 239| -------- | -------- | -------- | -------- | 240| want | [Want](js-apis-app-ability-want.md) | 是 | 启动Ability的必要信息。 | 241| options | [StartOptions](js-apis-app-ability-startOptions.md) | 否 | 启动Ability所携带的参数。 | 242 243**返回值：** 244 245| 类型 | 说明 | 246| -------- | -------- | 247| Promise<void> | Promise对象，包含接口执行结果。 | 248 249**错误码：** 250 251以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 252 253| 错误码ID | 错误信息 | 254| ------- | -------------------------------- | 255| 201 | The application does not have permission to call the interface. | 256| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 257| 801 | Capability not support. | 258| 16000001 | The specified ability does not exist. | 259| 16000002 | Incorrect ability type. | 260| 16000004 | Cannot start an invisible component. | 261| 16000005 | The specified process does not have the permission. | 262| 16000006 | Cross-user operations are not allowed. | 263| 16000008 | The crowdtesting application expires. | 264| 16000009 | An ability cannot be started or stopped in Wukong mode. | 265| 16000010 | The call with the continuation and prepare continuation flag is forbidden. | 266| 16000011 | The context does not exist. | 267| 16000012 | The application is controlled. | 268| 16000013 | The application is controlled by EDM. | 269| 16000018 | Redirection to a third-party application is not allowed in API version greater than 11. | 270| 16000019 | No matching ability is found. | 271| 16000050 | Internal error. | 272| 16000053 | The ability is not on the top of the UI. | 273| 16000055 | Installation-free timed out. | 274| 16000067 | The StartOptions check failed. | 275| 16000068 | The ability is already running. | 276| 16300003 | The target application is not the current application. | 277| 16000071 | App clone is not supported. | 278| 16000072 | App clone or multi-instance is not supported. | 279| 16000073 | The app clone index is invalid. | 280| 16000076 | The app instance key is invalid. | 281| 16000077 | The number of app instances reaches the limit. | 282| 16000078 | The multi-instance is not supported. | 283| 16000079 | The APP_INSTANCE_KEY cannot be specified. | 284| 16000080 | Creating a new instance is not supported. | 285| 16200001 | The caller has been released. | 286 287**示例：** 288 289```ts 290import { UIAbility, Want, StartOptions } from '@kit.AbilityKit'; 291import { BusinessError } from '@kit.BasicServicesKit'; 292 293export default class EntryAbility extends UIAbility { 294 onForeground() { 295 let want: Want = { 296 bundleName: 'com.example.myapplication', 297 abilityName: 'EntryAbility' 298 }; 299 let options: StartOptions = { 300 displayId: 0 301 }; 302 303 try { 304 this.context.startAbility(want, options) 305 .then(() => { 306 // 执行正常业务 307 console.info('startAbility succeed'); 308 }) 309 .catch((err: BusinessError) => { 310 // 处理业务逻辑错误 311 console.error(`startAbility failed, code is ${err.code}, message is ${err.message}`); 312 }); 313 } catch (err) { 314 // 处理入参错误异常 315 let code = (err as BusinessError).code; 316 let message = (err as BusinessError).message; 317 console.error(`startAbility failed, code is ${code}, message is ${message}`); 318 } 319 } 320} 321``` 322 323### startAbilityForResult 324 325startAbilityForResult(want: Want, callback: AsyncCallback<AbilityResult>): void 326 327启动一个UIAbility，并通过回调函数接收被拉起的UIAbility退出时的返回结果。使用callback异步回调。仅支持在主线程调用。 328 329UIAbility被启动后，有如下情况： 330 - 正常情况下可通过调用[terminateSelfWithResult](#terminateselfwithresult)接口使之终止并且返回结果给调用方。 331 - 异常情况下比如杀死UIAbility会返回异常信息给调用方，异常信息中resultCode为-1。 332 - 如果被启动的UIAbility模式是单实例模式，不同应用多次调用该接口启动这个UIAbility，当这个UIAbility调用[terminateSelfWithResult](#terminateselfwithresult)接口使之终止时，只将正常结果返回给最后一个调用方，其它调用方返回异常信息，异常信息中resultCode为-1。 333 334> **说明：** 335> 336> 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md)。 337 338**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 339 340**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 341 342**参数：** 343 344| 参数名 | 类型 | 必填 | 说明 | 345| -------- | -------- | -------- | -------- | 346| want |[Want](js-apis-app-ability-want.md) | 是 | 启动Ability的必要信息。 | 347| callback | AsyncCallback<[AbilityResult](js-apis-inner-ability-abilityResult.md)> | 是 | 回调函数，包含返回给拉起方的信息。 | 348 349**错误码：** 350 351以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 352 353| 错误码ID | 错误信息 | 354| ------- | -------------------------------- | 355| 201 | The application does not have permission to call the interface. | 356| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 357| 16000001 | The specified ability does not exist. | 358| 16000002 | Incorrect ability type. | 359| 16000004 | Cannot start an invisible component. | 360| 16000005 | The specified process does not have the permission. | 361| 16000006 | Cross-user operations are not allowed. | 362| 16000008 | The crowdtesting application expires. | 363| 16000009 | An ability cannot be started or stopped in Wukong mode. | 364| 16000010 | The call with the continuation and prepare continuation flag is forbidden. | 365| 16000011 | The context does not exist. | 366| 16000012 | The application is controlled. | 367| 16000013 | The application is controlled by EDM. | 368| 16000018 | Redirection to a third-party application is not allowed in API version greater than 11. | 369| 16000019 | No matching ability is found. | 370| 16000050 | Internal error. | 371| 16000053 | The ability is not on the top of the UI. | 372| 16000055 | Installation-free timed out. | 373| 16000071 | App clone is not supported. | 374| 16000072 | App clone or multi-instance is not supported. | 375| 16000073 | The app clone index is invalid. | 376| 16000076 | The app instance key is invalid. | 377| 16000077 | The number of app instances reaches the limit. | 378| 16000078 | The multi-instance is not supported. | 379| 16000079 | The APP_INSTANCE_KEY cannot be specified. | 380| 16000080 | Creating a new instance is not supported. | 381| 16200001 | The caller has been released. | 382 383**示例：** 384 385```ts 386import { UIAbility, Want, common } from '@kit.AbilityKit'; 387import { BusinessError } from '@kit.BasicServicesKit'; 388 389export default class EntryAbility extends UIAbility { 390 onForeground() { 391 let want: Want = { 392 deviceId: '', 393 bundleName: 'com.example.myapplication', 394 abilityName: 'EntryAbility' 395 }; 396 397 try { 398 this.context.startAbilityForResult(want, (err: BusinessError, result: common.AbilityResult) => { 399 if (err.code) { 400 // 处理业务逻辑错误 401 console.error(`startAbilityForResult failed, code is ${err.code}, message is ${err.message}`); 402 return; 403 } 404 // 执行正常业务 405 console.info('startAbilityForResult succeed'); 406 }); 407 } catch (err) { 408 // 处理入参错误异常 409 let code = (err as BusinessError).code; 410 let message = (err as BusinessError).message; 411 console.error(`startAbilityForResult failed, code is ${code}, message is ${message}`); 412 } 413 } 414} 415``` 416 417### startAbilityForResult 418 419startAbilityForResult(want: Want, options: StartOptions, callback: AsyncCallback<AbilityResult>): void 420 421启动一个UIAbility，并通过回调函数接收被拉起的UIAbility退出时的返回结果。使用callback异步回调。仅支持在主线程调用。 422 423UIAbility被启动后，有如下情况： 424 - 正常情况下可通过调用[terminateSelfWithResult](#terminateselfwithresult)接口使之终止并且返回结果给调用方。 425 - 异常情况下比如杀死UIAbility会返回异常信息给调用方，异常信息中resultCode为-1。 426 - 如果被启动的UIAbility模式是单实例模式，不同应用多次调用该接口启动这个UIAbility，当这个UIAbility调用[terminateSelfWithResult](#terminateselfwithresult)接口使之终止时，只将正常结果返回给最后一个调用方，其它调用方返回异常信息，异常信息中resultCode为-1。 427 428> **说明：** 429> 430> 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md)。 431 432**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 433 434**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 435 436**参数：** 437 438| 参数名 | 类型 | 必填 | 说明 | 439| -------- | -------- | -------- | -------- | 440| want |[Want](js-apis-app-ability-want.md) | 是 | 启动Ability的必要信息。 | 441| options | [StartOptions](js-apis-app-ability-startOptions.md) | 是 | 启动Ability所携带的参数。 | 442| callback | AsyncCallback<[AbilityResult](js-apis-inner-ability-abilityResult.md)> | 是 | 回调函数，包含返回给拉起方的信息。 | 443 444**错误码：** 445 446以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 447 448| 错误码ID | 错误信息 | 449| ------- | -------------------------------- | 450| 201 | The application does not have permission to call the interface. | 451| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 452| 16000001 | The specified ability does not exist. | 453| 16000004 | Cannot start an invisible component. | 454| 16000005 | The specified process does not have the permission. | 455| 16000006 | Cross-user operations are not allowed. | 456| 16000008 | The crowdtesting application expires. | 457| 16000009 | An ability cannot be started or stopped in Wukong mode. | 458| 16000011 | The context does not exist. | 459| 16000012 | The application is controlled. | 460| 16000013 | The application is controlled by EDM. | 461| 16000018 | Redirection to a third-party application is not allowed in API version greater than 11. | 462| 16000019 | No matching ability is found. | 463| 16000050 | Internal error. | 464| 16000053 | The ability is not on the top of the UI. | 465| 16000055 | Installation-free timed out. | 466| 16000071 | App clone is not supported. | 467| 16000072 | App clone or multi-instance is not supported. | 468| 16000073 | The app clone index is invalid. | 469| 16000076 | The app instance key is invalid. | 470| 16000077 | The number of app instances reaches the limit. | 471| 16000078 | The multi-instance is not supported. | 472| 16000079 | The APP_INSTANCE_KEY cannot be specified. | 473| 16000080 | Creating a new instance is not supported. | 474| 16200001 | The caller has been released. | 475 476**示例：** 477 478```ts 479import { UIAbility, Want, common, StartOptions } from '@kit.AbilityKit'; 480import { BusinessError } from '@kit.BasicServicesKit'; 481 482export default class EntryAbility extends UIAbility { 483 onForeground() { 484 let want: Want = { 485 deviceId: '', 486 bundleName: 'com.example.myapplication', 487 abilityName: 'EntryAbility' 488 }; 489 let options: StartOptions = { 490 displayId: 0 491 }; 492 493 try { 494 this.context.startAbilityForResult(want, options, (err: BusinessError, result: common.AbilityResult) => { 495 if (err.code) { 496 // 处理业务逻辑错误 497 console.error(`startAbilityForResult failed, code is ${err.code}, message is ${err.message}`); 498 return; 499 } 500 // 执行正常业务 501 console.info('startAbilityForResult succeed'); 502 }); 503 } catch (err) { 504 // 处理入参错误异常 505 let code = (err as BusinessError).code; 506 let message = (err as BusinessError).message; 507 console.error(`startAbilityForResult failed, code is ${code}, message is ${message}`); 508 } 509 } 510} 511``` 512 513 514### startAbilityForResult 515 516startAbilityForResult(want: Want, options?: StartOptions): Promise<AbilityResult> 517 518启动一个UIAbility，并通过回调函数接收被拉起的UIAbility退出时的返回结果。使用Promise异步回调。仅支持在主线程调用。 519 520UIAbility被启动后，有如下情况： 521 - 正常情况下可通过调用[terminateSelfWithResult](#terminateselfwithresult)接口使之终止并且返回结果给调用方。 522 - 异常情况下比如杀死UIAbility会返回异常信息给调用方，异常信息中resultCode为-1。 523 - 如果被启动的UIAbility模式是单实例模式，不同应用多次调用该接口启动这个UIAbility，当这个UIAbility调用[terminateSelfWithResult](#terminateselfwithresult)接口使之终止时，只将正常结果返回给最后一个调用方，其它调用方返回异常信息，异常信息中resultCode为-1。 524 525> **说明：** 526> 527> 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md)。 528 529**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 530 531**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 532 533**参数：** 534 535| 参数名 | 类型 | 必填 | 说明 | 536| -------- | -------- | -------- | -------- | 537| want | [Want](js-apis-app-ability-want.md) | 是 | 启动Ability的必要信息。 | 538| options | [StartOptions](js-apis-app-ability-startOptions.md) | 否 | 启动Ability所携带的参数。 | 539 540 541**返回值：** 542 543| 类型 | 说明 | 544| -------- | -------- | 545| Promise<[AbilityResult](js-apis-inner-ability-abilityResult.md)> | Promise对象，包含返回给拉起方的信息。 | 546 547**错误码：** 548 549以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 550 551| 错误码ID | 错误信息 | 552| ------- | -------------------------------- | 553| 201 | The application does not have permission to call the interface. | 554| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 555| 16000001 | The specified ability does not exist. | 556| 16000002 | Incorrect ability type. | 557| 16000004 | Cannot start an invisible component. | 558| 16000005 | The specified process does not have the permission. | 559| 16000006 | Cross-user operations are not allowed. | 560| 16000008 | The crowdtesting application expires. | 561| 16000009 | An ability cannot be started or stopped in Wukong mode. | 562| 16000010 | The call with the continuation and prepare continuation flag is forbidden. | 563| 16000011 | The context does not exist. | 564| 16000012 | The application is controlled. | 565| 16000013 | The application is controlled by EDM. | 566| 16000018 | Redirection to a third-party application is not allowed in API version greater than 11. | 567| 16000019 | No matching ability is found. | 568| 16000050 | Internal error. | 569| 16000053 | The ability is not on the top of the UI. | 570| 16000055 | Installation-free timed out. | 571| 16000071 | App clone is not supported. | 572| 16000072 | App clone or multi-instance is not supported. | 573| 16000073 | The app clone index is invalid. | 574| 16000076 | The app instance key is invalid. | 575| 16000077 | The number of app instances reaches the limit. | 576| 16000078 | The multi-instance is not supported. | 577| 16000079 | The APP_INSTANCE_KEY cannot be specified. | 578| 16000080 | Creating a new instance is not supported. | 579| 16200001 | The caller has been released. | 580 581**示例：** 582 583```ts 584import { UIAbility, Want, common, StartOptions } from '@kit.AbilityKit'; 585import { BusinessError } from '@kit.BasicServicesKit'; 586 587export default class EntryAbility extends UIAbility { 588 onForeground() { 589 let want: Want = { 590 bundleName: 'com.example.myapplication', 591 abilityName: 'EntryAbility' 592 }; 593 let options: StartOptions = { 594 displayId: 0 595 }; 596 597 try { 598 this.context.startAbilityForResult(want, options) 599 .then((result: common.AbilityResult) => { 600 // 执行正常业务 601 console.info('startAbilityForResult succeed'); 602 }) 603 .catch((err: BusinessError) => { 604 // 处理业务逻辑错误 605 console.error(`startAbilityForResult failed, code is ${err.code}, message is ${err.message}`); 606 }); 607 } catch (err) { 608 // 处理入参错误异常 609 let code = (err as BusinessError).code; 610 let message = (err as BusinessError).message; 611 console.error(`startAbilityForResult failed, code is ${code}, message is ${message}`); 612 } 613 } 614} 615``` 616 617### terminateSelf 618 619terminateSelf(callback: AsyncCallback<void>): void 620 621销毁UIAbility自身。使用callback异步回调。仅支持在主线程调用。 622 623> **说明：** 624> 625> 调用该接口后，任务中心的任务默认不会清理，如需清理，需要配置[removeMissionAfterTerminate](../../quick-start/module-configuration-file.md#abilities标签)为true。 626 627**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 628 629**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 630 631**参数：** 632 633| 参数名 | 类型 | 必填 | 说明 | 634| -------- | -------- | -------- | -------- | 635| callback | AsyncCallback<void> | 是 | 回调函数，包含接口执行结果。 | 636 637**错误码：** 638 639以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 640 641| 错误码ID | 错误信息 | 642| ------- | -------------------------------- | 643| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 644| 16000009 | An ability cannot be started or stopped in Wukong mode. | 645| 16000011 | The context does not exist. | 646| 16000050 | Internal error. | 647 648**示例：** 649 6501. 使用terminateSelf接口停止UIAbility示例代码如下，默认情况下应用会在最近任务列表中保留快照。 651 652 ```ts 653 import { UIAbility } from '@kit.AbilityKit'; 654 import { BusinessError } from '@kit.BasicServicesKit'; 655 656 export default class EntryAbility extends UIAbility { 657 onForeground() { 658 try { 659 this.context.terminateSelf((err: BusinessError) => { 660 if (err.code) { 661 // 处理业务逻辑错误 662 console.error(`terminateSelf failed, code is ${err.code}, message is ${err.message}`); 663 return; 664 } 665 // 执行正常业务 666 console.info('terminateSelf succeed'); 667 }); 668 } catch (err) { 669 // 捕获同步的参数错误 670 let code = (err as BusinessError).code; 671 let message = (err as BusinessError).message; 672 console.error(`terminateSelf failed, code is ${code}, message is ${message}`); 673 } 674 } 675 } 676 ``` 677 6782. （可选）如果需要在停止UIAbility时，清理任务中心的相关任务（即不保留最近任务列表中的快照），需要在[module.json5](../../quick-start/module-configuration-file.md)配置文件中将removeMissionAfterTerminate字段取值配置为true。 679 680 ```json 681 { 682 "module": { 683 // ... 684 "abilities": [ 685 { 686 // ... 687 "removeMissionAfterTerminate": true 688 } 689 ] 690 } 691 } 692 ``` 693 694### terminateSelf 695 696terminateSelf(): Promise<void> 697 698销毁UIAbility自身。使用Promise异步回调。仅支持在主线程调用。 699 700> **说明：** 701> 702> 调用该接口后，任务中心的任务默认不会清理，如需清理，需要配置[removeMissionAfterTerminate](../../quick-start/module-configuration-file.md#abilities标签)为true。 703 704**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 705 706**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 707 708**返回值：** 709 710| 类型 | 说明 | 711| -------- | -------- | 712| Promise<void> | Promise对象，包含接口执行结果。 | 713 714**错误码：** 715 716以下错误码详细介绍请参考[元能力子系统错误码](errorcode-ability.md)。 717 718| 错误码ID | 错误信息 | 719| ------- | -------------------------------- | 720| 16000009 | An ability cannot be started or stopped in Wukong mode. | 721| 16000011 | The context does not exist. | 722| 16000050 | Internal error. | 723 724 725**示例：** 726 7271. 使用terminateSelf接口停止UIAbility示例代码如下，默认情况下应用会在最近任务列表中保留快照。 728 729 ```ts 730 import { UIAbility } from '@kit.AbilityKit'; 731 import { BusinessError } from '@kit.BasicServicesKit'; 732 733 export default class EntryAbility extends UIAbility { 734 onForeground() { 735 try { 736 this.context.terminateSelf() 737 .then(() => { 738 // 执行正常业务 739 console.info('terminateSelf succeed'); 740 }) 741 .catch((err: BusinessError) => { 742 // 处理业务逻辑错误 743 console.error(`terminateSelf failed, code is ${err.code}, message is ${err.message}`); 744 }); 745 } catch (err) { 746 // 捕获同步的参数错误 747 let code = (err as BusinessError).code; 748 let message = (err as BusinessError).message; 749 console.error(`terminateSelf failed, code is ${code}, message is ${message}`); 750 } 751 } 752 } 753 ``` 754 7552. （可选）如果需要在停止UIAbility时，清理任务中心的相关任务（即不保留最近任务列表中的快照），需要在[module.json5](../../quick-start/module-configuration-file.md)配置文件中将removeMissionAfterTerminate字段取值配置为true。 756 757 ```json 758 { 759 "module": { 760 // ... 761 "abilities": [ 762 { 763 // ... 764 "removeMissionAfterTerminate": true 765 } 766 ] 767 } 768 } 769 ``` 770 771### terminateSelfWithResult 772 773terminateSelfWithResult(parameter: AbilityResult, callback: AsyncCallback<void>): void 774 775销毁UIAbility自身。使用callback异步回调。仅支持在主线程调用。 776 777仅当UIAbility通过[startAbilityForResult](#startabilityforresult)接口拉起时，调用terminateSelfWithResult接口销毁UIAbility，才会返回结果给调用方。 778 779> **说明：** 780> 781> 调用该接口后，任务中心的任务默认不会清理，如需清理，需要配置[removeMissionAfterTerminate](../../quick-start/module-configuration-file.md#abilities标签)为true。 782 783**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 784 785**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 786 787**参数：** 788 789| 参数名 | 类型 | 必填 | 说明 | 790| -------- | -------- | -------- | -------- | 791| parameter | [AbilityResult](js-apis-inner-ability-abilityResult.md) | 是 | 返回给startAbilityForResult 接口调用方的相关信息。 | 792| callback | AsyncCallback<void> | 是 | callback形式返回停止结果。 | 793 794**错误码：** 795 796以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 797 798| 错误码ID | 错误信息 | 799| ------- | -------------------------------- | 800| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 801| 16000009 | An ability cannot be started or stopped in Wukong mode. | 802| 16000011 | The context does not exist. | 803| 16000050 | Internal error. | 804 805 806**示例：** 807 808```ts 809import { UIAbility, Want, common } from '@kit.AbilityKit'; 810import { BusinessError } from '@kit.BasicServicesKit'; 811 812export default class EntryAbility extends UIAbility { 813 onForeground() { 814 let want: Want = { 815 bundleName: 'com.example.myapplication', 816 abilityName: 'EntryAbility' 817 }; 818 let resultCode = 100; 819 // 返回给接口调用方AbilityResult信息 820 let abilityResult: common.AbilityResult = { 821 want, 822 resultCode 823 }; 824 825 try { 826 this.context.terminateSelfWithResult(abilityResult, (err: BusinessError) => { 827 if (err.code) { 828 // 处理业务逻辑错误 829 console.error(`terminateSelfWithResult failed, code is ${err.code}, message is ${err.message}`); 830 return; 831 } 832 // 执行正常业务 833 console.info('terminateSelfWithResult succeed'); 834 }); 835 } catch (err) { 836 // 处理入参错误异常 837 let code = (err as BusinessError).code; 838 let message = (err as BusinessError).message; 839 console.error(`terminateSelfWithResult failed, code is ${code}, message is ${message}`); 840 } 841 } 842} 843``` 844 845 846### terminateSelfWithResult 847 848terminateSelfWithResult(parameter: AbilityResult): Promise<void> 849 850销毁UIAbility自身。使用Promise异步回调。仅支持在主线程调用。 851 852仅当UIAbility通过[startAbilityForResult](#startabilityforresult)接口拉起时，调用terminateSelfWithResult接口销毁UIAbility，才会返回结果给调用方。 853 854> **说明：** 855> 856> 调用该接口后，任务中心的任务默认不会清理，如需清理，需要配置[removeMissionAfterTerminate](../../quick-start/module-configuration-file.md#abilities标签)为true。 857 858**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 859 860**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 861 862**参数：** 863 864| 参数名 | 类型 | 必填 | 说明 | 865| -------- | -------- | -------- | -------- | 866| parameter | [AbilityResult](js-apis-inner-ability-abilityResult.md) | 是 | 返回给startAbilityForResult 接口调用方的信息。 | 867 868**返回值：** 869 870| 类型 | 说明 | 871| -------- | -------- | 872| Promise<void> | Promise对象，包含接口执行结果。 | 873 874**错误码：** 875 876以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 877 878| 错误码ID | 错误信息 | 879| ------- | -------------------------------- | 880| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 881| 16000009 | An ability cannot be started or stopped in Wukong mode. | 882| 16000011 | The context does not exist. | 883| 16000050 | Internal error. | 884 885 886**示例：** 887 888```ts 889import { UIAbility, Want, common } from '@kit.AbilityKit'; 890import { BusinessError } from '@kit.BasicServicesKit'; 891 892export default class EntryAbility extends UIAbility { 893 onForeground() { 894 let want: Want = { 895 bundleName: 'com.example.myapplication', 896 abilityName: 'EntryAbility' 897 }; 898 let resultCode = 100; 899 // 返回给接口调用方AbilityResult信息 900 let abilityResult: common.AbilityResult = { 901 want, 902 resultCode 903 }; 904 905 try { 906 this.context.terminateSelfWithResult(abilityResult) 907 .then(() => { 908 // 执行正常业务 909 console.info('terminateSelfWithResult succeed'); 910 }) 911 .catch((err: BusinessError) => { 912 // 处理业务逻辑错误 913 console.error(`terminateSelfWithResult failed, code is ${err.code}, message is ${err.message}`); 914 }); 915 } catch (err) { 916 // 处理入参错误异常 917 let code = (err as BusinessError).code; 918 let message = (err as BusinessError).message; 919 console.error(`terminateSelfWithResult failed, code is ${code}, message is ${message}`); 920 } 921 } 922} 923``` 924 925### connectServiceExtensionAbility 926 927connectServiceExtensionAbility(want: Want, options: ConnectOptions): number 928 929将当前UIAbility连接到一个[ServiceExtensionAbility](../../application-models/extensionability-overview.md)，通过返回的proxy与ServiceExtensionAbility进行通信，以使用ServiceExtensionAbility对外提供的能力。仅支持在主线程调用。 930 931> **说明：** 932> 933> 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md)。 934 935**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 936 937**参数：** 938 939| 参数名 | 类型 | 必填 | 说明 | 940| -------- | -------- | -------- | -------- | 941| want | [Want](js-apis-app-ability-want.md) | 是 | 连接ServiceExtensionAbility的want信息。 | 942| options | [ConnectOptions](js-apis-inner-ability-connectOptions.md) | 是 | 回调对象，返回服务连接成功、连接失败、断开的信息。 | 943 944**返回值：** 945 946| 类型 | 说明 | 947| -------- | -------- | 948| number | 返回连接id，调用方可以通过[disconnectServiceExtensionAbility](#disconnectserviceextensionability)传入该连接id来断开连接。 | 949 950**错误码：** 951 952以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 953 954| 错误码ID | 错误信息 | 955| ------- | -------------------------------- | 956| 201 | The application does not have permission to call the interface. | 957| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 958| 16000001 | The specified ability does not exist. | 959| 16000002 | Incorrect ability type. | 960| 16000004 | Cannot start an invisible component. | 961| 16000005 | The specified process does not have the permission. | 962| 16000006 | Cross-user operations are not allowed. | 963| 16000008 | The crowdtesting application expires. | 964| 16000011 | The context does not exist. | 965| 16000050 | Internal error. | 966| 16000053 | The ability is not on the top of the UI. | 967| 16000055 | Installation-free timed out. | 968 969**示例：** 970 971```ts 972import { UIAbility, Want, common } from '@kit.AbilityKit'; 973import { rpc } from '@kit.IPCKit'; 974import { BusinessError } from '@kit.BasicServicesKit'; 975 976export default class EntryAbility extends UIAbility { 977 onForeground() { 978 let want: Want = { 979 deviceId: '', 980 bundleName: 'com.example.myapplication', 981 abilityName: 'ServiceExtensionAbility' 982 }; 983 let commRemote: rpc.IRemoteObject; 984 let options: common.ConnectOptions = { 985 onConnect(elementName, remote) { 986 commRemote = remote; 987 console.info('onConnect...'); 988 }, 989 onDisconnect(elementName) { 990 console.info('onDisconnect...'); 991 }, 992 onFailed(code) { 993 console.info('onFailed...'); 994 } 995 }; 996 let connection: number; 997 998 try { 999 connection = this.context.connectServiceExtensionAbility(want, options); 1000 } catch (err) { 1001 // 处理入参错误异常 1002 let code = (err as BusinessError).code; 1003 let message = (err as BusinessError).message; 1004 console.error(`connectServiceExtensionAbility failed, code is ${code}, message is ${message}`); 1005 } 1006 } 1007} 1008``` 1009 1010### disconnectServiceExtensionAbility 1011 1012disconnectServiceExtensionAbility(connection: number): Promise\<void> 1013 1014断开与[ServiceExtensionAbility](../../application-models/extensionability-overview.md)的连接，断开连接之后开发者需要将连接成功时返回的remote对象置空。使用Promise异步回调。仅支持在主线程调用。 1015 1016**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 1017 1018**参数：** 1019 1020| 参数名 | 类型 | 必填 | 说明 | 1021| -------- | -------- | -------- | -------- | 1022| connection | number | 是 | 连接的ServiceExtensionAbility的标识id，即[connectServiceExtensionAbility](#connectserviceextensionability)返回的connectionId。 | 1023 1024**返回值：** 1025 1026| 类型 | 说明 | 1027| -------- | -------- | 1028| Promise\<void> | 无返回结果的Promise对象。 | 1029 1030**错误码：** 1031 1032以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 1033 1034| 错误码ID | 错误信息 | 1035| ------- | -------------------------------- | 1036| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 1037| 16000011 | The context does not exist. | 1038| 16000050 | Internal error. | 1039 1040**示例：** 1041 1042```ts 1043import { UIAbility } from '@kit.AbilityKit'; 1044import { rpc } from '@kit.IPCKit'; 1045import { BusinessError } from '@kit.BasicServicesKit'; 1046 1047export default class EntryAbility extends UIAbility { 1048 onForeground() { 1049 // connection为connectServiceExtensionAbility中的返回值 1050 let connection = 1; 1051 let commRemote: rpc.IRemoteObject | null; 1052 1053 try { 1054 this.context.disconnectServiceExtensionAbility(connection).then(() => { 1055 commRemote = null; 1056 // 执行正常业务 1057 console.info('disconnectServiceExtensionAbility succeed'); 1058 }).catch((err: BusinessError) => { 1059 // 处理业务逻辑错误 1060 console.error(`disconnectServiceExtensionAbility failed, code is ${err.code}, message is ${err.message}`); 1061 }); 1062 } catch (err) { 1063 commRemote = null; 1064 // 处理入参错误异常 1065 let code = (err as BusinessError).code; 1066 let message = (err as BusinessError).message; 1067 console.error(`disconnectServiceExtensionAbility failed, code is ${code}, message is ${message}`); 1068 } 1069 } 1070} 1071``` 1072 1073### disconnectServiceExtensionAbility 1074 1075disconnectServiceExtensionAbility(connection: number, callback: AsyncCallback\<void>): void 1076 1077断开与[ServiceExtensionAbility](../../application-models/extensionability-overview.md)的连接，断开连接之后开发者需要将连接成功时返回的remote对象置空。使用callback异步回调。仅支持在主线程调用。 1078 1079**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 1080 1081**参数：** 1082 1083| 参数名 | 类型 | 必填 | 说明 | 1084| -------- | -------- | -------- | -------- | 1085| connection | number | 是 | 连接的ServiceExtensionAbility的标识id，即[connectServiceExtensionAbility](#connectserviceextensionability)返回的connectionId。 | 1086| callback | AsyncCallback\<void> | 是 | callback形式返回断开连接的结果。 | 1087 1088**错误码：** 1089 1090以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 1091 1092| 错误码ID | 错误信息 | 1093| ------- | -------------------------------- | 1094| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 1095| 16000011 | The context does not exist. | 1096| 16000050 | Internal error. | 1097 1098**示例：** 1099 1100```ts 1101import { UIAbility } from '@kit.AbilityKit'; 1102import { rpc } from '@kit.IPCKit'; 1103import { BusinessError } from '@kit.BasicServicesKit'; 1104 1105export default class EntryAbility extends UIAbility { 1106 onForeground() { 1107 // connection为connectServiceExtensionAbility中的返回值 1108 let connection = 1; 1109 let commRemote: rpc.IRemoteObject | null; 1110 1111 try { 1112 this.context.disconnectServiceExtensionAbility(connection, (err: BusinessError) => { 1113 commRemote = null; 1114 if (err.code) { 1115 // 处理业务逻辑错误 1116 console.error(`disconnectServiceExtensionAbility failed, code is ${err.code}, message is ${err.message}`); 1117 return; 1118 } 1119 // 执行正常业务 1120 console.info('disconnectServiceExtensionAbility succeed'); 1121 }); 1122 } catch (err) { 1123 commRemote = null; 1124 // 处理入参错误异常 1125 let code = (err as BusinessError).code; 1126 let message = (err as BusinessError).message; 1127 console.error(`disconnectServiceExtensionAbility failed, code is ${code}, message is ${message}`); 1128 } 1129 } 1130} 1131``` 1132 1133### startAbilityByCall 1134 1135startAbilityByCall(want: Want): Promise<Caller> 1136 1137该接口用于获取[Caller](./js-apis-app-ability-uiAbility.md#caller)通信对象，以便于与[callee](./js-apis-app-ability-uiAbility.md#callee)进行通信。如果指定UIAbility未启动，则会将UIAbility启动至前台或后台。使用Promise异步回调。仅支持在主线程调用。 1138 1139该接口不支持拉起启动模式为[specified模式](../../application-models/uiability-launch-type.md#specified启动模式)的UIAbility。 1140 1141> **说明：** 1142> 1143> - 跨设备场景下，调用方与目标方必须为同一应用，且具备ohos.permission.DISTRIBUTED_DATASYNC权限，才能启动成功。 1144> 1145> - 同设备场景下，调用方与目标方必须为不同应用，且具备ohos.permission.ABILITY_BACKGROUND_COMMUNICATION权限（该权限仅系统应用可申请），才能启动成功。 1146> 1147> - 如果调用方位于后台，还需要具备ohos.permission.START_ABILITIES_FROM_BACKGROUND（该权限仅系统应用可申请）。更多的组件启动规则详见[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md)。 1148 1149**需要权限**：ohos.permission.DISTRIBUTED_DATASYNC 1150 1151> **说明：** 1152> 1153> API version 11之前的版本，该接口需要申请权限ohos.permission.ABILITY_BACKGROUND_COMMUNICATION（该权限仅系统应用可申请）。从API version 11开始，该接口需要申请的权限变更为ohos.permission.DISTRIBUTED_DATASYNC权限。 1154 1155**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 1156 1157**参数：** 1158 1159| 参数名 | 类型 | 必填 | 说明 | 1160| -------- | -------- | -------- | -------- | 1161| want | [Want](js-apis-app-ability-want.md) | 是 | 传入需要启动的UIAbility信息，包含abilityName、moduleName、bundleName、deviceId、parameters（可选）。将parameters中的'ohos.aafwk.param.callAbilityToForeground'配置为true可将UIAbility拉起到前台；否则表示将UIAbility拉起到后台。 | 1162 1163**返回值：** 1164 1165| 类型 | 说明 | 1166| -------- | -------- | 1167| Promise<[Caller](js-apis-app-ability-uiAbility.md#caller)> | Promise对象，获取要通讯的caller对象。 | 1168 1169**错误码：** 1170 1171以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 1172 1173| 错误码ID | 错误信息 | 1174| ------- | -------------------------------- | 1175| 201 | The application does not have permission to call the interface. | 1176| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 1177| 16000001 | The specified ability does not exist. | 1178| 16000002 | Incorrect ability type. | 1179| 16000004 | Cannot start an invisible component. | 1180| 16000006 | Cross-user operations are not allowed. | 1181| 16000008 | The crowdtesting application expires. | 1182| 16000011 | The context does not exist. | 1183| 16000012 | The application is controlled. | 1184| 16000013 | The application is controlled by EDM. | 1185| 16000018 | Redirection to a third-party application is not allowed in API version greater than 11. | 1186| 16000050 | Internal error. | 1187| 16000071 | App clone is not supported. | 1188| 16000072 | App clone or multi-instance is not supported. | 1189| 16000073 | The app clone index is invalid. | 1190| 16000076 | The app instance key is invalid. | 1191| 16000077 | The number of app instances reaches the limit. | 1192| 16000078 | The multi-instance is not supported. | 1193| 16000079 | The APP_INSTANCE_KEY cannot be specified. | 1194| 16000080 | Creating a new instance is not supported. | 1195 1196**示例：** 1197 1198后台启动： 1199 1200```ts 1201import { UIAbility, Caller, Want } from '@kit.AbilityKit'; 1202import { BusinessError } from '@kit.BasicServicesKit'; 1203 1204export default class EntryAbility extends UIAbility { 1205 onForeground() { 1206 let caller: Caller; 1207 // 后台启动Ability，不配置parameters 1208 let wantBackground: Want = { 1209 bundleName: 'com.example.myapplication', 1210 moduleName: 'entry', 1211 abilityName: 'EntryAbility', 1212 deviceId: '' 1213 }; 1214 1215 try { 1216 this.context.startAbilityByCall(wantBackground) 1217 .then((obj: Caller) => { 1218 // 执行正常业务 1219 caller = obj; 1220 console.info('startAbilityByCall succeed'); 1221 }).catch((err: BusinessError) => { 1222 // 处理业务逻辑错误 1223 console.error(`startAbilityByCall failed, code is ${err.code}, message is ${err.message}`); 1224 }); 1225 } catch (err) { 1226 // 处理入参错误异常 1227 let code = (err as BusinessError).code; 1228 let message = (err as BusinessError).message; 1229 console.error(`startAbilityByCall failed, code is ${code}, message is ${message}`); 1230 } 1231 } 1232} 1233``` 1234 1235前台启动： 1236 1237```ts 1238import { UIAbility, Caller, Want } from '@kit.AbilityKit'; 1239import { BusinessError } from '@kit.BasicServicesKit'; 1240 1241export default class EntryAbility extends UIAbility { 1242 onForeground() { 1243 let caller: Caller; 1244 // 前台启动Ability，将parameters中的'ohos.aafwk.param.callAbilityToForeground'配置为true 1245 let wantForeground: Want = { 1246 bundleName: 'com.example.myapplication', 1247 moduleName: 'entry', 1248 abilityName: 'EntryAbility', 1249 deviceId: '', 1250 parameters: { 1251 'ohos.aafwk.param.callAbilityToForeground': true 1252 } 1253 }; 1254 1255 try { 1256 this.context.startAbilityByCall(wantForeground) 1257 .then((obj: Caller) => { 1258 // 执行正常业务 1259 caller = obj; 1260 console.info('startAbilityByCall succeed'); 1261 }).catch((err: BusinessError) => { 1262 // 处理业务逻辑错误 1263 console.error(`startAbilityByCall failed, code is ${err.code}, message is ${err.message}`); 1264 }); 1265 } catch (err) { 1266 // 处理入参错误异常 1267 let code = (err as BusinessError).code; 1268 let message = (err as BusinessError).message; 1269 console.error(`startAbilityByCall failed, code is ${code}, message is ${message}`); 1270 } 1271 } 1272} 1273``` 1274 1275### setMissionLabel 1276 1277setMissionLabel(label: string, callback: AsyncCallback<void>): void 1278 1279设置UIAbility在多任务界面中显示的名称。使用callback异步回调。 1280 1281**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 1282 1283**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 1284 1285**参数：** 1286 1287| 参数名 | 类型 | 必填 | 说明 | 1288| -------- | -------- | -------- | -------- | 1289| label | string | 是 | 任务的名称。 | 1290| callback | AsyncCallback<void> | 是 | 回调函数，返回接口调用是否成功的结果。 | 1291 1292**错误码：** 1293 1294以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 1295 1296| 错误码ID | 错误信息 | 1297| ------- | -------------------------------- | 1298| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 1299| 16000011 | The context does not exist. | 1300| 16000050 | Internal error. | 1301 1302**示例：** 1303 1304```ts 1305import { UIAbility, AbilityConstant, Want } from '@kit.AbilityKit'; 1306import { BusinessError } from '@kit.BasicServicesKit'; 1307 1308export default class EntryAbility extends UIAbility { 1309 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 1310 this.context.setMissionLabel('test', (result: BusinessError) => { 1311 console.info(`setMissionLabel: ${JSON.stringify(result)}`); 1312 }); 1313 } 1314} 1315``` 1316 1317### setMissionLabel 1318 1319setMissionLabel(label: string): Promise<void> 1320 1321设置UIAbility在多任务界面中显示的名称。使用Promise异步回调。 1322 1323**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 1324 1325**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 1326 1327**参数：** 1328 1329| 参数名 | 类型 | 必填 | 说明 | 1330| -------- | -------- | -------- | -------- | 1331| label | string | 是 | 任务的名称。 | 1332 1333**返回值：** 1334 1335| 类型 | 说明 | 1336| -------- | -------- | 1337| Promise<void> | Promise对象，包含接口执行结果。 | 1338 1339**错误码：** 1340 1341以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 1342 1343| 错误码ID | 错误信息 | 1344| ------- | -------------------------------- | 1345| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 1346| 16000011 | The context does not exist. | 1347| 16000050 | Internal error. | 1348 1349**示例：** 1350 1351```ts 1352import { UIAbility, AbilityConstant, Want } from '@kit.AbilityKit'; 1353import { BusinessError } from '@kit.BasicServicesKit'; 1354 1355export default class EntryAbility extends UIAbility { 1356 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 1357 this.context.setMissionLabel('test').then(() => { 1358 console.info('success'); 1359 }).catch((err: BusinessError) => { 1360 let code = (err as BusinessError).code; 1361 let message = (err as BusinessError).message; 1362 console.error(`setMissionLabel failed, code is ${code}, message is ${message}`); 1363 }); 1364 } 1365} 1366``` 1367 1368### setMissionContinueState<sup>10+</sup> 1369 1370setMissionContinueState(state: AbilityConstant.ContinueState, callback: AsyncCallback<void>): void 1371 1372设置UIAbility任务的流转状态。使用callback异步回调。 1373 1374**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 1375 1376**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 1377 1378**参数：** 1379 1380| 参数名 | 类型 | 必填 | 说明 | 1381| -------- | -------- | -------- | -------- | 1382| state | [AbilityConstant.ContinueState](js-apis-app-ability-abilityConstant.md#continuestate10) | 是 | 流转状态。 | 1383| callback | AsyncCallback<void> | 是 | 回调函数，返回接口调用是否成功的结果。 | 1384 1385**错误码：** 1386 1387错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 1388 1389| 错误码ID | 错误信息 | 1390| ------- | -------------------------------- | 1391| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 1392| 16000011 | The context does not exist. | 1393| 16000050 | Internal error. | 1394 1395**示例：** 1396 1397```ts 1398import { UIAbility, AbilityConstant } from '@kit.AbilityKit'; 1399import { BusinessError } from '@kit.BasicServicesKit'; 1400 1401export default class EntryAbility extends UIAbility { 1402 onForeground() { 1403 this.context.setMissionContinueState(AbilityConstant.ContinueState.INACTIVE, (result: BusinessError) => { 1404 console.info(`setMissionContinueState: ${JSON.stringify(result)}`); 1405 }); 1406 } 1407} 1408``` 1409 1410### setMissionContinueState<sup>10+</sup> 1411 1412setMissionContinueState(state: AbilityConstant.ContinueState): Promise<void> 1413 1414设置UIAbility任务的流转状态。使用Promise异步回调。 1415 1416**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 1417 1418**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 1419 1420**参数：** 1421 1422| 参数名 | 类型 | 必填 | 说明 | 1423| -------- | -------- | -------- | -------- | 1424| state | [AbilityConstant.ContinueState](js-apis-app-ability-abilityConstant.md#continuestate10) | 是 | 流转状态。 | 1425 1426**返回值：** 1427 1428| 类型 | 说明 | 1429| -------- | -------- | 1430| Promise<void> | Promise对象，包含接口执行结果。 | 1431 1432**错误码：** 1433 1434错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 1435 1436| 错误码ID | 错误信息 | 1437| ------- | -------------------------------- | 1438| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 1439| 16000011 | The context does not exist. | 1440| 16000050 | Internal error. | 1441 1442**示例：** 1443 1444```ts 1445import { UIAbility, AbilityConstant } from '@kit.AbilityKit'; 1446import { BusinessError } from '@kit.BasicServicesKit'; 1447 1448export default class EntryAbility extends UIAbility { 1449 onForeground() { 1450 this.context.setMissionContinueState(AbilityConstant.ContinueState.INACTIVE).then(() => { 1451 console.info('success'); 1452 }).catch((err: BusinessError) => { 1453 console.error(`setMissionContinueState failed, code is ${err.code}, message is ${err.message}`); 1454 }); 1455 } 1456} 1457``` 1458 1459### restoreWindowStage 1460 1461restoreWindowStage(localStorage: LocalStorage): void 1462 1463恢复UIAbility中的WindowStage数据。仅支持在主线程调用。 1464 1465**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 1466 1467**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 1468 1469**参数：** 1470 1471| 参数名 | 类型 | 必填 | 说明 | 1472| -------- | -------- | -------- | -------- | 1473| localStorage | LocalStorage | 是 | 用于恢复window stage的存储数据。 | 1474 1475**错误码：** 1476 1477以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 1478 1479| 错误码ID | 错误信息 | 1480| ------- | -------------------------------- | 1481| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 1482| 16000011 | The context does not exist. | 1483| 16000050 | Internal error. | 1484 1485**示例：** 1486 1487```ts 1488import { UIAbility } from '@kit.AbilityKit'; 1489 1490export default class EntryAbility extends UIAbility { 1491 onForeground() { 1492 let storage = new LocalStorage(); 1493 this.context.restoreWindowStage(storage); 1494 } 1495} 1496``` 1497 1498### isTerminating 1499 1500isTerminating(): boolean 1501 1502查询UIAbility是否处于消亡中状态。 1503 1504**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 1505 1506**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 1507 1508**返回值：** 1509 1510| 类型 | 说明 | 1511| -------- | -------- | 1512| boolean | 表示是否处于消亡中状态。true表示处于消亡中状态，false表示不处于消亡中状态。 | 1513 1514**错误码：** 1515 1516以下错误码详细介绍请参考[元能力子系统错误码](errorcode-ability.md)。 1517 1518| 错误码ID | 错误信息 | 1519| ------- | -------------------------------- | 1520| 16000011 | The context does not exist. | 1521 1522**示例：** 1523 1524```ts 1525import { UIAbility } from '@kit.AbilityKit'; 1526 1527export default class EntryAbility extends UIAbility { 1528 onForeground() { 1529 let isTerminating: boolean = this.context.isTerminating(); 1530 console.info(`ability state is ${isTerminating}`); 1531 } 1532} 1533``` 1534 1535### requestDialogService 1536 1537requestDialogService(want: Want, result: AsyncCallback<dialogRequest.RequestResult>): void 1538 1539启动一个支持模态弹框的ServiceExtensionAbility。ServiceExtensionAbility被启动后，应用弹出模态弹框，通过调用[setRequestResult](js-apis-app-ability-dialogRequest.md#requestcallbacksetrequestresult)接口返回结果给调用者。使用callback异步回调。仅支持在主线程调用。 1540 1541> **说明：** 1542> 1543> 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md)。 1544 1545**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 1546 1547**参数：** 1548 1549| 参数名 | 类型 | 必填 | 说明 | 1550| -------- | -------- | -------- | -------- | 1551| want |[Want](js-apis-app-ability-want.md) | 是 | 启动ServiceExtensionAbility的want信息。 | 1552| result | AsyncCallback<[dialogRequest.RequestResult](js-apis-app-ability-dialogRequest.md#requestresult)> | 是 | 执行结果回调函数。 | 1553 1554**错误码：** 1555 1556以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 1557 1558| 错误码ID | 错误信息 | 1559| ------- | -------------------------------- | 1560| 201 | The application does not have permission to call the interface. | 1561| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 1562| 16000001 | The specified ability does not exist. | 1563| 16000002 | Incorrect ability type. | 1564| 16000004 | Cannot start an invisible component. | 1565| 16000005 | The specified process does not have the permission. | 1566| 16000006 | Cross-user operations are not allowed. | 1567| 16000008 | The crowdtesting application expires. | 1568| 16000009 | An ability cannot be started or stopped in Wukong mode. | 1569| 16000010 | The call with the continuation and prepare continuation flag is forbidden. | 1570| 16000011 | The context does not exist. | 1571| 16000012 | The application is controlled. | 1572| 16000013 | The application is controlled by EDM. | 1573| 16000050 | Internal error. | 1574| 16000053 | The ability is not on the top of the UI. | 1575| 16000055 | Installation-free timed out. | 1576| 16200001 | The caller has been released. | 1577 1578**示例：** 1579 1580```ts 1581import { UIAbility, Want, dialogRequest } from '@kit.AbilityKit'; 1582import { BusinessError } from '@kit.BasicServicesKit'; 1583 1584export default class EntryAbility extends UIAbility { 1585 onForeground() { 1586 let want: Want = { 1587 deviceId: '', 1588 bundleName: 'com.example.myapplication', 1589 abilityName: 'AuthAccountServiceExtension' 1590 }; 1591 1592 try { 1593 this.context.requestDialogService(want, (err: BusinessError, result: dialogRequest.RequestResult) => { 1594 if (err.code) { 1595 // 处理业务逻辑错误 1596 console.error(`requestDialogService failed, code is ${err.code}, message is ${err.message}`); 1597 return; 1598 } 1599 // 执行正常业务 1600 console.info(`requestDialogService succeed, result = ${JSON.stringify(result)}`); 1601 }); 1602 } catch (err) { 1603 // 处理入参错误异常 1604 let code = (err as BusinessError).code; 1605 let message = (err as BusinessError).message; 1606 console.error(`requestDialogService failed, code is ${code}, message is ${message}`); 1607 } 1608 } 1609} 1610``` 1611 1612### requestDialogService 1613 1614requestDialogService(want: Want): Promise<dialogRequest.RequestResult> 1615 1616启动一个支持模态弹框的ServiceExtensionAbility。ServiceExtensionAbility被启动后，应用弹出模态弹框，通过调用[setRequestResult](js-apis-app-ability-dialogRequest.md#requestcallbacksetrequestresult)接口返回结果给调用者。使用Promise异步回调。仅支持在主线程调用。 1617 1618> **说明：** 1619> 1620> 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md)。 1621 1622**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 1623 1624**参数：** 1625 1626| 参数名 | 类型 | 必填 | 说明 | 1627| -------- | -------- | -------- | -------- | 1628| want | [Want](js-apis-app-ability-want.md) | 是 | 启动ServiceExtensionAbility的want信息。 | 1629 1630 1631**返回值：** 1632 1633| 类型 | 说明 | 1634| -------- | -------- | 1635| Promise<[dialogRequest.RequestResult](js-apis-app-ability-dialogRequest.md#requestresult)> | Promise对象，包含接口执行结果。 | 1636 1637**错误码：** 1638 1639以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 1640 1641| 错误码ID | 错误信息 | 1642| ------- | -------------------------------- | 1643| 201 | The application does not have permission to call the interface. | 1644| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 1645| 16000001 | The specified ability does not exist. | 1646| 16000002 | Incorrect ability type. | 1647| 16000004 | Cannot start an invisible component. | 1648| 16000005 | The specified process does not have the permission. | 1649| 16000006 | Cross-user operations are not allowed. | 1650| 16000008 | The crowdtesting application expires. | 1651| 16000009 | An ability cannot be started or stopped in Wukong mode. | 1652| 16000010 | The call with the continuation and prepare continuation flag is forbidden. | 1653| 16000011 | The context does not exist. | 1654| 16000012 | The application is controlled. | 1655| 16000013 | The application is controlled by EDM. | 1656| 16000050 | Internal error. | 1657| 16000053 | The ability is not on the top of the UI. | 1658| 16000055 | Installation-free timed out. | 1659| 16200001 | The caller has been released. | 1660 1661**示例：** 1662 1663```ts 1664import { UIAbility, Want, dialogRequest } from '@kit.AbilityKit'; 1665import { BusinessError } from '@kit.BasicServicesKit'; 1666 1667export default class EntryAbility extends UIAbility { 1668 onForeground() { 1669 let want: Want = { 1670 bundleName: 'com.example.myapplication', 1671 abilityName: 'AuthAccountServiceExtension' 1672 }; 1673 1674 try { 1675 this.context.requestDialogService(want) 1676 .then((result: dialogRequest.RequestResult) => { 1677 // 执行正常业务 1678 console.info(`requestDialogService succeed, result = ${JSON.stringify(result)}`); 1679 }) 1680 .catch((err: BusinessError) => { 1681 // 处理业务逻辑错误 1682 console.error(`requestDialogService failed, code is ${err.code}, message is ${err.message}`); 1683 }); 1684 } catch (err) { 1685 // 处理入参错误异常 1686 let code = (err as BusinessError).code; 1687 let message = (err as BusinessError).message; 1688 console.error(`requestDialogService failed, code is ${code}, message is ${message}`); 1689 } 1690 } 1691} 1692``` 1693 1694### reportDrawnCompleted<sup>10+</sup> 1695 1696reportDrawnCompleted(callback: AsyncCallback\<void>): void 1697 1698用于通知系统UIAbility对应的窗口内容已经绘制完成。使用callback异步回调。 1699 1700**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 1701 1702**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 1703 1704**参数：** 1705 1706| 参数名 | 类型 | 必填 | 说明 | 1707| -------- | -------- | -------- | -------- | 1708| callback | AsyncCallback<void> | 是 | 回调函数，返回接口调用是否成功的结果。 | 1709 1710**错误码：** 1711 1712以下错误码详细介绍请参考[元能力子系统错误码](errorcode-ability.md)。 1713 1714| 错误码ID | 错误信息 | 1715| ------- | -------------------------------- | 1716| 16000011 | The context does not exist. | 1717| 16000050 | Internal error. | 1718 1719**示例：** 1720 1721```ts 1722import { UIAbility } from '@kit.AbilityKit'; 1723import { window } from '@kit.ArkUI'; 1724import { BusinessError } from '@kit.BasicServicesKit'; 1725 1726export default class EntryAbility extends UIAbility { 1727 onWindowStageCreate(windowStage: window.WindowStage) { 1728 windowStage.loadContent('pages/Index', (err, data) => { 1729 if (err.code) { 1730 return; 1731 } 1732 1733 try { 1734 this.context.reportDrawnCompleted((err) => { 1735 if (err.code) { 1736 // 处理业务逻辑错误 1737 console.error(`reportDrawnCompleted failed, code is ${err.code}, message is ${err.message}`); 1738 return; 1739 } 1740 // 执行正常业务 1741 console.info('reportDrawnCompleted succeed'); 1742 }); 1743 } catch (err) { 1744 // 捕获同步的参数错误 1745 let code = (err as BusinessError).code; 1746 let message = (err as BusinessError).message; 1747 console.error(`reportDrawnCompleted failed, code is ${code}, message is ${message}`); 1748 } 1749 }); 1750 console.info("MainAbility onWindowStageCreate"); 1751 } 1752}; 1753``` 1754 1755### startAbilityByType<sup>11+</sup> 1756 1757startAbilityByType(type: string, wantParam: Record<string, Object>, 1758 abilityStartCallback: AbilityStartCallback, callback: AsyncCallback\<void>) : void 1759 1760通过type隐式启动UIExtensionAbility。使用callback异步回调。仅支持在主线程调用，仅支持处于前台的应用调用。 1761 1762**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 1763 1764**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 1765 1766**参数：** 1767 1768| 参数名 | 类型 | 必填 | 说明 | 1769| -------- | -------- | -------- | -------- | 1770| type | string | 是 | 启动的UIExtensionAbility类型，取值详见[通过startAbilityByType接口拉起垂类面板](../../application-models/start-intent-panel.md#匹配规则)。 | 1771| wantParam | Record<string, Object> | 是 | 表示扩展参数。 | 1772| abilityStartCallback | [AbilityStartCallback](js-apis-inner-application-abilityStartCallback.md) | 是 | 回调函数，返回启动失败后的详细错误信息。 | 1773| callback | AsyncCallback<void> | 是 | 回调函数，返回接口调用是否成功的结果。 | 1774 1775**错误码：** 1776 1777以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 1778 1779| 错误码ID | 错误信息 | 1780| ------- | -------------------------------- | 1781| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 1782| 16000050 | Internal error. | 1783 1784**示例：** 1785 1786```ts 1787import { UIAbility, common } from '@kit.AbilityKit'; 1788 1789export default class EntryAbility extends UIAbility { 1790 onForeground() { 1791 let wantParam: Record<string, Object> = { 1792 'time': '2023-10-23 20:45' 1793 }; 1794 let abilityStartCallback: common.AbilityStartCallback = { 1795 onError: (code: number, name: string, message: string) => { 1796 console.info(`code:` + code + `name:` + name + `message:` + message); 1797 }, 1798 onResult: (abilityResult: common.AbilityResult) => { 1799 console.info(`resultCode:` + abilityResult.resultCode + `bundleName:` + abilityResult.want?.bundleName); 1800 } 1801 }; 1802 1803 this.context.startAbilityByType("photoEditor", wantParam, abilityStartCallback, (err) => { 1804 if (err) { 1805 console.error(`startAbilityByType fail, err: ${JSON.stringify(err)}`); 1806 } else { 1807 console.info(`success`); 1808 } 1809 }); 1810 } 1811} 1812``` 1813 1814### startAbilityByType<sup>11+</sup> 1815 1816startAbilityByType(type: string, wantParam: Record<string, Object>, 1817 abilityStartCallback: AbilityStartCallback) : Promise\<void> 1818 1819通过type隐式启动UIExtensionAbility。使用Promise异步回调。仅支持在主线程调用，仅支持处于前台的应用调用。 1820 1821**原子化服务API**：从API version 11开始，该接口支持在原子化服务中使用。 1822 1823**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 1824 1825**参数：** 1826 1827| 参数名 | 类型 | 必填 | 说明 | 1828| -------- | -------- | -------- | -------- | 1829| type | string | 是 | 启动的UIExtensionAbility类型，取值详见[通过startAbilityByType接口拉起垂类面板](../../application-models/start-intent-panel.md#匹配规则)。 | 1830| wantParam | Record<string, Object> | 是 | 表示扩展参数。 | 1831| abilityStartCallback | [AbilityStartCallback](js-apis-inner-application-abilityStartCallback.md) | 是 | 回调函数，返回启动失败后的详细错误信息。 | 1832 1833**返回值：** 1834 1835| 类型 | 说明 | 1836| -------- | -------- | 1837| Promise<void> | Promise对象，包含接口执行结果。 | 1838 1839**错误码：** 1840 1841以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 1842 1843| 错误码ID | 错误信息 | 1844| ------- | -------------------------------- | 1845| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 1846| 16000050 | Internal error. | 1847 1848**示例：** 1849 1850```ts 1851import { UIAbility, common } from '@kit.AbilityKit'; 1852import { BusinessError } from '@kit.BasicServicesKit'; 1853 1854export default class EntryAbility extends UIAbility { 1855 onForeground() { 1856 let wantParam: Record<string, Object> = { 1857 'time': '2023-10-23 20:45' 1858 }; 1859 let abilityStartCallback: common.AbilityStartCallback = { 1860 onError: (code: number, name: string, message: string) => { 1861 console.info(`code:` + code + `name:` + name + `message:` + message); 1862 }, 1863 onResult: (abilityResult: common.AbilityResult) => { 1864 console.info(`resultCode:` + abilityResult.resultCode + `bundleName:` + abilityResult.want?.bundleName); 1865 } 1866 }; 1867 1868 this.context.startAbilityByType("photoEditor", wantParam, abilityStartCallback).then(() => { 1869 console.info(`startAbilityByType success`); 1870 }).catch((err: BusinessError) => { 1871 console.error(`startAbilityByType fail, err: ${JSON.stringify(err)}`); 1872 }); 1873 } 1874} 1875``` 1876 1877### showAbility<sup>12+</sup> 1878 1879showAbility(): Promise\<void> 1880 1881显示当前UIAbility。使用Promise异步回调。仅支持在主线程调用。 1882 1883调用此接口前要求确保应用已添加至状态栏。 1884 1885**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 1886 1887**设备行为差异**：该接口仅在2in1和Tablet设备中可正常调用，在其他设备中返回801错误码。 1888 1889**返回值：** 1890 1891| 类型 | 说明 | 1892| -------- | -------- | 1893| Promise<void> | Promise对象，包含接口执行结果。 | 1894 1895**错误码：** 1896 1897以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 1898 1899| 错误码ID | 错误信息 | 1900| ------- | -------------------------------- | 1901| 801 | Capability not support. | 1902| 16000050 | Internal error. | 1903| 16000067 | The StartOptions check failed. | 1904 1905**示例：** 1906 1907```ts 1908// Index.ets 1909import { common } from '@kit.AbilityKit'; 1910import { BusinessError } from '@kit.BasicServicesKit'; 1911 1912@Entry 1913@Component 1914struct Index { 1915 @State showAbility: string = 'showAbility' 1916 1917 build() { 1918 Row() { 1919 Column() { 1920 Text(this.showAbility) 1921 .fontSize(30) 1922 .fontWeight(FontWeight.Bold) 1923 .onClick(() => { 1924 let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 1925 1926 context.showAbility().then(() => { 1927 console.info(`showAbility success`); 1928 }).catch((err: BusinessError) => { 1929 console.error(`showAbility fail, err: ${JSON.stringify(err)}`); 1930 }); 1931 }); 1932 } 1933 .width('100%') 1934 } 1935 .height('100%') 1936 } 1937} 1938``` 1939```ts 1940// EntryAbility.ts 1941import { UIAbility, Want, StartOptions, contextConstant } from '@kit.AbilityKit'; 1942import { BusinessError } from '@kit.BasicServicesKit'; 1943 1944export default class EntryAbility extends UIAbility { 1945 onForeground() { 1946 let want: Want = { 1947 deviceId: '', 1948 bundleName: 'com.example.myapplication', 1949 abilityName: 'EntryAbility' 1950 }; 1951 let options: StartOptions = { 1952 displayId: 0, 1953 processMode: contextConstant.ProcessMode.NEW_PROCESS_ATTACH_TO_STATUS_BAR_ITEM, 1954 startupVisibility: contextConstant.StartupVisibility.STARTUP_SHOW 1955 }; 1956 1957 try { 1958 this.context.startAbility(want, options, (err: BusinessError) => { 1959 if (err.code) { 1960 // 处理业务逻辑错误 1961 console.error(`startAbility failed, code is ${err.code}, message is ${err.message}`); 1962 return; 1963 } 1964 // 执行正常业务 1965 console.info('startAbility succeed'); 1966 }); 1967 } catch (err) { 1968 // 处理入参错误异常 1969 let code = (err as BusinessError).code; 1970 let message = (err as BusinessError).message; 1971 console.error(`startAbility failed, code is ${code}, message is ${message}`); 1972 } 1973 } 1974} 1975``` 1976 1977### hideAbility<sup>12+</sup> 1978 1979hideAbility(): Promise\<void> 1980 1981隐藏当前UIAbility。使用Promise异步回调。仅支持在主线程调用。 1982 1983调用此接口前要求确保应用已添加至状态栏。 1984 1985**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 1986 1987**设备行为差异**：该接口仅在2in1和Tablet设备中可正常调用，在其他设备中返回801错误码。 1988 1989**返回值：** 1990 1991| 类型 | 说明 | 1992| -------- | -------- | 1993| Promise<void> | Promise对象，包含接口执行结果。 | 1994 1995**错误码：** 1996 1997以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 1998 1999| 错误码ID | 错误信息 | 2000| ------- | -------------------------------- | 2001| 801 | Capability not support. | 2002| 16000050 | Internal error. | 2003| 16000067 | The StartOptions check failed. | 2004 2005**示例：** 2006 2007```ts 2008// Index.ets 2009import { common } from '@kit.AbilityKit'; 2010import { BusinessError } from '@kit.BasicServicesKit'; 2011 2012@Entry 2013@Component 2014struct Index { 2015 @State hideAbility: string = 'hideAbility' 2016 2017 build() { 2018 Row() { 2019 Column() { 2020 Text(this.hideAbility) 2021 .fontSize(30) 2022 .fontWeight(FontWeight.Bold) 2023 .onClick(() => { 2024 let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 2025 2026 context.hideAbility().then(() => { 2027 console.info(`hideAbility success`); 2028 }).catch((err: BusinessError) => { 2029 console.error(`hideAbility fail, err: ${JSON.stringify(err)}`); 2030 }); 2031 }); 2032 } 2033 .width('100%') 2034 } 2035 .height('100%') 2036 } 2037} 2038``` 2039```ts 2040// EntryAbility.ts 2041import { UIAbility, Want, StartOptions, contextConstant } from '@kit.AbilityKit'; 2042import { BusinessError } from '@kit.BasicServicesKit'; 2043 2044export default class EntryAbility extends UIAbility { 2045 onForeground() { 2046 let want: Want = { 2047 deviceId: '', 2048 bundleName: 'com.example.myapplication', 2049 abilityName: 'EntryAbility' 2050 }; 2051 let options: StartOptions = { 2052 displayId: 0, 2053 processMode: contextConstant.ProcessMode.NEW_PROCESS_ATTACH_TO_STATUS_BAR_ITEM, 2054 startupVisibility: contextConstant.StartupVisibility.STARTUP_HIDE 2055 }; 2056 2057 try { 2058 this.context.startAbility(want, options, (err: BusinessError) => { 2059 if (err.code) { 2060 // 处理业务逻辑错误 2061 console.error(`startAbility failed, code is ${err.code}, message is ${err.message}`); 2062 return; 2063 } 2064 // 执行正常业务 2065 console.info('startAbility succeed'); 2066 }); 2067 } catch (err) { 2068 // 处理入参错误异常 2069 let code = (err as BusinessError).code; 2070 let message = (err as BusinessError).message; 2071 console.error(`startAbility failed, code is ${code}, message is ${message}`); 2072 } 2073 } 2074} 2075``` 2076 2077### moveAbilityToBackground<sup>12+<sup> 2078 2079moveAbilityToBackground(): Promise\<void> 2080 2081将处于前台的UIAbility移动到后台。使用Promise异步回调。仅支持在主线程调用。<br/><!--RP1--><!--RP1End--> 2082 2083**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 2084 2085**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 2086 2087**设备行为差异**： 2088- 从API version 12开始，该接口仅在Phone、Wearable和TV设备中可正常调用，在其他设备上返回16000061错误码。 2089- 从API version 13开始，该接口仅在Phone、Tablet、Wearable和TV设备中可正常调用，在其他设备上返回16000061错误码。 2090 2091**返回值：** 2092 2093| 类型 | 说明 | 2094| -------- | -------- | 2095| Promise<void> | Promise对象，包含接口执行结果。 | 2096 2097**错误码：** 2098 2099以下错误码详细介绍请参考[元能力子系统错误码](errorcode-ability.md)。 2100 2101| 错误码ID | 错误信息 | 2102| ------- | -------------------------------- | 2103| 16000011 | The context does not exist. | 2104| 16000050 | Internal error. | 2105| 16000061 | Operation not supported. | 2106| 16000065 | The API can be called only when the ability is running in the foreground. | 2107| 16000066 | An ability cannot switch to the foreground or background in Wukong mode. | 2108 2109**示例：** 2110 2111```ts 2112import { common } from '@kit.AbilityKit'; 2113import { BusinessError } from '@kit.BasicServicesKit'; 2114 2115@Entry 2116@Component 2117struct Index { 2118 @State moveAbilityToBackground: string = 'Move To Background' 2119 2120 build() { 2121 Row() { 2122 Column() { 2123 Text(this.moveAbilityToBackground) 2124 .fontSize(30) 2125 .fontWeight(FontWeight.Bold) 2126 .onClick(() => { 2127 let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 2128 2129 context.moveAbilityToBackground().then(() => { 2130 console.info(`moveAbilityToBackground success.`); 2131 }).catch((err: BusinessError) => { 2132 console.info(`moveAbilityToBackground error: ${JSON.stringify(err)}.`); 2133 }); 2134 }); 2135 } 2136 .width('100%') 2137 } 2138 .height('100%') 2139 } 2140} 2141``` 2142 2143### openAtomicService<sup>12+<sup> 2144 2145openAtomicService(appId: string, options?: AtomicServiceOptions): Promise<AbilityResult> 2146 2147打开一个独立窗口的原子化服务，并返回结果。使用Promise异步回调。仅支持在主线程调用。 2148 2149原子化服务被启动后，有如下情况： 2150 - 正常情况下原子化服务可通过[terminateSelfWithResult](#terminateselfwithresult)接口使之终止并且返回结果给调用方。 2151 - 异常情况下比如杀死原子化服务会返回异常信息给调用方，异常信息中resultCode为-1。 2152 - 如果不同应用多次调用该接口启动同一个原子化服务，当这个原子化服务调用[terminateSelfWithResult](#terminateselfwithresult)接口使之终止时，只将正常结果返回给最后一个调用方, 其它调用方返回异常信息，异常信息中resultCode为-1。 2153 2154> **说明：** 2155> 2156> 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md)。 2157 2158**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 2159 2160**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 2161 2162**参数：** 2163 2164| 参数名 | 类型 | 必填 | 说明 | 2165| -------- | -------- | -------- | -------- | 2166| appId | string | 是 | 应用的唯一标识，由云端统一分配。 | 2167| options | [AtomicServiceOptions](js-apis-app-ability-atomicServiceOptions.md) | 否 | 启动原子化服务所携带的参数。 | 2168 2169 2170**返回值：** 2171 2172| 类型 | 说明 | 2173| -------- | -------- | 2174| Promise<[AbilityResult](js-apis-inner-ability-abilityResult.md)> | Promise对象，包含返回给拉起方的信息。 | 2175 2176**错误码：** 2177 2178以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 2179 2180| 错误码ID | 错误信息 | 2181| ------- | -------------------------------- | 2182| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 2183| 16000002 | Incorrect ability type. | 2184| 16000003 | The specified ID does not exist. | 2185| 16000004 | Cannot start an invisible component. | 2186| 16000011 | The context does not exist. | 2187| 16000012 | The application is controlled. | 2188| 16000050 | Internal error. | 2189| 16000053 | The ability is not on the top of the UI. | 2190| 16000055 | Installation-free timed out. | 2191| 16200001 | The caller has been released. | 2192 2193**示例：** 2194 2195```ts 2196import { UIAbility, common, AtomicServiceOptions } from '@kit.AbilityKit'; 2197import { BusinessError } from '@kit.BasicServicesKit'; 2198 2199export default class EntryAbility extends UIAbility { 2200 onForeground() { 2201 let appId: string = '6918661953712445909'; 2202 let options: AtomicServiceOptions = { 2203 displayId: 0 2204 }; 2205 2206 try { 2207 this.context.openAtomicService(appId, options) 2208 .then((result: common.AbilityResult) => { 2209 // 执行正常业务 2210 console.info('openAtomicService succeed'); 2211 }) 2212 .catch((err: BusinessError) => { 2213 // 处理业务逻辑错误 2214 console.error(`openAtomicService failed, code is ${err.code}, message is ${err.message}`); 2215 }); 2216 } catch (err) { 2217 // 处理入参错误异常 2218 let code = (err as BusinessError).code; 2219 let message = (err as BusinessError).message; 2220 console.error(`openAtomicService failed, code is ${code}, message is ${message}`); 2221 } 2222 } 2223} 2224``` 2225 2226### openLink<sup>12+<sup> 2227 2228openLink(link: string, options?: OpenLinkOptions, callback?: AsyncCallback<AbilityResult>): Promise<void> 2229 2230通过<!--RP2-->[App Linking](../../application-models/app-linking-startup.md)<!--RP2End-->或[Deep Linking](../../application-models/deep-linking-startup.md)方式启动UIAbility，并通过回调函数接收被拉起的UIAbility退出时的返回结果。使用Promise异步回调。仅支持在主线程调用。 2231 2232通过在link字段中传入标准格式的URL，基于隐式want匹配规则拉起目标UIAbility。目标方必须具备以下过滤器特征，才能处理App Linking链接： 2233- "actions"列表中包含"ohos.want.action.viewData"。 2234- "entities"列表中包含"entity.system.browsable"。 2235- "uris"列表中包含"scheme"为"https"且"domainVerify"为true的元素。 2236 2237如果希望获取被拉起方终止后的结果，可以设置callback参数，此参数的使用可参照[startAbilityForResult](#startabilityforresult)接口。 2238传入的参数不合法时，如未设置必选参数或link字符串不是标准格式的URL，接口会直接抛出异常。参数校验通过，拉起目标方时出现的错误通过promise返回错误信息。 2239 2240> **说明：** 2241> 2242> 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md)。 2243 2244**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 2245 2246**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 2247 2248**参数：** 2249 2250| 参数名 | 类型 | 必填 | 说明 | 2251| -------- | -------- | -------- | -------- | 2252| link | string | 是 | 指示要打开的标准格式URL。 | 2253| options | [OpenLinkOptions](js-apis-app-ability-openLinkOptions.md) | 否 | 打开URL的选项参数。 | 2254| callback | AsyncCallback<[AbilityResult](js-apis-inner-ability-abilityResult.md)> | 否 | 回调函数，包含返回给拉起方的信息。 | 2255 2256**返回值：** 2257 2258| 类型 | 说明 | 2259| -------- | -------- | 2260| Promise<void> | Promise对象，包含接口执行结果。 | 2261 2262**错误码：** 2263 2264以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 2265 2266| 错误码ID | 错误信息 | 2267| ------- | -------------------------------- | 2268| 201 | The application does not have permission to call the interface. | 2269| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 2270| 16000001 | The specified ability does not exist. | 2271| 16000002 | Incorrect ability type. | 2272| 16000004 | Cannot start an invisible component. | 2273| 16000005 | The specified process does not have the permission. | 2274| 16000006 | Cross-user operations are not allowed. | 2275| 16000008 | The crowdtesting application expires. | 2276| 16000009 | An ability cannot be started or stopped in Wukong mode. | 2277| 16000010 | The call with the continuation and prepare continuation flag is forbidden. | 2278| 16000011 | The context does not exist. | 2279| 16000012 | The application is controlled. | 2280| 16000013 | The application is controlled by EDM. | 2281| 16000019 | No matching ability is found. | 2282| 16200001 | The caller has been released. | 2283| 16000053 | The ability is not on the top of the UI. | 2284 2285**示例：** 2286 2287```ts 2288import { common, OpenLinkOptions } from '@kit.AbilityKit'; 2289import { hilog } from '@kit.PerformanceAnalysisKit'; 2290import { BusinessError } from '@kit.BasicServicesKit'; 2291 2292const DOMAIN = 0xeeee; 2293const TAG: string = '[openLinkDemo]'; 2294 2295@Entry 2296@Component 2297struct Index { 2298 build() { 2299 RelativeContainer() { 2300 Button("Call StartAbilityForResult") 2301 .onClick(() => { 2302 let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 2303 let link: string = 'https://www.example.com'; 2304 let openLinkOptions: OpenLinkOptions = { 2305 appLinkingOnly: true, 2306 parameters: { demo_key: 'demo_value' } 2307 }; 2308 2309 try { 2310 context.openLink( 2311 link, 2312 openLinkOptions, 2313 (err, result) => { 2314 hilog.error(DOMAIN, TAG, `openLink callback error.code: ${JSON.stringify(err)}`); 2315 hilog.info(DOMAIN, TAG, `openLink callback result: ${JSON.stringify(result.resultCode)}`); 2316 hilog.info(DOMAIN, TAG, `openLink callback result data: ${JSON.stringify(result.want)}`); 2317 } 2318 ).then(() => { 2319 hilog.info(DOMAIN, TAG, `open link success.`); 2320 }).catch((err: BusinessError) => { 2321 hilog.error(DOMAIN, TAG, `open link failed, errCode ${JSON.stringify(err.code)}`); 2322 }); 2323 } 2324 catch (e) { 2325 hilog.error(DOMAIN, TAG, `exception occured, errCode ${JSON.stringify(e.code)}`); 2326 } 2327 }) 2328 } 2329 .height('100%') 2330 .width('100%') 2331 } 2332} 2333``` 2334 2335### backToCallerAbilityWithResult<sup>12+<sup> 2336 2337backToCallerAbilityWithResult(abilityResult: AbilityResult, requestCode: string): Promise<void> 2338 2339当通过[startAbilityForResult](#startabilityforresult)或[openLink](#openlink12)拉起目标方UIAbility，且需要目标方返回结果时，目标方可以通过该接口将结果返回并拉起调用方。与[terminateSelfWithResult](#terminateselfwithresult)不同的是，本接口在返回时不会销毁当前UIAbility。使用Promise异步回调。 2340 2341**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 2342 2343**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 2344 2345**参数：** 2346 2347| 参数名 | 类型 | 必填 | 说明 | 2348| -------- | -------- | -------- | -------- | 2349| abilityResult | [AbilityResult](js-apis-inner-ability-abilityResult.md) | 是 | 包含目标方返回给拉起方的结果。 | 2350| requestCode | string | 是 | 通过[startAbilityForResult](#startabilityforresult)或[openLink](#openlink12)拉起目标方Ability且需要目标方返回结果时，系统生成的用于标识本次调用的requestCode。该值可以通过want中的[CALLER_REQUEST_CODE](js-apis-app-ability-wantConstant.md)字段获取。| 2351 2352**返回值：** 2353 2354| 类型 | 说明 | 2355| -------- | -------- | 2356| Promise<void> | Promise对象，包含接口执行结果。 | 2357 2358**错误码：** 2359 2360以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 2361 2362| 错误码ID | 错误信息 | 2363| ------- | -------------------------------- | 2364| 201 | The application does not have permission to call the interface. | 2365| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 2366| 16000009 | An ability cannot be started or stopped in Wukong mode. | 2367| 16000011 | The context does not exist. | 2368| 16000050 | Internal error. | 2369| 16000074 | The caller does not exist. | 2370| 16000075 | BackToCaller is not supported. | 2371 2372**示例：** 2373调用方通过startAbilityForResult接口拉起目标方, 目标方再调用backToCallerAbilityWithResult接口返回到调用方。 2374 2375```ts 2376// 调用方 2377// index.ets 2378import { common, Want } from '@kit.AbilityKit'; 2379import { BusinessError } from '@ohos.base'; 2380import { hilog } from '@kit.PerformanceAnalysisKit'; 2381 2382@Entry 2383@Component 2384struct Index { 2385 @State message: string = 'Hello World'; 2386 2387 build() { 2388 Row() { 2389 Column() { 2390 Text(this.message) 2391 .fontSize(30) 2392 .fontWeight(FontWeight.Bold) 2393 2394 Button("Call StartAbilityForResult") 2395 .onClick(() => { 2396 let context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext; 2397 let want: Want = { 2398 bundleName: 'com.example.demo2', 2399 abilityName: 'EntryAbility' 2400 }; 2401 2402 try { 2403 // 通过startAbilityForResult拉起目标应用 2404 context.startAbilityForResult(want, (err: BusinessError, result: common.AbilityResult) => { 2405 if (err.code) { 2406 // 处理业务逻辑错误 2407 hilog.error(0x0000, 'testTag', `startAbilityForResult failed, code is ${err.code}, message is ${err.message}`); 2408 this.message = `startAbilityForResult failed: code is ${err.code}, message is ${err.message}` 2409 return; 2410 } 2411 // 执行正常业务 2412 hilog.info(0x0000, 'testTag', `startAbilityForResult succeed`); 2413 hilog.info(0x0000, 'testTag', `AbilityResult is ${JSON.stringify(result)}`); 2414 this.message = `AbilityResult.resultCode: ${JSON.stringify(result.resultCode)}` 2415 }); 2416 } catch (err) { 2417 // 处理入参错误异常 2418 let code = (err as BusinessError).code; 2419 let message = (err as BusinessError).message; 2420 hilog.error(0x0000, 'testTag', `startAbilityForResult failed, code is ${code}, message is ${message}`); 2421 this.message = `startAbilityForResult failed, code is ${code}, message is ${message}`; 2422 } 2423 }) 2424 } 2425 .width('100%') 2426 } 2427 .height('100%') 2428 } 2429} 2430``` 2431 2432```ts 2433// 目标方 2434// EntryAbility.ets 2435import { AbilityConstant, common, UIAbility, Want, wantConstant } from '@kit.AbilityKit'; 2436import { hilog } from '@kit.PerformanceAnalysisKit'; 2437import { BusinessError } from '@kit.BasicServicesKit'; 2438 2439export default class EntryAbility extends UIAbility { 2440 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { 2441 // 从want中获取调用方的CALLER_REQUEST_CODE，并保存 2442 let callerRequestCode: string = want?.parameters?.[wantConstant.Params.CALLER_REQUEST_CODE] as string; 2443 AppStorage.setOrCreate<string>("callerRequestCode", callerRequestCode) 2444 } 2445 2446 onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): void { 2447 let callerRequestCode: string = want?.parameters?.[wantConstant.Params.CALLER_REQUEST_CODE] as string; 2448 AppStorage.setOrCreate<string>("callerRequestCode", callerRequestCode) 2449 } 2450 2451 onForeground(): void { 2452 // 获取保存的CALLER_REQUEST_CODE 2453 let callerRequestCode: string = AppStorage.get<string>("callerRequestCode") as string; 2454 hilog.info(0x0000, 'testTag', `callerRequestCode is ${callerRequestCode}`); 2455 let want: Want = {}; 2456 let resultCode = 100; 2457 let abilityResult: common.AbilityResult = { 2458 want, 2459 resultCode 2460 }; 2461 try { 2462 // 将结果信息返回给调用方 2463 this.context.backToCallerAbilityWithResult(abilityResult, callerRequestCode) 2464 .then(() => { 2465 // 执行正常业务 2466 hilog.info(0x0000, 'testTag', 'backToCallerAbilityWithResult succeed'); 2467 }) 2468 .catch((err: BusinessError) => { 2469 // 处理业务逻辑错误 2470 hilog.error(0x0000, 'testTag', `backToCallerAbilityWithResult failed, code is ${err.code}, message is ${err.message}`); 2471 }); 2472 } catch (err) { 2473 // 捕获同步的参数错误 2474 let code = (err as BusinessError).code; 2475 let message = (err as BusinessError).message; 2476 hilog.error(0x0000, 'testTag', `backToCallerAbilityWithResult failed, code is ${code}, message is ${message}`); 2477 } 2478 } 2479} 2480``` 2481 2482### setRestoreEnabled<sup>14+</sup> 2483 2484setRestoreEnabled(enabled: boolean): void 2485 2486设置UIAbility是否启用备份恢复。 2487 2488**原子化服务API**：从API version 14开始，该接口支持在原子化服务中使用。 2489 2490**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 2491 2492**参数：** 2493 2494| 参数名 | 类型 | 必填 | 说明 | 2495| -------- | -------- | -------- | -------- | 2496| enabled | boolean | 是 | 表示是否启用恢复。true表示启用，false表示不启用。 | 2497 2498**错误码：** 2499 2500以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 2501 2502| 错误码ID | 错误信息 | 2503| ------- | -------------------------------- | 2504| 401 | If the input parameter is not valid parameter. | 2505| 16000011 | The context does not exist. | 2506 2507**示例：** 2508 2509```ts 2510import { UIAbility, AbilityConstant, Want } from '@kit.AbilityKit'; 2511import { BusinessError } from '@kit.BasicServicesKit'; 2512 2513export default class EntryAbility extends UIAbility { 2514 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { 2515 let enabled = true; 2516 try { 2517 this.context.setRestoreEnabled(enabled); 2518 } catch (paramError) { 2519 let code = (paramError as BusinessError).code; 2520 let message = (paramError as BusinessError).message; 2521 console.error(`setRestoreEnabled failed, err code: ${code}, err msg: ${message}`); 2522 } 2523 } 2524} 2525``` 2526 2527### startUIServiceExtensionAbility<sup>14+<sup> 2528 2529startUIServiceExtensionAbility(want: Want): Promise<void> 2530 2531启动一个UIServiceExtensionAbility。使用Promise异步回调。 2532 2533> **说明：** 2534> 2535> 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md)。 2536 2537**原子化服务API**：从API version 14开始，该接口支持在原子化服务中使用。 2538 2539**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 2540 2541**参数：** 2542 2543| 参数名 | 类型 | 必填 | 说明 | 2544| -------- | --------------------------------------- | ---- | ------------------------ | 2545| want | [Want](js-apis-app-ability-want.md) | 是 | 启动UIServiceExtensionAbility的必要信息。 | 2546 2547**返回值：** 2548 2549| 类型 | 说明 | 2550| ------------------- | -------------------------------------- | 2551| Promise<void> | Promise对象，包含接口执行结果。 | 2552 2553**错误码：** 2554 2555以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 2556 2557| 错误码ID | 错误信息 | 2558| -------- | ----------------------------------------------------------------------------------------------------------- | 2559| 201 | The application does not have permission to call the interface. | 2560| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 2561| 801 | Capability not supported. | 2562| 16000001 | The specified ability does not exist. | 2563| 16000002 | Incorrect ability type. | 2564| 16000004 | Cannot start an invisible component. | 2565| 16000005 | The specified process does not have the permission. | 2566| 16000008 | The crowdtesting application expires. | 2567| 16000011 | The context does not exist. | 2568| 16000012 | The application is controlled. | 2569| 16000013 | The application is controlled by EDM. | 2570| 16000019 | No matching ability is found. | 2571| 16000050 | Internal error. | 2572| 16200001 | The caller has been released. | 2573 2574**示例：** 2575 2576```ts 2577import { common, Want } from '@kit.AbilityKit'; 2578import { BusinessError } from '@kit.BasicServicesKit'; 2579 2580@Entry 2581@Component 2582struct Index { 2583 build() { 2584 Column() { 2585 Row() { 2586 // 创建启动按钮 2587 Button('start ability') 2588 .enabled(true) 2589 .onClick(() => { 2590 let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 2591 let startWant: Want = { 2592 bundleName: 'com.acts.uiserviceextensionability', 2593 abilityName: 'UiServiceExtAbility', 2594 }; 2595 try { 2596 // 启动UIServiceExtensionAbility 2597 context.startUIServiceExtensionAbility(startWant).then(() => { 2598 console.info('startUIServiceExtensionAbility success'); 2599 }).catch((error: BusinessError) => { 2600 console.info('startUIServiceExtensionAbility error', JSON.stringify(error)); 2601 }) 2602 } catch (err) { 2603 console.info('startUIServiceExtensionAbility failed', JSON.stringify(err)); 2604 } 2605 }) 2606 } 2607 } 2608 } 2609} 2610``` 2611 2612### connectUIServiceExtensionAbility<sup>14+<sup> 2613 2614connectUIServiceExtensionAbility(want: Want, callback: UIServiceExtensionConnectCallback) : Promise<UIServiceProxy> 2615 2616连接一个UIServiceExtensionAbility。使用Promise异步回调。 2617 2618> **说明：** 2619> 2620> 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md)。 2621> 2622 2623**原子化服务API**：从API version 14开始，该接口支持在原子化服务中使用。 2624 2625**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 2626 2627**参数：** 2628 2629| 参数名 | 类型 | 必填 | 说明 | 2630| ------ | ---- | ---- | ---- | 2631| want |[Want](js-apis-app-ability-want.md) | 是 | 连接UIServiceExtensionAbility的必要信息。 | 2632| callback | [UIServiceExtensionConnectCallback](js-apis-inner-application-uiServiceExtensionconnectcallback.md) | 是 | 连接UIServiceExtensionAbility回调。 | 2633 2634**返回值：** 2635 2636| 类型 | 说明 | 2637| ------------------- | -------------------------------------- | 2638| Promise<UIServiceProxy> | Promise对象，包含connectUIServiceExtensionAbility执行后返回的[UIServiceProxy](js-apis-inner-application-uiserviceproxy.md)对象。 | 2639 2640**错误码：** 2641 2642以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 2643 2644| 错误码ID | 错误信息 | 2645| -------- | ----------------------------------------------------------------------------------- | 2646| 201 | The application does not have permission to call the interface. | 2647| 801 | Capability not supported. | 2648| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 2649| 16000001 | The specified ability does not exist. | 2650| 16000002 | Incorrect ability type. | 2651| 16000004 | Cannot start an invisible component. | 2652| 16000005 | The specified process does not have the permission. | 2653| 16000008 | The crowdtesting application expires. | 2654| 16000011 | The context does not exist. | 2655| 16000013 | The application is controlled by EDM. | 2656| 16000050 | Internal error. | 2657| 16000055 | Installation-free timed out. | 2658 2659**示例：** 2660 2661```ts 2662import { common, Want } from '@kit.AbilityKit'; 2663import { BusinessError } from '@kit.BasicServicesKit'; 2664 2665const TAG: string = '[Extension] '; 2666 2667@Entry 2668@Component 2669struct UIServiceExtensionAbility { 2670 dataCallBack : common.UIServiceExtensionConnectCallback = { 2671 // 接收数据 2672 onData: (data: Record<string, Object>) => { 2673 console.info(`dataCallBack received data`, JSON.stringify(data)); 2674 }, 2675 // 连接断开 2676 onDisconnect: () => { 2677 console.info(`dataCallBack onDisconnect`); 2678 } 2679 } 2680 2681 async myConnect() { 2682 // 获取上下文 2683 let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 2684 let startWant: Want = { 2685 deviceId: '', 2686 bundleName: 'com.example.myapplication', 2687 abilityName: 'UiServiceExtAbility' 2688 }; 2689 2690 try { 2691 // 连接服务 2692 context.connectUIServiceExtensionAbility(startWant, this.dataCallBack) 2693 .then((proxy: common.UIServiceProxy) => { 2694 console.info(TAG + `try to connectUIServiceExtensionAbility`, JSON.stringify(proxy)); 2695 }).catch((err: Error) => { 2696 let code = (err as BusinessError).code; 2697 let message = (err as BusinessError).message; 2698 console.info(TAG + `connectUIServiceExtensionAbility failed, code is ${code}, message is ${message}`); 2699 }); 2700 } catch (err) { 2701 let code = (err as BusinessError).code; 2702 let message = (err as BusinessError).message; 2703 console.info(TAG + `connectUIServiceExtensionAbility failed, code is ${code}, message is ${message}`); 2704 }; 2705 } 2706 2707 build() { 2708 RelativeContainer() { 2709 // 创建连接按钮 2710 Button('connectServiceExtensionAbility', { type: ButtonType.Capsule, stateEffect: true }) 2711 .alignRules({ 2712 center: { anchor: '__container__', align: VerticalAlign.Center }, 2713 middle: { anchor: '__container__', align: HorizontalAlign.Center } 2714 }) 2715 .onClick(() => { 2716 this.myConnect() 2717 }); 2718 } 2719 .height('100%') 2720 .width('100%') 2721 } 2722} 2723``` 2724 2725### disconnectUIServiceExtensionAbility<sup>14+<sup> 2726 2727disconnectUIServiceExtensionAbility(proxy: UIServiceProxy): Promise<void> 2728 2729断开与UIServiceExtensionAbility的连接。使用Promise异步回调。 2730 2731> **说明：** 2732> 2733> 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md)。 2734> 2735 2736**原子化服务API**：从API version 14开始，该接口支持在原子化服务中使用。 2737 2738**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 2739 2740**参数：** 2741 2742| 参数名 | 类型 | 必填 | 说明 | 2743| ------ | ---- | ---- | -------------------- | 2744| proxy | [UIServiceProxy](js-apis-inner-application-uiserviceproxy.md) | 是 | [connectUIServiceExtensionAbility](#connectuiserviceextensionability14)执行返回的Proxy。 | 2745 2746**返回值：** 2747 2748| 类型 | 说明 | 2749| ------------------- | -------------------------------------- | 2750| Promise<void> | Promise对象，包含接口执行结果。 | 2751 2752**错误码：** 2753 2754以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 2755 2756| 错误码ID | 错误信息 | 2757| -------- | ------------------------------------------------------------------------------------------- | 2758| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 2759| 16000011 | The context does not exist. | 2760| 16000050 | Internal error. | 2761 2762**示例：** 2763 2764```ts 2765import { common } from '@kit.AbilityKit'; 2766import { BusinessError } from '@kit.BasicServicesKit'; 2767 2768const TAG: string = '[Extension] '; 2769 2770@Entry 2771@Component 2772struct UIServiceExtensionAbility { 2773 comProxy: common.UIServiceProxy | null = null; 2774 2775 build() { 2776 Scroll() { 2777 Column() { 2778 // 创建断开连接的按钮 2779 Button('disconnectUIServiceExtensionAbility', { type: ButtonType.Capsule, stateEffect: true }) 2780 .margin({ 2781 top: 5, 2782 left: 10, 2783 right: 10, 2784 bottom: 5 2785 }) 2786 .alignRules({ 2787 center: { anchor: '__container__', align: VerticalAlign.Center }, 2788 middle: { anchor: '__container__', align: HorizontalAlign.Center } 2789 }) 2790 .onClick(() => { 2791 this.myDisconnectUIServiceExtensionAbility() 2792 }); 2793 } 2794 .width('100%') 2795 } 2796 .height('100%') 2797 } 2798 2799 myDisconnectUIServiceExtensionAbility() { 2800 let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 2801 2802 try { 2803 // 断开UIServiceExtension连接 2804 context.disconnectUIServiceExtensionAbility(this.comProxy) 2805 .then(() => { 2806 console.info(TAG + `disconnectUIServiceExtensionAbility succeed ${this.comProxy}`); 2807 }).catch((err: Error) => { 2808 let code = (err as BusinessError).code; 2809 let message = (err as BusinessError).message; 2810 console.info(TAG + `disconnectUIServiceExtensionAbility failed, code is ${code}, message is ${message}`); 2811 }); 2812 } catch (err) { 2813 let code = (err as BusinessError).code; 2814 let message = (err as BusinessError).message; 2815 console.info(TAG + `disconnectUIServiceExtensionAbility failed, code is ${code}, message is ${message}`); 2816 } 2817 } 2818} 2819``` 2820 2821### setAbilityInstanceInfo<sup>15+<sup> 2822 2823setAbilityInstanceInfo(label: string, icon: image.PixelMap) : Promise<void> 2824 2825设置当前UIAbility实例的图标和标签信息。图标与标签信息可在任务中心和快捷栏的界面中显示。使用Promise异步回调。 2826 2827**需要权限**： ohos.permission.SET_ABILITY_INSTANCE_INFO 2828 2829**系统能力**： SystemCapability.Ability.AbilityRuntime.Core 2830 2831**设备行为差异**：该接口仅在2in1设备中可正常调用，在其他设备中返回801错误码。 2832 2833**参数**： 2834 2835| 参数名 | 类型 | 必填 | 说明 | 2836| ------ | -------------------------------------------------------------- | ---- | -------------------------------------------------- | 2837| label |string | 是 | 新的标题。标题长度不超过1024字节，标题不可为空字符串。 | 2838| icon | [image.PixelMap](../apis-image-kit/arkts-apis-image-PixelMap.md) | 是 | 新的图标。建议图标大小为512px*512px。 | 2839 2840**返回值**： 2841 2842| 类型 | 说明 | 2843| ------------------- | -------------------------------------- | 2844| Promise<void> | Promise对象，包含接口执行结果。 | 2845 2846**错误码**： 2847 2848以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 2849 2850| 错误码ID | 错误信息 | 2851| -------- | ----------------------------------------------------------------------------------- | 2852| 201 | The application does not have permission to call the interface. | 2853| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 2854| 801 | Capability not supported. | 2855| 16000011 | The context does not exist. | 2856| 16000050 | Internal error. | 2857 2858**示例**： 2859 2860```ts 2861import { UIAbility } from '@kit.AbilityKit'; 2862import { image } from '@kit.ImageKit'; 2863import { BusinessError } from '@kit.BasicServicesKit'; 2864import { window } from '@kit.ArkUI'; 2865 2866export default class EntryAbility extends UIAbility { 2867 onWindowStageCreate(windowStage: window.WindowStage): void { 2868 windowStage.loadContent('pages/Index', async (err, data) => { 2869 if (err.code) { 2870 console.error(`loadContent failed, code is ${err.code}`); 2871 return; 2872 } 2873 2874 let newLabel: string = 'instance label'; 2875 let color = new ArrayBuffer(512 * 512 * 4); // 创建一个ArrayBuffer对象，用于存储图像像素。该对象的大小为（height * width * 4）字节。 2876 let bufferArr = new Uint8Array(color); 2877 for (let i = 0; i < bufferArr.length; i += 4) { 2878 bufferArr[i] = 255; 2879 bufferArr[i+1] = 0; 2880 bufferArr[i+2] = 122; 2881 bufferArr[i+3] = 255; 2882 } 2883 let opts: image.InitializationOptions = { 2884 editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 512, width: 512 } 2885 }; 2886 let imagePixelMap: image.PixelMap = await image.createPixelMap(color, opts); 2887 this.context.setAbilityInstanceInfo(newLabel, imagePixelMap) 2888 .then(() => { 2889 console.info('setAbilityInstanceInfo success'); 2890 }).catch((err: BusinessError) => { 2891 console.error(`setAbilityInstanceInfo failed, code is ${err.code}, message is ${err.message}`); 2892 }); 2893 }); 2894 } 2895} 2896``` 2897 2898### revokeDelegator<sup>17+</sup> 2899 2900revokeDelegator() : Promise<void> 2901 2902如果Module下首个UIAbility启动时期望重定向到另一个UIAbility，该重定向的UIAbility被称为“DelegatorAbility”。DelegatorAbility的设置详见当前接口示例的步骤1。 2903 2904当DelegatorAbility完成特定操作时，可以使用该接口回到首个UIAbility。使用Promise异步回调。 2905 2906> **说明**： 2907> 2908> 当接口调用成功后，DelegatorAbility中的[Window](../apis-arkui/arkts-apis-window.md)方法会失效。 2909 2910**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 2911 2912**返回值**： 2913 2914| 类型 | 说明 | 2915| ------------------- | -------------------------------------- | 2916| Promise<void> | Promise对象，包含接口执行结果。 | 2917 2918**错误码**： 2919 2920以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 2921 2922| 错误码ID | 错误信息 | 2923| ------- | -------- | 2924| 801 | Capability not support. | 2925| 16000011 | The context does not exist. | 2926| 16000050 | Internal error. | 2927| 16000065 | The API can be called only when the ability is running in the foreground. | 2928| 16000084 | Only DelegatorAbility is allowed to call this API, and only once. | 2929| 16000085 | An error occurred during the interaction between the ability and window. | 2930 2931**示例**： 2932 29331. 设置DelegatorAbility。 2934 2935 在[module.json5](../../quick-start/module-configuration-file.md)配置文件标签中配置abilitySrcEntryDelegator和abilityStageSrcEntryDelegator。当Module下首个UIAbility冷启动时，系统优先启动abilitySrcEntryDelegator指向的UIAbility。 2936 > **说明**： 2937 > 2938 > - 当UIAbility是通过[startAbilityByCall](#startabilitybycall)启动时，系统会忽略在[module.json5](../../quick-start/module-configuration-file.md)配置文件标签中配置的abilitySrcEntryDelegator和abilityStageSrcEntryDelegator。 2939 > - abilityStageSrcEntryDelegator指定的ModuleName不能与当前ModuleName相同。 2940 ```json 2941 { 2942 "module": { 2943 // ... 2944 "abilityStageSrcEntryDelegator": "xxxModuleName", 2945 "abilitySrcEntryDelegator": "xxxAbilityName", 2946 // ... 2947 } 2948 } 2949 ``` 2950 29512. 取消DelegatorAbility。 2952 2953 ```ts 2954 import { UIAbility } from '@kit.AbilityKit'; 2955 import { BusinessError } from '@kit.BasicServicesKit'; 2956 2957 export default class DelegatorAbility extends UIAbility { 2958 onForeground() { 2959 // DelegatorAbility完成特定操作后，调用revokeDelegator回到首个UIAbility 2960 this.context.revokeDelegator().then(() => { 2961 console.info('revokeDelegator success'); 2962 }).catch((err: BusinessError) => { 2963 console.error(`revokeDelegator failed, code is ${err.code}, message is ${err.message}`); 2964 }); 2965 } 2966 } 2967 ``` 2968 2969### setColorMode<sup>18+</sup> 2970 2971setColorMode(colorMode: ConfigurationConstant.ColorMode): void 2972 2973设置UIAbility的深浅色模式。调用该接口前需要保证该UIAbility对应页面已完成加载。仅支持主线程调用。 2974 2975> **说明**： 2976> - 调用该接口前，需要确保窗口已完成创建、且UIAbility对应的页面已完成加载，即在[onWindowStageCreate()](js-apis-app-ability-uiAbility.md#onwindowstagecreate)生命周期中通过[loadContent](../apis-arkui/arkts-apis-window-WindowStage.md#loadcontent9)方法加载页面之后调用。 2977> - 调用该接口后会创建新的资源管理器对象，如果此前有缓存资源管理器，需要进行更新。 2978> - 深浅色模式生效的优先级：UIAbility的深浅色模式 > 应用的深浅色模式（[ApplicationContext.setColorMode](js-apis-inner-application-applicationContext.md#applicationcontextsetcolormode11)）> 系统的深浅色模式。 2979 2980**原子化服务API**：从API version 18开始，该接口支持在原子化服务中使用。 2981 2982**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 2983 2984**参数**： 2985 2986| 参数名 | 类型 | 必填 | 说明 | 2987| ------ | ------------- | ---- | -------------------- | 2988| colorMode | [ConfigurationConstant.ColorMode](js-apis-app-ability-configurationConstant.md) | 是 | 设置颜色模式，包括: <br> - COLOR_MODE_DARK：深色模式 <br> - COLOR_MODE_LIGHT：浅色模式 <br> - COLOR_MODE_NOT_SET：不设置（跟随系统或应用）| 2989 2990**错误码**： 2991 2992以下错误码详细介绍请参考[元能力子系统错误码](errorcode-ability.md)。 2993 2994| 错误码ID | 错误信息 | 2995| ------- | -------- | 2996| 16000011 | The context does not exist. | 2997 2998**示例**： 2999 3000```ts 3001import { UIAbility, ConfigurationConstant } from '@kit.AbilityKit'; 3002import { hilog } from '@kit.PerformanceAnalysisKit'; 3003import { window } from '@kit.ArkUI'; 3004 3005export default class MyAbility extends UIAbility { 3006 onWindowStageCreate(windowStage: window.WindowStage) { 3007 windowStage.loadContent('pages/Index', (err, data) => { 3008 if (err.code) { 3009 hilog.error(0x0000, 'testTag', 'Failed to load the content.'); 3010 return; 3011 } 3012 let uiAbilityContext = this.context; 3013 uiAbilityContext.setColorMode(ConfigurationConstant.ColorMode.COLOR_MODE_DARK); 3014 }); 3015 } 3016} 3017``` 3018 3019### startAppServiceExtensionAbility<sup>20+</sup> 3020 3021startAppServiceExtensionAbility(want: Want): Promise\<void> 3022 3023启动[AppServiceExtensionAbility](js-apis-app-ability-appServiceExtensionAbility.md)实例。使用Promise异步回调。 3024 3025> **说明：** 3026> 3027> 该接口的调用方必须为[AppServiceExtensionAbility](js-apis-app-ability-appServiceExtensionAbility.md)所属应用或者在AppServiceExtensionAbility支持的应用清单（即[extensionAbilities标签](../../quick-start/module-configuration-file.md#extensionabilities标签)的appIdentifierAllowList属性）中的应用。 3028 3029**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 3030 3031**设备行为差异**：该接口仅在2in1设备中可正常调用，在其他设备中返回801错误码。 3032 3033**参数：** 3034 3035| 参数名 | 类型 | 必填 | 说明 | 3036| -------- | -------- | -------- | -------- | 3037| want | [Want](js-apis-app-ability-want.md) | 是 | 启动[AppServiceExtensionAbility](js-apis-app-ability-appServiceExtensionAbility.md)的Want信息。 | 3038 3039**返回值**： 3040 3041| 类型 | 说明 | 3042| ------------------- | -------------------------------------- | 3043| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 3044 3045**错误码：** 3046 3047以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 3048 3049| 错误码ID | 错误信息 | 3050| ------- | -------------------------------- | 3051| 801 | Capability not supported. | 3052| 16000001 | The specified ability does not exist. | 3053| 16000002 | Incorrect ability type. | 3054| 16000004 | Cannot start an invisible component. | 3055| 16000005 | The specified process does not have the permission. | 3056| 16000006 | Cross-user operations are not allowed. | 3057| 16000008 | The crowdtesting application expires. | 3058| 16000011 | The context does not exist. | 3059| 16000012 | The application is controlled. | 3060| 16000013 | The application is controlled by EDM. | 3061| 16000019 | No matching ability is found. | 3062| 16000050 | Internal error. | 3063| 16000200 | The caller is not in the appIdentifierAllowList of the target application. | 3064 3065**示例：** 3066 3067```ts 3068import { UIAbility, Want } from '@kit.AbilityKit'; 3069import { BusinessError } from '@kit.BasicServicesKit'; 3070 3071export default class EntryAbility extends UIAbility { 3072 onForeground() { 3073 let want: Want = { 3074 deviceId: '', 3075 bundleName: 'com.example.myapplication', 3076 abilityName: 'AppServiceExtensionAbility' 3077 }; 3078 3079 try { 3080 this.context.startAppServiceExtensionAbility(want) 3081 .then(() => { 3082 // 执行正常业务 3083 console.info('startAppServiceExtensionAbility succeed'); 3084 }) 3085 .catch((err: BusinessError) => { 3086 // 处理业务逻辑错误 3087 console.error(`startAppServiceExtensionAbility failed, code is ${err.code}, message is ${err.message}`); 3088 }); 3089 } catch (err) { 3090 // 处理入参错误异常 3091 let code = (err as BusinessError).code; 3092 let message = (err as BusinessError).message; 3093 console.error(`startAppServiceExtensionAbility failed, code is ${code}, message is ${message}`); 3094 } 3095 } 3096} 3097``` 3098 3099### stopAppServiceExtensionAbility<sup>20+</sup> 3100 3101stopAppServiceExtensionAbility(want: Want): Promise\<void> 3102 3103停止[AppServiceExtensionAbility](js-apis-app-ability-appServiceExtensionAbility.md)实例。使用Promise异步回调。 3104 3105> **说明：** 3106> 3107> 该接口的调用方必须为[AppServiceExtensionAbility](js-apis-app-ability-appServiceExtensionAbility.md)所属应用或者在AppServiceExtensionAbility支持的应用清单（即[extensionAbilities标签](../../quick-start/module-configuration-file.md#extensionabilities标签)的appIdentifierAllowList属性）中的应用。 3108 3109**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 3110 3111**设备行为差异**：该接口仅在2in1设备中可正常调用，在其他设备中返回801错误码。 3112 3113**参数：** 3114 3115| 参数名 | 类型 | 必填 | 说明 | 3116| -------- | -------- | -------- | -------- | 3117| want | [Want](js-apis-app-ability-want.md) | 是 | 停止[AppServiceExtensionAbility](js-apis-app-ability-appServiceExtensionAbility.md)的Want信息。 | 3118 3119**返回值**： 3120 3121| 类型 | 说明 | 3122| ------------------- | -------------------------------------- | 3123| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 3124 3125**错误码：** 3126 3127以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 3128 3129| 错误码ID | 错误信息 | 3130| ------- | -------------------------------- | 3131| 801 | Capability not supported. | 3132| 16000001 | The specified ability does not exist. | 3133| 16000002 | Incorrect ability type. | 3134| 16000004 | Cannot start an invisible component. | 3135| 16000005 | The specified process does not have the permission. | 3136| 16000006 | Cross-user operations are not allowed. | 3137| 16000011 | The context does not exist. | 3138| 16000050 | Internal error. | 3139| 16000200 | The caller is not in the appIdentifierAllowList of the target application. | 3140 3141**示例：** 3142 3143```ts 3144import { UIAbility, Want } from '@kit.AbilityKit'; 3145import { BusinessError } from '@kit.BasicServicesKit'; 3146 3147export default class EntryAbility extends UIAbility { 3148 onForeground() { 3149 let want: Want = { 3150 deviceId: '', 3151 bundleName: 'com.example.myapplication', 3152 abilityName: 'AppServiceExtensionAbility' 3153 }; 3154 3155 try { 3156 this.context.stopAppServiceExtensionAbility(want) 3157 .then(() => { 3158 // 执行正常业务 3159 console.info('stopAppServiceExtensionAbility succeed'); 3160 }) 3161 .catch((err: BusinessError) => { 3162 // 处理业务逻辑错误 3163 console.error(`stopAppServiceExtensionAbility failed, code is ${err.code}, message is ${err.message}`); 3164 }); 3165 } catch (err) { 3166 // 处理入参错误异常 3167 let code = (err as BusinessError).code; 3168 let message = (err as BusinessError).message; 3169 console.error(`stopAppServiceExtensionAbility failed, code is ${code}, message is ${message}`); 3170 } 3171 } 3172} 3173``` 3174 3175### connectAppServiceExtensionAbility<sup>20+</sup> 3176 3177connectAppServiceExtensionAbility(want: Want, callback: ConnectOptions): number 3178 3179将当前UIAbility连接到[AppServiceExtensionAbility](js-apis-app-ability-appServiceExtensionAbility.md)。通过返回的proxy与AppServiceExtensionAbility进行通信，以使用AppServiceExtensionAbility对外提供的能力。仅支持在主线程调用。 3180 3181> **说明：** 3182> 3183> 如果[AppServiceExtensionAbility](js-apis-app-ability-appServiceExtensionAbility.md)实例未启动，该接口的调用方必须为AppServiceExtensionAbility所属应用或者在AppServiceExtensionAbility支持的应用清单（即[extensionAbilities标签](../../quick-start/module-configuration-file.md#extensionabilities标签)的appIdentifierAllowList属性）中的应用。 3184 3185**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 3186 3187**设备行为差异**：该接口仅在2in1设备中可正常调用，在其他设备中返回801错误码。 3188 3189**参数：** 3190 3191| 参数名 | 类型 | 必填 | 说明 | 3192| -------- | -------- | -------- | -------- | 3193| want | [Want](js-apis-app-ability-want.md) | 是 | 连接[AppServiceExtensionAbility](js-apis-app-ability-appServiceExtensionAbility.md)的Want信息。 | 3194| callback | [ConnectOptions](js-apis-inner-ability-connectOptions.md) | 是 | ConnectOptions类型的回调函数，返回服务连接成功、连接失败、断开的信息。 | 3195 3196**返回值：** 3197 3198| 类型 | 说明 | 3199| -------- | -------- | 3200| number | 返回连接id，[disconnectAppServiceExtensionAbility](#disconnectappserviceextensionability20)根据该连接id断开连接。 | 3201 3202**错误码：** 3203 3204以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 3205 3206| 错误码ID | 错误信息 | 3207| ------- | -------------------------------- | 3208| 801 | Capability not supported. | 3209| 16000001 | The specified ability does not exist. | 3210| 16000002 | Incorrect ability type. | 3211| 16000004 | Cannot start an invisible component. | 3212| 16000005 | The specified process does not have the permission. | 3213| 16000006 | Cross-user operations are not allowed. | 3214| 16000008 | The crowdtesting application expires. | 3215| 16000011 | The context does not exist. | 3216| 16000050 | Internal error. | 3217| 16000201 | The target service has not been started yet. | 3218 3219**示例：** 3220 3221```ts 3222import { UIAbility, Want, common } from '@kit.AbilityKit'; 3223import { rpc } from '@kit.IPCKit'; 3224import { BusinessError } from '@kit.BasicServicesKit'; 3225 3226export default class EntryAbility extends UIAbility { 3227 onForeground() { 3228 let want: Want = { 3229 deviceId: '', 3230 bundleName: 'com.example.myapplication', 3231 abilityName: 'AppServiceExtensionAbility' 3232 }; 3233 let commRemote: rpc.IRemoteObject; 3234 let callback: common.ConnectOptions = { 3235 onConnect(elementName, remote) { 3236 commRemote = remote; 3237 console.info('onConnect...'); 3238 }, 3239 onDisconnect(elementName) { 3240 console.info('onDisconnect...'); 3241 }, 3242 onFailed(code) { 3243 console.info('onFailed...'); 3244 } 3245 }; 3246 let connection: number; 3247 3248 try { 3249 connection = this.context.connectAppServiceExtensionAbility(want, callback); 3250 } catch (err) { 3251 // 处理入参错误异常 3252 let code = (err as BusinessError).code; 3253 let message = (err as BusinessError).message; 3254 console.error(`connectAppServiceExtensionAbility failed, code is ${code}, message is ${message}`); 3255 } 3256 } 3257} 3258``` 3259 3260### disconnectAppServiceExtensionAbility<sup>20+</sup> 3261 3262disconnectAppServiceExtensionAbility(connection: number): Promise\<void> 3263 3264断开与[AppServiceExtensionAbility](js-apis-app-ability-appServiceExtensionAbility.md)的连接。仅支持在主线程调用。使用Promise异步回调。 3265 3266断开连接之后，为了防止使用可能失效的remote对象进行通信，建议将连接成功时返回的remote对象设置为null。 3267 3268**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 3269 3270**设备行为差异**：该接口仅在2in1设备中可正常调用，在其他设备中返回801错误码。 3271 3272**参数：** 3273 3274| 参数名 | 类型 | 必填 | 说明 | 3275| -------- | -------- | -------- | -------- | 3276| connection | number | 是 | 在[connectAppServiceExtensionAbility](#connectappserviceextensionability20)返回的连接id。 | 3277 3278**返回值：** 3279 3280| 类型 | 说明 | 3281| -------- | -------- | 3282| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 3283 3284**错误码：** 3285 3286以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 3287 3288| 错误码ID | 错误信息 | 3289| ------- | -------------------------------- | 3290| 801 | Capability not supported. | 3291| 16000011 | The context does not exist. | 3292| 16000050 | Internal error. | 3293 3294**示例：** 3295 3296```ts 3297import { UIAbility } from '@kit.AbilityKit'; 3298import { rpc } from '@kit.IPCKit'; 3299import { BusinessError } from '@kit.BasicServicesKit'; 3300 3301export default class EntryAbility extends UIAbility { 3302 onForeground() { 3303 // connection为connectAppServiceExtensionAbility中的返回值 3304 let connection = 1; 3305 let commRemote: rpc.IRemoteObject | null; 3306 3307 try { 3308 this.context.disconnectAppServiceExtensionAbility(connection).then(() => { 3309 commRemote = null; 3310 // 执行正常业务 3311 console.info('disconnectAppServiceExtensionAbility succeed'); 3312 }).catch((err: BusinessError) => { 3313 // 处理业务逻辑错误 3314 console.error(`disconnectAppServiceExtensionAbility failed, code is ${err.code}, message is ${err.message}`); 3315 }); 3316 } catch (err) { 3317 commRemote = null; 3318 // 处理入参错误异常 3319 let code = (err as BusinessError).code; 3320 let message = (err as BusinessError).message; 3321 console.error(`disconnectAppServiceExtensionAbility failed, code is ${code}, message is ${message}`); 3322 } 3323 } 3324} 3325``` 3326 3327### setOnNewWantSkipScenarios<sup>20+</sup> 3328 3329setOnNewWantSkipScenarios(scenarios: number): Promise\<void> 3330 3331在特定场景下拉起UIAbility时，如果不需要触发[onNewWant](./js-apis-app-ability-uiAbility.md#onnewwant)生命周期回调，可以通过该接口设置。仅支持在主线程调用。使用Promise异步回调。 3332 3333> **说明：** 3334> 3335> 该接口通常用于[onCreate](./js-apis-app-ability-uiAbility.md#oncreate)生命周期回调中。入参取值建议包含所有的[Scenarios](js-apis-app-ability-contextConstant.md#scenarios20)枚举值。详见下方示例代码。 3336 3337**原子化服务API**：从API version 20开始，该接口支持在原子化服务中使用。 3338 3339**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 3340 3341**参数：** 3342 3343| 参数名 | 类型 | 必填 | 说明 | 3344| -------- | -------- | -------- | -------- | 3345| scenarios | number | 是 | 取值范围请参考[Scenarios](./js-apis-app-ability-contextConstant.md#scenarios20)。 | 3346 3347**返回值：** 3348 3349| 类型 | 说明 | 3350| -------- | -------- | 3351| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 3352 3353**错误码：** 3354 3355以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 3356 3357| 错误码ID | 错误信息 | 3358| ------- | -------------------------------- | 3359| 16000050 | Internal error. Possible causes: Connection to service failed. | 3360 3361**示例：** 3362 3363```ts 3364import { AbilityConstant, contextConstant, UIAbility, Want } from '@kit.AbilityKit'; 3365import { BusinessError } from '@kit.BasicServicesKit'; 3366 3367export default class EntryAbility extends UIAbility { 3368 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 3369 let scenarios: number = contextConstant.Scenarios.SCENARIO_MOVE_MISSION_TO_FRONT | 3370 contextConstant.Scenarios.SCENARIO_SHOW_ABILITY | 3371 contextConstant.Scenarios.SCENARIO_BACK_TO_CALLER_ABILITY_WITH_RESULT; 3372 3373 try { 3374 this.context.setOnNewWantSkipScenarios(scenarios).then(() => { 3375 // 执行正常业务 3376 console.info('setOnNewWantSkipScenarios succeed'); 3377 }).catch((err: BusinessError) => { 3378 // 处理业务逻辑错误 3379 console.error(`setOnNewWantSkipScenarios failed, code is ${err.code}, message is ${err.message}`); 3380 }); 3381 } catch (err) { 3382 // 处理入参错误异常 3383 let code = (err as BusinessError).code; 3384 let message = (err as BusinessError).message; 3385 console.error(`setOnNewWantSkipScenarios failed, code is ${code}, message is ${message}`); 3386 } 3387 } 3388} 3389```