1# ServiceExtensionContext 2 3ServiceExtensionContext模块是ServiceExtensionAbility的上下文环境，继承自ExtensionContext。 4 5ServiceExtensionContext模块提供ServiceExtensionAbility具有的能力，包括启动、停止、绑定、解绑Ability。 6 7> **说明：** 8> 9> - 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 10> - 本模块接口仅可在Stage模型下使用。 11 12## 导入模块 13 14```ts 15import common from '@ohos.app.ability.common'; 16``` 17 18## 使用说明 19 20在使用ServiceExtensionContext的功能前，需要通过ServiceExtensionAbility子类实例获取。 21 22```ts 23 import ServiceExtensionAbility from '@ohos.app.ability.ServiceExtensionAbility'; 24 import rpc from '@ohos.rpc'; 25 26 let commRemote: rpc.IRemoteObject; // 断开连接时需要释放 27 class EntryAbility extends ServiceExtensionAbility { 28 onCreate() { 29 let context = this.context; // 获取ServiceExtensionContext 30 } 31 } 32``` 33 34## ServiceExtensionContext.startAbility 35 36startAbility(want: Want, callback: AsyncCallback<void>): void; 37 38启动Ability。 39 40**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 41 42**系统API**: 此接口为系统接口，三方应用不支持调用。 43 44**参数：** 45 46| 参数名 | 类型 | 必填 | 说明 | 47| -------- | -------- | -------- | -------- | 48| want | [Want](js-apis-app-ability-want.md) | 是 | Want类型参数，传入需要启动的ability的信息，如Ability名称，Bundle名称等。 | 49| callback | AsyncCallback<void> | 是 | 回调函数，返回接口调用是否成功的结果。 | 50 51**错误码：** 52 53| 错误码ID | 错误信息 | 54| ------- | -------------------------------- | 55| 16000001 | The specified ability does not exist. | 56| 16000002 | Incorrect ability type. | 57| 16000004 | Can not start invisible component. | 58| 16000005 | The specified process does not have the permission. | 59| 16000006 | Cross-user operations are not allowed. | 60| 16000008 | The crowdtesting application expires. | 61| 16000009 | An ability cannot be started or stopped in Wukong mode. | 62| 16000010 | The call with the continuation flag is forbidden. | 63| 16000011 | The context does not exist. | 64| 16000012 | The application is controlled. | 65| 16000013 | The application is controlled by EDM. | 66| 16000050 | Internal error. | 67| 16000053 | The ability is not on the top of the UI. | 68| 16000055 | Installation-free timed out. | 69| 16200001 | The caller has been released. | 70 71以上错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 72 73**示例：** 74 75 ```ts 76 import Want from '@ohos.app.ability.Want'; 77 import { BusinessError } from '@ohos.base'; 78 79 let want: Want = { 80 bundleName: 'com.example.myapp', 81 abilityName: 'MyAbility' 82 }; 83 84 try { 85 this.context.startAbility(want, (error: BusinessError) => { 86 if (error.code) { 87 // 处理业务逻辑错误 88 console.error('startAbility failed, error.code: ${error.code}, error.message: ${error.message}'); 89 return; 90 } 91 // 执行正常业务 92 console.log('startAbility succeed'); 93 }); 94 } catch (paramError) { 95 // 处理入参错误异常 96 console.error('error.code: ${paramError.code}, error.message: ${paramError.message}'); 97 } 98 ``` 99 100## ServiceExtensionContext.startAbility 101 102startAbility(want: Want, options?: StartOptions): Promise\<void>; 103 104启动Ability，结果以Promise的形式返回。 105 106**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 107 108**系统API**: 此接口为系统接口，三方应用不支持调用。 109 110**参数：** 111 112| 参数名 | 类型 | 必填 | 说明 | 113| -------- | -------- | -------- | -------- | 114| want | [Want](js-apis-app-ability-want.md) | 是 | Want类型参数，传入需要启动的ability的信息，如Ability名称，Bundle名称等。 | 115| options | [StartOptions](js-apis-app-ability-startOptions.md) | 否 | 启动Ability所携带的参数。 | 116 117**返回值：** 118 119| 类型 | 说明 | 120| -------- | -------- | 121| Promise<void> | 返回一个Promise，包含启动的结果。 | 122 123**错误码：** 124 125| 错误码ID | 错误信息 | 126| ------- | -------------------------------- | 127| 16000001 | The specified ability does not exist. | 128| 16000002 | Incorrect ability type. | 129| 16000004 | Can not start invisible component. | 130| 16000005 | The specified process does not have the permission. | 131| 16000006 | Cross-user operations are not allowed. | 132| 16000008 | The crowdtesting application expires. | 133| 16000009 | An ability cannot be started or stopped in Wukong mode. | 134| 16000010 | The call with the continuation flag is forbidden. | 135| 16000011 | The context does not exist. | 136| 16000012 | The application is controlled. | 137| 16000013 | The application is controlled by EDM. | 138| 16000050 | Internal error. | 139| 16000053 | The ability is not on the top of the UI. | 140| 16000055 | Installation-free timed out. | 141| 16200001 | The caller has been released. | 142 143以上错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 144 145**示例：** 146 147 ```ts 148 import Want from '@ohos.app.ability.Want'; 149 import StartOptions from '@ohos.app.ability.StartOptions'; 150 import { BusinessError } from '@ohos.base'; 151 152 let want: Want = { 153 bundleName: 'com.example.myapp', 154 abilityName: 'MyAbility' 155 }; 156 let options: StartOptions = { 157 windowMode: 0, 158 }; 159 160 try { 161 this.context.startAbility(want, options) 162 .then((data: void) => { 163 // 执行正常业务 164 console.log('startAbility succeed'); 165 }) 166 .catch((error: BusinessError) => { 167 // 处理业务逻辑错误 168 console.error('startAbility failed, error.code: ${error.code}, error.message: ${error.message}'); 169 }); 170 } catch (paramError) { 171 // 处理入参错误异常 172 console.error('error.code: ${paramError.code}, error.message: ${paramError.message}'); 173 } 174 ``` 175 176## ServiceExtensionContext.startAbility 177 178startAbility(want: Want, options: StartOptions, callback: AsyncCallback<void>): void 179 180启动Ability，结果以Callback的形式返回。 181 182**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 183 184**系统API**: 此接口为系统接口，三方应用不支持调用。 185 186**参数：** 187 188| 参数名 | 类型 | 必填 | 说明 | 189| -------- | -------- | -------- | -------- | 190| want | [Want](js-apis-app-ability-want.md) | 是 | 启动Ability的want信息。 | 191| options | [StartOptions](js-apis-app-ability-startOptions.md) | 是 | 启动Ability所携带的参数。 | 192| callback | AsyncCallback<void> | 是 | callback形式返回启动结果。 | 193 194**错误码：** 195 196| 错误码ID | 错误信息 | 197| ------- | -------------------------------- | 198| 16000001 | The specified ability does not exist. | 199| 16000002 | Incorrect ability type. | 200| 16000004 | Can not start invisible component. | 201| 16000005 | The specified process does not have the permission. | 202| 16000006 | Cross-user operations are not allowed. | 203| 16000008 | The crowdtesting application expires. | 204| 16000009 | An ability cannot be started or stopped in Wukong mode. | 205| 16000010 | The call with the continuation flag is forbidden. | 206| 16000011 | The context does not exist. | 207| 16000012 | The application is controlled. | 208| 16000013 | The application is controlled by EDM. | 209| 16000050 | Internal error. | 210| 16000053 | The ability is not on the top of the UI. | 211| 16000055 | Installation-free timed out. | 212| 16200001 | The caller has been released. | 213 214以上错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 215 216**示例：** 217 218 ```ts 219 import Want from '@ohos.app.ability.Want'; 220 import StartOptions from '@ohos.app.ability.StartOptions'; 221 import { BusinessError } from '@ohos.base'; 222 223 let want: Want = { 224 deviceId: '', 225 bundleName: 'com.example.myapplication', 226 abilityName: 'EntryAbility' 227 }; 228 let options: StartOptions = { 229 windowMode: 0 230 }; 231 232 try { 233 this.context.startAbility(want, options, (error: BusinessError) => { 234 if (error.code) { 235 // 处理业务逻辑错误 236 console.error('startAbility failed, error.code: ${error.code}, error.message: ${error.message}'); 237 return; 238 } 239 // 执行正常业务 240 console.log('startAbility succeed'); 241 }); 242 } catch (paramError) { 243 // 处理入参错误异常 244 console.error('error.code: ${paramError.code}, error.message: ${paramError.message}'); 245 } 246 ``` 247 248## ServiceExtensionContext.startAbilityWithAccount 249 250startAbilityWithAccount(want: Want, accountId: number, callback: AsyncCallback\<void>): void; 251 252根据account启动Ability（callback形式）。 253 254使用规则： 255 - 调用方应用位于后台时，使用该接口启动Ability需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限 256 - 跨应用场景下，目标Ability的exported属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限 257 - 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md) 258 259**需要权限**：ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS 260 261**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 262 263**系统API**: 此接口为系统接口，三方应用不支持调用。 264 265**参数：** 266 267| 参数名 | 类型 | 必填 | 说明 | 268| -------- | -------- | -------- | -------- | 269| want | [Want](js-apis-app-ability-want.md) | 是 | 启动Ability的want信息。 | 270| accountId | number | 是 | 系统帐号的帐号ID，详情参考[getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess)。 | 271| callback | AsyncCallback\<void\> | 是 | 启动Ability的回调函数。 | 272 273**错误码：** 274 275| 错误码ID | 错误信息 | 276| ------- | -------------------------------- | 277| 16000001 | The specified ability does not exist. | 278| 16000002 | Incorrect ability type. | 279| 16000004 | Can not start invisible component. | 280| 16000005 | The specified process does not have the permission. | 281| 16000006 | Cross-user operations are not allowed. | 282| 16000008 | The crowdtesting application expires. | 283| 16000009 | An ability cannot be started or stopped in Wukong mode. | 284| 16000010 | The call with the continuation flag is forbidden. | 285| 16000011 | The context does not exist. | 286| 16000012 | The application is controlled. | 287| 16000013 | The application is controlled by EDM. | 288| 16000050 | Internal error. | 289| 16000053 | The ability is not on the top of the UI. | 290| 16000055 | Installation-free timed out. | 291| 16200001 | The caller has been released. | 292 293以上错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 294 295**示例：** 296 297 ```ts 298 import Want from '@ohos.app.ability.Want'; 299 import { BusinessError } from '@ohos.base'; 300 301 let want: Want = { 302 deviceId: '', 303 bundleName: 'com.example.myapplication', 304 abilityName: 'EntryAbility' 305 }; 306 let accountId = 100; 307 308 try { 309 this.context.startAbilityWithAccount(want, accountId, (error: BusinessError) => { 310 if (error.code) { 311 // 处理业务逻辑错误 312 console.error('startAbilityWithAccount failed, error.code: ${error.code}, error.message: ${error.message}'); 313 return; 314 } 315 // 执行正常业务 316 console.log('startAbilityWithAccount succeed'); 317 }); 318 } catch (paramError) { 319 // 处理入参错误异常 320 console.error('error.code: ${paramError.code}, error.message: ${paramError.message}'); 321 } 322 ``` 323 324## ServiceExtensionContext.startAbilityWithAccount 325 326startAbilityWithAccount(want: Want, accountId: number, options: StartOptions, callback: AsyncCallback\<void\>): void; 327 328根据account启动Ability（callback形式）。 329 330使用规则： 331 - 调用方应用位于后台时，使用该接口启动Ability需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限 332 - 跨应用场景下，目标Ability的exported属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限 333 - 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md) 334 335**需要权限**：ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS 336 337**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 338 339**系统API**: 此接口为系统接口，三方应用不支持调用。 340 341**参数：** 342 343| 参数名 | 类型 | 必填 | 说明 | 344| -------- | -------- | -------- | -------- | 345| want | [Want](js-apis-app-ability-want.md) | 是 | 启动Ability的want信息。 | 346| accountId | number | 是 | 系统帐号的帐号ID，详情参考[getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess)。 | 347| options | [StartOptions](js-apis-app-ability-startOptions.md) | 是 | 启动Ability所携带的参数。 | 348| callback | AsyncCallback\<void\> | 是 | 启动Ability的回调函数。 | 349 350**错误码：** 351 352| 错误码ID | 错误信息 | 353| ------- | -------------------------------- | 354| 16000001 | The specified ability does not exist. | 355| 16000002 | Incorrect ability type. | 356| 16000004 | Can not start invisible component. | 357| 16000005 | The specified process does not have the permission. | 358| 16000006 | Cross-user operations are not allowed. | 359| 16000008 | The crowdtesting application expires. | 360| 16000009 | An ability cannot be started or stopped in Wukong mode. | 361| 16000010 | The call with the continuation flag is forbidden. | 362| 16000011 | The context does not exist. | 363| 16000012 | The application is controlled. | 364| 16000013 | The application is controlled by EDM. | 365| 16000050 | Internal error. | 366| 16000053 | The ability is not on the top of the UI. | 367| 16000055 | Installation-free timed out. | 368| 16200001 | The caller has been released. | 369 370以上错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 371 372**示例：** 373 374 ```ts 375 import Want from '@ohos.app.ability.Want'; 376 import StartOptions from '@ohos.app.ability.StartOptions'; 377 import { BusinessError } from '@ohos.base'; 378 379 let want: Want = { 380 deviceId: '', 381 bundleName: 'com.example.myapplication', 382 abilityName: 'EntryAbility' 383 }; 384 let accountId = 100; 385 let options: StartOptions = { 386 windowMode: 0 387 }; 388 389 try { 390 this.context.startAbilityWithAccount(want, accountId, options, (error: BusinessError) => { 391 if (error.code) { 392 // 处理业务逻辑错误 393 console.error('startAbilityWithAccount failed, error.code: ${error.code}, error.message: ${error.message}'); 394 return; 395 } 396 // 执行正常业务 397 console.log('startAbilityWithAccount succeed'); 398 }); 399 } catch (paramError) { 400 // 处理入参错误异常 401 console.error('error.code: ${paramError.code}, error.message: ${paramError.message}'); 402 } 403 ``` 404 405 406## ServiceExtensionContext.startAbilityWithAccount 407 408startAbilityWithAccount(want: Want, accountId: number, options?: StartOptions): Promise\<void>; 409 410根据account启动Ability（Promise形式）。 411 412使用规则： 413 - 调用方应用位于后台时，使用该接口启动Ability需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限 414 - 跨应用场景下，目标Ability的exported属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限 415 - 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md) 416 417**需要权限**：ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS 418 419**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 420 421**系统API**: 此接口为系统接口，三方应用不支持调用。 422 423**参数：** 424 425| 参数名 | 类型 | 必填 | 说明 | 426| -------- | -------- | -------- | -------- | 427| want | [Want](js-apis-app-ability-want.md) | 是 | 启动Ability的want信息。 | 428| accountId | number | 是 | 系统帐号的帐号ID，详情参考[getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess)。。 | 429| options | [StartOptions](js-apis-app-ability-startOptions.md) | 否 | 启动Ability所携带的参数。 | 430 431**返回值：** 432 433| 类型 | 说明 | 434| -------- | -------- | 435| Promise<void> | 返回一个Promise，包含接口的结果。 | 436 437**错误码：** 438 439| 错误码ID | 错误信息 | 440| ------- | -------------------------------- | 441| 16000001 | The specified ability does not exist. | 442| 16000002 | Incorrect ability type. | 443| 16000004 | Can not start invisible component. | 444| 16000005 | The specified process does not have the permission. | 445| 16000006 | Cross-user operations are not allowed. | 446| 16000008 | The crowdtesting application expires. | 447| 16000009 | An ability cannot be started or stopped in Wukong mode. | 448| 16000010 | The call with the continuation flag is forbidden. | 449| 16000011 | The context does not exist. | 450| 16000012 | The application is controlled. | 451| 16000013 | The application is controlled by EDM. | 452| 16000050 | Internal error. | 453| 16000053 | The ability is not on the top of the UI. | 454| 16000055 | Installation-free timed out. | 455| 16200001 | The caller has been released. | 456 457以上错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 458 459**示例：** 460 461 ```ts 462 import Want from '@ohos.app.ability.Want'; 463 import StartOptions from '@ohos.app.ability.StartOptions'; 464 import { BusinessError } from '@ohos.base'; 465 466 let want: Want = { 467 deviceId: '', 468 bundleName: 'com.example.myapplication', 469 abilityName: 'EntryAbility' 470 }; 471 let accountId = 100; 472 let options: StartOptions = { 473 windowMode: 0 474 }; 475 476 try { 477 this.context.startAbilityWithAccount(want, accountId, options) 478 .then((data: void) => { 479 // 执行正常业务 480 console.log('startAbilityWithAccount succeed'); 481 }) 482 .catch((error: BusinessError) => { 483 // 处理业务逻辑错误 484 console.error('startAbilityWithAccount failed, error.code: ${error.code}, error.message: ${error.message}'); 485 }); 486 } catch (paramError) { 487 // 处理入参错误异常 488 console.error('error.code: ${paramError.code}, error.message: ${paramError.message}'); 489 } 490 ``` 491 492## ServiceExtensionContext.startServiceExtensionAbility 493 494startServiceExtensionAbility(want: Want, callback: AsyncCallback\<void>): void; 495 496启动一个新的ServiceExtensionAbility（callback形式）。 497 498**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 499 500**系统API**: 此接口为系统接口，三方应用不支持调用。 501 502**参数：** 503 504| 参数名 | 类型 | 必填 | 说明 | 505| -------- | -------- | -------- | -------- | 506| want | [Want](js-apis-app-ability-want.md) | 是 | 启动Ability的want信息。 | 507| callback | AsyncCallback\<void\> | 是 | 启动Ability的回调函数。 | 508 509**错误码：** 510 511| 错误码ID | 错误信息 | 512| ------- | -------------------------------- | 513| 16000001 | The specified ability does not exist. | 514| 16000002 | Incorrect ability type. | 515| 16000004 | Can not start invisible component. | 516| 16000005 | The specified process does not have the permission. | 517| 16000006 | Cross-user operations are not allowed. | 518| 16000008 | The crowdtesting application expires. | 519| 16000011 | The context does not exist. | 520| 16000012 | The application is controlled. | 521| 16000013 | The application is controlled by EDM. | 522| 16000050 | Internal error. | 523| 16200001 | The caller has been released. | 524 525以上错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 526 527**示例：** 528 529 ```ts 530 import Want from '@ohos.app.ability.Want'; 531 import { BusinessError } from '@ohos.base'; 532 533 let want: Want = { 534 deviceId: '', 535 bundleName: 'com.example.myapplication', 536 abilityName: 'EntryAbility' 537 }; 538 539 try { 540 this.context.startServiceExtensionAbility(want, (error: BusinessError) => { 541 if (error.code) { 542 // 处理业务逻辑错误 543 console.error('startServiceExtensionAbility failed, error.code: ${error.code}, error.message: ${error.message}'); 544 return; 545 } 546 // 执行正常业务 547 console.log('startServiceExtensionAbility succeed'); 548 }); 549 } catch (paramError) { 550 // 处理入参错误异常 551 console.error('error.code: ${paramError.code}, error.message: ${paramError.message}'); 552 } 553 ``` 554 555## ServiceExtensionContext.startServiceExtensionAbility 556 557startServiceExtensionAbility(want: Want): Promise\<void>; 558 559启动一个新的ServiceExtensionAbility（Promise形式）。 560 561**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 562 563**系统API**: 此接口为系统接口，三方应用不支持调用。 564 565**参数：** 566 567| 参数名 | 类型 | 必填 | 说明 | 568| -------- | -------- | -------- | -------- | 569| want | [Want](js-apis-app-ability-want.md) | 是 | 启动Ability的want信息。 | 570 571**返回值：** 572 573| 类型 | 说明 | 574| -------- | -------- | 575| Promise<void> | 返回一个Promise，包含接口的结果。 | 576 577**错误码：** 578 579| 错误码ID | 错误信息 | 580| ------- | -------------------------------- | 581| 16000001 | The specified ability does not exist. | 582| 16000002 | Incorrect ability type. | 583| 16000004 | Can not start invisible component. | 584| 16000005 | The specified process does not have the permission. | 585| 16000006 | Cross-user operations are not allowed. | 586| 16000008 | The crowdtesting application expires. | 587| 16000011 | The context does not exist. | 588| 16000012 | The application is controlled. | 589| 16000013 | The application is controlled by EDM. | 590| 16000050 | Internal error. | 591| 16200001 | The caller has been released. | 592 593以上错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 594 595**示例：** 596 597 ```ts 598 import Want from '@ohos.app.ability.Want'; 599 import { BusinessError } from '@ohos.base'; 600 601 let want: Want = { 602 deviceId: '', 603 bundleName: 'com.example.myapplication', 604 abilityName: 'EntryAbility' 605 }; 606 607 try { 608 this.context.startServiceExtensionAbility(want) 609 .then((data: void) => { 610 // 执行正常业务 611 console.log('startServiceExtensionAbility succeed'); 612 }) 613 .catch((error: BusinessError) => { 614 // 处理业务逻辑错误 615 console.error('startServiceExtensionAbility failed, error.code: ${error.code}, error.message: ${error.message}'); 616 }); 617 } catch (paramError) { 618 // 处理入参错误异常 619 console.error('error.code: ${paramError.code}, error.message: ${paramError.message}'); 620 } 621 ``` 622 623## ServiceExtensionContext.startServiceExtensionAbilityWithAccount 624 625startServiceExtensionAbilityWithAccount(want: Want, accountId: number, callback: AsyncCallback\<void>): void; 626 627启动一个新的ServiceExtensionAbility（callback形式）。 628 629> **说明：** 630> 631> 当accountId为当前用户时，不需要校验该权限。 632 633**需要权限**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS 634 635**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 636 637**系统API**: 此接口为系统接口，三方应用不支持调用。 638 639**参数：** 640 641| 参数名 | 类型 | 必填 | 说明 | 642| -------- | -------- | -------- | -------- | 643| want | [Want](js-apis-app-ability-want.md) | 是 | 启动Ability的want信息。 | 644| accountId | number | 是 | 系统帐号的帐号ID，详情参考[getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess)。 | 645| callback | AsyncCallback\<void\> | 是 | 启动Ability的回调函数。 | 646 647**错误码：** 648 649| 错误码ID | 错误信息 | 650| ------- | -------------------------------- | 651| 16000001 | The specified ability does not exist. | 652| 16000002 | Incorrect ability type. | 653| 16000004 | Can not start invisible component. | 654| 16000005 | The specified process does not have the permission. | 655| 16000006 | Cross-user operations are not allowed. | 656| 16000008 | The crowdtesting application expires. | 657| 16000011 | The context does not exist. | 658| 16000012 | The application is controlled. | 659| 16000013 | The application is controlled by EDM. | 660| 16000050 | Internal error. | 661| 16200001 | The caller has been released. | 662 663以上错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 664 665 666**示例：** 667 668 ```ts 669 import Want from '@ohos.app.ability.Want'; 670 import { BusinessError } from '@ohos.base'; 671 672 let want: Want = { 673 deviceId: '', 674 bundleName: 'com.example.myapplication', 675 abilityName: 'EntryAbility' 676 }; 677 let accountId = 100; 678 679 try { 680 this.context.startServiceExtensionAbilityWithAccount(want, accountId, (error: BusinessError) => { 681 if (error.code) { 682 // 处理业务逻辑错误 683 console.error('startServiceExtensionAbilityWithAccount failed, error.code: ${error.code}, error.message: ${error.message}'); 684 return; 685 } 686 // 执行正常业务 687 console.log('startServiceExtensionAbilityWithAccount succeed'); 688 }); 689 } catch (paramError) { 690 // 处理入参错误异常 691 console.error('error.code: ${paramError.code}, error.message: ${paramError.message}'); 692 } 693 ``` 694 695## ServiceExtensionContext.startServiceExtensionAbilityWithAccount 696 697startServiceExtensionAbilityWithAccount(want: Want, accountId: number): Promise\<void>; 698 699启动一个新的ServiceExtensionAbility（Promise形式）。 700 701> **说明：** 702> 703> 当accountId为当前用户时，不需要校验该权限。 704 705**需要权限**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS 706 707**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 708 709**系统API**: 此接口为系统接口，三方应用不支持调用。 710 711**参数：** 712 713| 参数名 | 类型 | 必填 | 说明 | 714| -------- | -------- | -------- | -------- | 715| want | [Want](js-apis-app-ability-want.md) | 是 | 启动Ability的want信息。 | 716| accountId | number | 是 | 系统帐号的帐号ID，详情参考[getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess)。 | 717 718**返回值：** 719 720| 类型 | 说明 | 721| -------- | -------- | 722| Promise<void> | 返回一个Promise，包含接口的结果。 | 723 724**错误码：** 725 726| 错误码ID | 错误信息 | 727| ------- | -------------------------------- | 728| 16000001 | The specified ability does not exist. | 729| 16000002 | Incorrect ability type. | 730| 16000004 | Can not start invisible component. | 731| 16000005 | The specified process does not have the permission. | 732| 16000006 | Cross-user operations are not allowed. | 733| 16000008 | The crowdtesting application expires. | 734| 16000011 | The context does not exist. | 735| 16000012 | The application is controlled. | 736| 16000013 | The application is controlled by EDM. | 737| 16000050 | Internal error. | 738| 16200001 | The caller has been released. | 739 740以上错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 741 742**示例：** 743 744 ```ts 745 import Want from '@ohos.app.ability.Want'; 746 import { BusinessError } from '@ohos.base'; 747 748 let want: Want = { 749 deviceId: '', 750 bundleName: 'com.example.myapplication', 751 abilityName: 'EntryAbility' 752 }; 753 let accountId = 100; 754 755 try { 756 this.context.startServiceExtensionAbilityWithAccount(want, accountId) 757 .then((data: void) => { 758 // 执行正常业务 759 console.log('startServiceExtensionAbilityWithAccount succeed'); 760 }) 761 .catch((error: BusinessError) => { 762 // 处理业务逻辑错误 763 console.error('startServiceExtensionAbilityWithAccount failed, error.code: ${error.code}, error.message: ${error.message}'); 764 }); 765 } catch (paramError) { 766 // 处理入参错误异常 767 console.error('error.code: ${paramError.code}, error.message: ${paramError.message}'); 768 } 769 ``` 770 771## ServiceExtensionContext.startAbilityAsCaller<sup>10+<sup> 772 773startAbilityAsCaller(want: Want, callback: AsyncCallback\<void>): void; 774 775使用设置的caller信息启动一个Ability，caller信息由want携带，在系统服务层识别，Ability可以在onCreate生命周期的want参数中获取到caller信息。使用该接口启动一个Ability时，want的caller信息不会被当前自身的应用信息覆盖，系统服务层可获取到初始caller的信息。使用callback异步回调。 776 777使用规则： 778 - 调用方应用位于后台时，使用该接口启动Ability需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限 779 - 跨应用场景下，目标Ability的exported属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限 780 - 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md) 781 782**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 783 784**系统API**: 此接口为系统接口，三方应用不支持调用。 785 786**参数：** 787 788| 参数名 | 类型 | 必填 | 说明 | 789| -------- | -------- | -------- | -------- | 790| want | [Want](js-apis-app-ability-want.md) | 是 | 启动Ability的want信息。 | 791| callback | AsyncCallback<void> | 是 | 回调函数。当启动Ability成功，err为undefined，否则为错误对象。 | 792 793**错误码：** 794 795| 错误码ID | 错误信息 | 796| ------- | -------------------------------- | 797| 16000001 | The specified ability does not exist. | 798| 16000002 | Incorrect ability type. | 799| 16000004 | Can not start invisible component. | 800| 16000005 | The specified process does not have the permission. | 801| 16000006 | Cross-user operations are not allowed. | 802| 16000008 | The crowdtesting application expires. | 803| 16000009 | An ability cannot be started or stopped in Wukong mode. | 804| 16000010 | The call with the continuation flag is forbidden. | 805| 16000011 | The context does not exist. | 806| 16000012 | The application is controlled. | 807| 16000013 | The application is controlled by EDM. | 808| 16000050 | Internal error. | 809| 16000053 | The ability is not on the top of the UI. | 810| 16000055 | Installation-free timed out. | 811| 16200001 | The caller has been released. | 812 813错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md) 814 815**示例：** 816 817```ts 818import extension from '@ohos.app.ability.ServiceExtensionAbility'; 819import Want from '@ohos.app.ability.Want'; 820 821export default class EntryAbility extends extension { 822 onCreate(want: Want) { 823 // want包含启动该应用的Caller信息 824 let localWant: Want = want; 825 localWant.bundleName = 'com.example.demo'; 826 localWant.moduleName = 'entry'; 827 localWant.abilityName = 'TestAbility'; 828 829 // 使用启动方的Caller身份信息启动新Ability 830 this.context.startAbilityAsCaller(localWant, (err) => { 831 if (err && err.code != 0) { 832 console.error('startAbilityAsCaller failed, err:' + JSON.stringify(err)); 833 } else { 834 console.log('startAbilityAsCaller success.'); 835 } 836 }) 837 } 838} 839 840``` 841 842## ServiceExtensionContext.startAbilityAsCaller<sup>10+<sup> 843 844startAbilityAsCaller(want: Want, options: StartOptions, callback: AsyncCallback\<void>): void; 845 846使用设置的caller信息启动一个Ability，caller信息由want携带，在系统服务层识别，Ability可以在onCreate生命周期的want参数中获取到caller信息。使用该接口启动一个Ability时，want的caller信息不会被当前自身的应用信息覆盖，系统服务层可获取到初始caller的信息。使用callback异步回调。 847 848使用规则： 849 - 调用方应用位于后台时，使用该接口启动Ability需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限 850 - 跨应用场景下，目标Ability的exported属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限 851 - 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md) 852 853**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 854 855**系统API**: 此接口为系统接口，三方应用不支持调用。 856 857**参数：** 858 859| 参数名 | 类型 | 必填 | 说明 | 860| -------- | -------- | -------- | -------- | 861| want | [Want](js-apis-app-ability-want.md) | 是 | 启动Ability的want信息。 | 862| options | [StartOptions](js-apis-app-ability-startOptions.md) | 是 | 启动Ability所携带的参数。 | 863| callback | AsyncCallback<void> | 是 | 回调函数。当启动Ability成功，err为undefined，否则为错误对象。 | 864 865**错误码：** 866 867| 错误码ID | 错误信息 | 868| ------- | -------------------------------- | 869| 16000001 | The specified ability does not exist. | 870| 16000004 | Can not start invisible component. | 871| 16000005 | The specified process does not have the permission. | 872| 16000006 | Cross-user operations are not allowed. | 873| 16000008 | The crowdtesting application expires. | 874| 16000009 | An ability cannot be started or stopped in Wukong mode. | 875| 16000011 | The context does not exist. | 876| 16000012 | The application is controlled. | 877| 16000013 | The application is controlled by EDM. | 878| 16000050 | Internal error. | 879| 16000053 | The ability is not on the top of the UI. | 880| 16000055 | Installation-free timed out. | 881| 16200001 | The caller has been released. | 882 883错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md) 884 885**示例：** 886 887```ts 888import extension from '@ohos.app.ability.ServiceExtensionAbility'; 889import Want from '@ohos.app.ability.Want'; 890import StartOptions from '@ohos.app.ability.StartOptions'; 891 892export default class EntryAbility extends extension { 893 onCreate(want: Want) { 894 // want包含启动该应用的Caller信息 895 let localWant: Want = want; 896 localWant.bundleName = 'com.example.demo'; 897 localWant.moduleName = 'entry'; 898 localWant.abilityName = 'TestAbility'; 899 900 let option: StartOptions = { 901 displayId: 0 902 } 903 904 // 使用启动方的Caller身份信息启动新Ability 905 this.context.startAbilityAsCaller(localWant, option, (err) => { 906 if (err && err.code != 0) { 907 console.error('startAbilityAsCaller failed, err:' + JSON.stringify(err)); 908 } else { 909 console.log('startAbilityAsCaller success.'); 910 } 911 }) 912 } 913} 914 915``` 916 917## ServiceExtensionContext.startAbilityAsCaller<sup>10+<sup> 918 919startAbilityAsCaller(want: Want, options?: StartOptions): Promise\<void>; 920 921使用设置的caller信息启动一个Ability，caller信息由want携带，在系统服务层识别，Ability可以在onCreate生命周期的want参数中获取到caller信息。使用该接口启动一个Ability时，want的caller信息不会被当前自身的应用信息覆盖，系统服务层可获取到初始caller的信息。使用Promise异步回调。 922 923使用规则： 924 - 调用方应用位于后台时，使用该接口启动Ability需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限 925 - 跨应用场景下，目标Ability的exported属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限 926 - 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md) 927 928**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 929 930**系统API**: 此接口为系统接口，三方应用不支持调用。 931 932**参数：** 933 934| 参数名 | 类型 | 必填 | 说明 | 935| -------- | -------- | -------- | -------- | 936| want | [Want](js-apis-app-ability-want.md) | 是 | 启动Ability的want信息。 | 937| options | [StartOptions](js-apis-app-ability-startOptions.md) | 否 | 启动Ability所携带的参数。 | 938 939**返回值：** 940 941| 类型 | 说明 | 942| -------- | -------- | 943| Promise<void> | Promise对象。无返回结果的Promise对象。 | 944 945**错误码：** 946 947| 错误码ID | 错误信息 | 948| ------- | -------------------------------- | 949| 16000001 | The specified ability does not exist. | 950| 16000002 | Incorrect ability type. | 951| 16000004 | Can not start invisible component. | 952| 16000005 | The specified process does not have the permission. | 953| 16000006 | Cross-user operations are not allowed. | 954| 16000008 | The crowdtesting application expires. | 955| 16000009 | An ability cannot be started or stopped in Wukong mode. | 956| 16000010 | The call with the continuation flag is forbidden. | 957| 16000011 | The context does not exist. | 958| 16000012 | The application is controlled. | 959| 16000013 | The application is controlled by EDM. | 960| 16000050 | Internal error. | 961| 16000053 | The ability is not on the top of the UI. | 962| 16000055 | Installation-free timed out. | 963| 16200001 | The caller has been released. | 964 965错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md) 966 967**示例：** 968 969```ts 970import extension from '@ohos.app.ability.ServiceExtensionAbility'; 971import Want from '@ohos.app.ability.Want'; 972import StartOptions from '@ohos.app.ability.StartOptions'; 973import { BusinessError } from '@ohos.base'; 974 975export default class EntryAbility extends extension { 976 onCreate(want: Want) { 977 // want包含启动该应用的Caller信息 978 let localWant: Want = want; 979 localWant.bundleName = 'com.example.demo'; 980 localWant.moduleName = 'entry'; 981 localWant.abilityName = 'TestAbility'; 982 983 let option: StartOptions = { 984 displayId: 0 985 } 986 987 // 使用启动方的Caller身份信息启动新Ability 988 this.context.startAbilityAsCaller(localWant, option) 989 .then(() => { 990 console.log('startAbilityAsCaller success.'); 991 }) 992 .catch((err: BusinessError) => { 993 console.error('startAbilityAsCaller failed, err:' + JSON.stringify(err)); 994 }) 995 } 996} 997 998``` 999 1000## ServiceExtensionContext.stopServiceExtensionAbility 1001 1002stopServiceExtensionAbility(want: Want, callback: AsyncCallback\<void>): void; 1003 1004停止同一应用程序内的服务（callback形式）。 1005 1006**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 1007 1008**系统API**: 此接口为系统接口，三方应用不支持调用。 1009 1010**参数：** 1011 1012| 参数名 | 类型 | 必填 | 说明 | 1013| -------- | -------- | -------- | -------- | 1014| want | [Want](js-apis-app-ability-want.md) | 是 | 停止Ability的want信息。 | 1015| callback | AsyncCallback\<void\> | 是 | 停止Ability的回调函数。 | 1016 1017**错误码：** 1018 1019| 错误码ID | 错误信息 | 1020| ------- | -------------------------------- | 1021| 16000001 | The specified ability does not exist. | 1022| 16000002 | Incorrect ability type. | 1023| 16000004 | Can not start invisible component. | 1024| 16000005 | The specified process does not have the permission. | 1025| 16000006 | Cross-user operations are not allowed. | 1026| 16000011 | The context does not exist. | 1027| 16000050 | Internal error. | 1028| 16200001 | The caller has been released. | 1029 1030以上错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 1031 1032**示例：** 1033 1034 ```ts 1035 import Want from '@ohos.app.ability.Want'; 1036 import { BusinessError } from '@ohos.base'; 1037 1038 let want: Want = { 1039 deviceId: '', 1040 bundleName: 'com.example.myapplication', 1041 abilityName: 'EntryAbility' 1042 }; 1043 1044 try { 1045 this.context.stopServiceExtensionAbility(want, (error: BusinessError) => { 1046 if (error.code) { 1047 // 处理业务逻辑错误 1048 console.error('stopServiceExtensionAbility failed, error.code: ${error.code}, error.message: ${error.message}'); 1049 return; 1050 } 1051 // 执行正常业务 1052 console.log('stopServiceExtensionAbility succeed'); 1053 }); 1054 } catch (paramError) { 1055 // 处理入参错误异常 1056 console.error('error.code: ${paramError.code}, error.message: ${paramError.message}'); 1057 } 1058 ``` 1059 1060## ServiceExtensionContext.stopServiceExtensionAbility 1061 1062stopServiceExtensionAbility(want: Want): Promise\<void>; 1063 1064停止同一应用程序内的服务（Promise形式）。 1065 1066**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 1067 1068**系统API**: 此接口为系统接口，三方应用不支持调用。 1069 1070**参数：** 1071 1072| 参数名 | 类型 | 必填 | 说明 | 1073| -------- | -------- | -------- | -------- | 1074| want | [Want](js-apis-app-ability-want.md) | 是 | 停止Ability的want信息。 | 1075 1076**返回值：** 1077 1078| 类型 | 说明 | 1079| -------- | -------- | 1080| Promise<void> | 返回一个Promise，包含接口的结果。 | 1081 1082**错误码：** 1083 1084| 错误码ID | 错误信息 | 1085| ------- | -------------------------------- | 1086| 16000001 | The specified ability does not exist. | 1087| 16000002 | Incorrect ability type. | 1088| 16000004 | Can not start invisible component. | 1089| 16000005 | The specified process does not have the permission. | 1090| 16000006 | Cross-user operations are not allowed. | 1091| 16000011 | The context does not exist. | 1092| 16000050 | Internal error. | 1093| 16200001 | The caller has been released. | 1094 1095以上错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 1096 1097**示例：** 1098 1099 ```ts 1100 import Want from '@ohos.app.ability.Want'; 1101 import { BusinessError } from '@ohos.base'; 1102 1103 let want: Want = { 1104 deviceId: '', 1105 bundleName: 'com.example.myapplication', 1106 abilityName: 'EntryAbility' 1107 }; 1108 1109 try { 1110 this.context.stopServiceExtensionAbility(want) 1111 .then(() => { 1112 // 执行正常业务 1113 console.log('stopServiceExtensionAbility succeed'); 1114 }) 1115 .catch((error: BusinessError) => { 1116 // 处理业务逻辑错误 1117 console.error('stopServiceExtensionAbility failed, error.code: ${error.code}, error.message: ${error.message}'); 1118 }); 1119 } catch (paramError) { 1120 // 处理入参错误异常 1121 console.error('error.code: ${paramError.code}, error.message: ${paramError.message}'); 1122 } 1123 ``` 1124 1125## ServiceExtensionContext.stopServiceExtensionAbilityWithAccount 1126 1127stopServiceExtensionAbilityWithAccount(want: Want, accountId: number, callback: AsyncCallback\<void>): void; 1128 1129使用帐户停止同一应用程序内的服务（callback形式）。 1130 1131> **说明：** 1132> 1133> 当accountId为当前用户时，不需要校验该权限。 1134 1135**需要权限**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS 1136 1137**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 1138 1139**系统API**: 此接口为系统接口，三方应用不支持调用。 1140 1141**参数：** 1142 1143| 参数名 | 类型 | 必填 | 说明 | 1144| -------- | -------- | -------- | -------- | 1145| want | [Want](js-apis-app-ability-want.md) | 是 | 停止Ability的want信息。 | 1146| accountId | number | 是 | 需要停止的系统帐号的帐号ID，详情参考[getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess)。 | 1147| callback | AsyncCallback\<void\> | 是 | 停止Ability的回调函数。 | 1148 1149**错误码：** 1150 1151| 错误码ID | 错误信息 | 1152| ------- | -------------------------------- | 1153| 16000001 | The specified ability does not exist. | 1154| 16000002 | Incorrect ability type. | 1155| 16000004 | Can not start invisible component. | 1156| 16000005 | The specified process does not have the permission. | 1157| 16000006 | Cross-user operations are not allowed. | 1158| 16000011 | The context does not exist. | 1159| 16000050 | Internal error. | 1160| 16200001 | The caller has been released. | 1161 1162以上错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 1163 1164**示例：** 1165 1166 ```ts 1167 import Want from '@ohos.app.ability.Want'; 1168 import { BusinessError } from '@ohos.base'; 1169 1170 let want: Want = { 1171 deviceId: '', 1172 bundleName: 'com.example.myapplication', 1173 abilityName: 'EntryAbility' 1174 }; 1175 let accountId = 100; 1176 1177 try { 1178 this.context.stopServiceExtensionAbilityWithAccount(want, accountId, (error: BusinessError) => { 1179 if (error.code) { 1180 // 处理业务逻辑错误 1181 console.error('stopServiceExtensionAbilityWithAccount failed, error.code: ${error.code, error.message: ${error.message}'); 1182 return; 1183 } 1184 // 执行正常业务 1185 console.log('stopServiceExtensionAbilityWithAccount succeed'); 1186 }); 1187 } catch (paramError) { 1188 // 处理入参错误异常 1189 console.error('error.code: ${paramError.code}, error.message: ${paramError.message}'); 1190 } 1191 ``` 1192 1193## ServiceExtensionContext.stopServiceExtensionAbilityWithAccount 1194 1195stopServiceExtensionAbilityWithAccount(want: Want, accountId: number): Promise\<void>; 1196 1197使用帐户停止同一应用程序内的服务（Promise形式）。 1198 1199> **说明：** 1200> 1201> 当accountId为当前用户时，不需要校验该权限。 1202 1203**需要权限**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS 1204 1205**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 1206 1207**系统API**: 此接口为系统接口，三方应用不支持调用。 1208 1209**参数：** 1210 1211| 参数名 | 类型 | 必填 | 说明 | 1212| -------- | -------- | -------- | -------- | 1213| want | [Want](js-apis-app-ability-want.md) | 是 | 停止Ability的want信息。 | 1214| accountId | number | 是 | 需要停止的系统帐号的帐号ID，详情参考[getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess)。 | 1215 1216**返回值：** 1217 1218| 类型 | 说明 | 1219| -------- | -------- | 1220| Promise<void> | 返回一个Promise，包含接口的结果。 | 1221 1222**错误码：** 1223 1224| 错误码ID | 错误信息 | 1225| ------- | -------------------------------- | 1226| 16000001 | The specified ability does not exist. | 1227| 16000002 | Incorrect ability type. | 1228| 16000004 | Can not start invisible component. | 1229| 16000005 | The specified process does not have the permission. | 1230| 16000006 | Cross-user operations are not allowed. | 1231| 16000011 | The context does not exist. | 1232| 16000050 | Internal error. | 1233| 16200001 | The caller has been released. | 1234 1235以上错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 1236 1237**示例：** 1238 1239 ```ts 1240 import Want from '@ohos.app.ability.Want'; 1241 import { BusinessError } from '@ohos.base'; 1242 1243 let want: Want = { 1244 deviceId: '', 1245 bundleName: 'com.example.myapplication', 1246 abilityName: 'EntryAbility' 1247 }; 1248 let accountId = 100; 1249 1250 try { 1251 this.context.stopServiceExtensionAbilityWithAccount(want, accountId) 1252 .then(() => { 1253 // 执行正常业务 1254 console.log('stopServiceExtensionAbilityWithAccount succeed'); 1255 }) 1256 .catch((error: BusinessError) => { 1257 // 处理业务逻辑错误 1258 console.error('stopServiceExtensionAbilityWithAccount failed, error.code: ${error.code}, error.message: ${error.message}'); 1259 }); 1260 } catch (paramError) { 1261 // 处理入参错误异常 1262 console.error('error.code: ${paramError.code}, error.message: ${paramError.message}'); 1263 } 1264 ``` 1265 1266## ServiceExtensionContext.terminateSelf 1267 1268terminateSelf(callback: AsyncCallback<void>): void; 1269 1270停止Ability自身。 1271 1272**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 1273 1274**系统API**: 此接口为系统接口，三方应用不支持调用。 1275 1276**参数：** 1277 1278| 参数名 | 类型 | 必填 | 说明 | 1279| -------- | -------- | -------- | -------- | 1280| callback | AsyncCallback<void> | 是 | 回调函数，返回接口调用是否成功的结果。 | 1281 1282**错误码：** 1283 1284| 错误码ID | 错误信息 | 1285| ------- | -------------------------------- | 1286| 16000001 | The specified ability does not exist. | 1287| 16000004 | Can not start invisible component. | 1288| 16000005 | The specified process does not have the permission. | 1289| 16000009 | An ability cannot be started or stopped in Wukong mode. | 1290| 16000011 | The context does not exist. | 1291| 16000050 | Internal error. | 1292 1293以上错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 1294 1295**示例：** 1296 1297 ```ts 1298 import { BusinessError } from '@ohos.base'; 1299 1300 this.context.terminateSelf((error: BusinessError) => { 1301 if (error.code) { 1302 // 处理业务逻辑错误 1303 console.error('terminateSelf failed, error.code: ${error.code}, error.message: ${error.message}'); 1304 return; 1305 } 1306 // 执行正常业务 1307 console.log('terminateSelf succeed'); 1308 }); 1309 ``` 1310 1311## ServiceExtensionContext.terminateSelf 1312 1313terminateSelf(): Promise<void>; 1314 1315停止ability自身。通过Promise返回结果。 1316 1317**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 1318 1319**系统API**: 此接口为系统接口，三方应用不支持调用。 1320 1321**返回值：** 1322 1323| 类型 | 说明 | 1324| -------- | -------- | 1325| Promise<void> | 返回一个Promise，包含接口的结果。 | 1326 1327**错误码：** 1328 1329| 错误码ID | 错误信息 | 1330| ------- | -------------------------------- | 1331| 16000001 | The specified ability does not exist. | 1332| 16000004 | Can not start invisible component. | 1333| 16000005 | The specified process does not have the permission. | 1334| 16000009 | An ability cannot be started or stopped in Wukong mode. | 1335| 16000011 | The context does not exist. | 1336| 16000050 | Internal error. | 1337 1338以上错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 1339 1340**示例：** 1341 1342 ```ts 1343 import { BusinessError } from '@ohos.base'; 1344 1345 this.context.terminateSelf().then(() => { 1346 // 执行正常业务 1347 console.log('terminateSelf succeed'); 1348 }).catch((error: BusinessError) => { 1349 // 处理业务逻辑错误 1350 console.error('terminateSelf failed, error.code: ${error.code}, error.message: ${error.message}'); 1351 }); 1352 ``` 1353 1354## ServiceExtensionContext.connectServiceExtensionAbility 1355 1356connectServiceExtensionAbility(want: Want, options: ConnectOptions): number; 1357 1358将一个Ability与服务类型的Ability绑定。 1359 1360**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 1361 1362**系统API**: 此接口为系统接口，三方应用不支持调用。 1363 1364**参数：** 1365 1366| 参数名 | 类型 | 必填 | 说明 | 1367| -------- | -------- | -------- | -------- | 1368| want | [Want](js-apis-app-ability-want.md) | 是 | Want类型参数，传入需要启动的ability的信息，如Ability名称，Bundle名称等。 | 1369| options | [ConnectOptions](js-apis-inner-ability-connectOptions.md) | 是 | ConnectOptions类型的回调函数，返回服务连接成功、断开或连接失败后的信息。 | 1370 1371**返回值：** 1372 1373| 类型 | 说明 | 1374| -------- | -------- | 1375| number | 返回一个number，后续根据这个number去断开连接。 | 1376 1377**错误码：** 1378 1379| 错误码ID | 错误信息 | 1380| ------- | -------------------------------- | 1381| 16000001 | The specified ability does not exist. | 1382| 16000002 | Incorrect ability type. | 1383| 16000004 | Can not start invisible component. | 1384| 16000005 | The specified process does not have the permission. | 1385| 16000006 | Cross-user operations are not allowed. | 1386| 16000008 | The crowdtesting application expires. | 1387| 16000053 | The ability is not on the top of the UI. | 1388| 16000055 | Installation-free timed out. | 1389| 16000011 | The context does not exist. | 1390| 16000050 | Internal error. | 1391 1392以上错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 1393 1394**示例：** 1395 1396 ```ts 1397 import ServiceExtensionAbility from '@ohos.app.ability.ServiceExtensionAbility'; 1398 import common from '@ohos.app.ability.common'; 1399 import Want from '@ohos.app.ability.Want'; 1400 import { BusinessError } from '@ohos.base'; 1401 1402 let want: Want = { 1403 bundleName: 'com.example.myapp', 1404 abilityName: 'MyAbility' 1405 }; 1406 let options: common.ConnectOptions = { 1407 onConnect(elementName, remote) { 1408 commRemote = remote; 1409 console.log('----------- onConnect -----------'); 1410 }, 1411 onDisconnect(elementName) { console.log('----------- onDisconnect -----------') }, 1412 onFailed(code) { console.error('----------- onFailed -----------') } 1413 }; 1414 let connection: number; 1415 try { 1416 connection = this.context.connectServiceExtensionAbility(want, options); 1417 } catch (paramError) { 1418 // 处理入参错误异常 1419 console.error('error.code: ${paramError.code}, error.message: ${paramError.message}'); 1420 } 1421 ``` 1422 1423## ServiceExtensionContext.connectServiceExtensionAbilityWithAccount 1424 1425connectServiceExtensionAbilityWithAccount(want: Want, accountId: number, options: ConnectOptions): number; 1426 1427使用AbilityInfo.AbilityType.SERVICE模板和account将当前能力连接到一个能力。 1428 1429**需要权限**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS 1430 1431**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 1432 1433**系统API**: 此接口为系统接口，三方应用不支持调用。 1434 1435**参数：** 1436 1437| 参数名 | 类型 | 必填 | 说明 | 1438| -------- | -------- | -------- | -------- | 1439| want | [Want](js-apis-app-ability-want.md) | 是 | 启动Ability的want信息。 | 1440| accountId | number | 是 | 系统帐号的帐号ID，详情参考[getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess)。 | 1441| options | ConnectOptions | 是 | 远端对象实例。 | 1442 1443**返回值：** 1444 1445| 类型 | 说明 | 1446| -------- | -------- | 1447| number | 返回Ability连接的结果code。 | 1448 1449**错误码：** 1450 1451| 错误码ID | 错误信息 | 1452| ------- | -------------------------------- | 1453| 16000001 | The specified ability does not exist. | 1454| 16000002 | Incorrect ability type. | 1455| 16000004 | Can not start invisible component. | 1456| 16000005 | The specified process does not have the permission. | 1457| 16000006 | Cross-user operations are not allowed. | 1458| 16000008 | The crowdtesting application expires. | 1459| 16000053 | The ability is not on the top of the UI. | 1460| 16000055 | Installation-free timed out. | 1461| 16000011 | The context does not exist. | 1462| 16000050 | Internal error. | 1463 1464以上错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 1465 1466**示例：** 1467 1468 ```ts 1469 import ServiceExtensionAbility from '@ohos.app.ability.ServiceExtensionAbility'; 1470 import common from '@ohos.app.ability.common'; 1471 import Want from '@ohos.app.ability.Want'; 1472 import { BusinessError } from '@ohos.base'; 1473 1474 let want: Want = { 1475 deviceId: '', 1476 bundleName: 'com.example.myapplication', 1477 abilityName: 'EntryAbility' 1478 }; 1479 let accountId = 100; 1480 let options: common.ConnectOptions = { 1481 onConnect(elementName, remote) { 1482 commRemote = remote; 1483 console.log('----------- onConnect -----------'); 1484 }, 1485 onDisconnect(elementName) { console.log('----------- onDisconnect -----------'); }, 1486 onFailed(code) { console.log('----------- onFailed -----------'); } 1487 }; 1488 let connection: number; 1489 try { 1490 connection = this.context.connectServiceExtensionAbilityWithAccount(want, accountId, options); 1491 } catch (paramError) { 1492 // 处理入参错误异常 1493 console.error('error.code: ${paramError.code}, error.message: ${paramError.message}'); 1494 } 1495 ``` 1496 1497## ServiceExtensionContext.disconnectServiceExtensionAbility 1498 1499disconnectServiceExtensionAbility(connection: number, callback:AsyncCallback<void>): void; 1500 1501将一个Ability与绑定的服务类型的Ability解绑，断开连接之后需要将连接成功时返回的remote对象置空。 1502 1503**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 1504 1505**系统API**: 此接口为系统接口，三方应用不支持调用。 1506 1507**参数：** 1508 1509| 参数名 | 类型 | 必填 | 说明 | 1510| -------- | -------- | -------- | -------- | 1511| connection | number | 是 | 在connectServiceExtensionAbility中返回的number。 | 1512| callback | AsyncCallback<void> | 是 | 回调函数，返回接口调用是否成功的结果。 | 1513 1514**错误码：** 1515 1516| 错误码ID | 错误信息 | 1517| ------- | -------------------------------- | 1518| 16000011 | The context does not exist. | 1519| 16000050 | Internal error. | 1520 1521以上错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 1522 1523**示例：** 1524 1525 ```ts 1526 import { BusinessError } from '@ohos.base'; 1527 1528 // connection为connectServiceExtensionAbility中的返回值 1529 let connection = 1; 1530 1531 try { 1532 this.context.disconnectServiceExtensionAbility(connection, (error: BusinessError) => { 1533 commRemote = null; 1534 if (error.code) { 1535 // 处理业务逻辑错误 1536 console.error('disconnectServiceExtensionAbility failed, error.code: ${error.code}, error.message: ${error.message}'); 1537 return; 1538 } 1539 // 执行正常业务 1540 console.log('disconnectServiceExtensionAbility succeed'); 1541 }); 1542 } catch (paramError) { 1543 commRemote = null; 1544 // 处理入参错误异常 1545 console.error('error.code: ${paramError.code}, error.message: ${paramError.message}'); 1546 } 1547 ``` 1548 1549## ServiceExtensionContext.disconnectServiceExtensionAbility 1550 1551disconnectServiceExtensionAbility(connection: number): Promise<void>; 1552 1553将一个Ability与绑定的服务类型的Ability解绑，断开连接之后需要将连接成功时返回的remote对象置空(Promise形式返回结果)。 1554 1555**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 1556 1557**系统API**: 此接口为系统接口，三方应用不支持调用。 1558 1559**参数：** 1560 1561| 参数名 | 类型 | 必填 | 说明 | 1562| -------- | -------- | -------- | -------- | 1563| connection | number | 是 | 在connectServiceExtensionAbility中返回的number。 | 1564 1565**返回值：** 1566 1567| 类型 | 说明 | 1568| -------- | -------- | 1569| Promise<void> | 返回一个Promise，包含接口的结果。 | 1570 1571**错误码：** 1572 1573| 错误码ID | 错误信息 | 1574| ------- | -------------------------------- | 1575| 16000011 | The context does not exist. | 1576| 16000050 | Internal error. | 1577 1578以上错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 1579 1580**示例：** 1581 1582 ```ts 1583 import { BusinessError } from '@ohos.base'; 1584 1585 // connection为connectServiceExtensionAbility中的返回值 1586 let connection = 1; 1587 1588 try { 1589 this.context.disconnectServiceExtensionAbility(connection) 1590 .then(() => { 1591 commRemote = null; 1592 // 执行正常业务 1593 console.log('disconnectServiceExtensionAbility succeed'); 1594 }) 1595 .catch((error: BusinessError) => { 1596 commRemote = null; 1597 // 处理业务逻辑错误 1598 console.error('disconnectServiceExtensionAbility failed, error.code: ${error.code}, error.message: ${error.message}'); 1599 }); 1600 } catch (paramError) { 1601 commRemote = null; 1602 // 处理入参错误异常 1603 console.error('error.code: ${paramError.code}, error.message: ${paramError.message}'); 1604 } 1605 ``` 1606 1607## ServiceExtensionContext.startAbilityByCall 1608 1609startAbilityByCall(want: Want): Promise<Caller>; 1610 1611启动指定Ability至前台或后台，同时获取其Caller通信接口，调用方可使用Caller与被启动的Ability进行通信。 1612 1613使用规则： 1614 - 调用方应用位于后台时，使用该接口启动Ability需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限 1615 - 跨应用场景下，目标Ability的exported属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限 1616 - 同设备与跨设备场景下，该接口的使用规则存在差异，详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md) 1617 1618**需要权限**: ohos.permission.ABILITY_BACKGROUND_COMMUNICATION 1619 1620**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 1621 1622**系统API**：此接口为系统接口，三方应用不支持调用。 1623 1624**参数：** 1625 1626| 参数名 | 类型 | 必填 | 说明 | 1627| -------- | -------- | -------- | -------- | 1628| want | [Want](js-apis-app-ability-want.md) | 是 | 传入需要启动的Ability的信息，包含abilityName、moduleName、bundleName、deviceId(可选)、parameters(可选)，其中deviceId缺省或为空表示启动本地Ability，parameters缺省或为空表示后台启动Ability。 | 1629 1630**返回值：** 1631 1632| 类型 | 说明 | 1633| -------- | -------- | 1634| Promise<Caller> | 获取要通讯的caller对象。 | 1635 1636**错误码：** 1637 1638| 错误码ID | 错误信息 | 1639| ------- | -------------------------------- | 1640| 16000001 | The specified ability does not exist. | 1641| 16000002 | Incorrect ability type. | 1642| 16000004 | Can not start invisible component. | 1643| 16000005 | Static permission denied. The specified process does not have the permission. | 1644| 16000006 | Cross-user operations are not allowed. | 1645| 16000008 | The crowdtesting application expires. | 1646| 16000011 | The context does not exist. | 1647| 16000050 | Internal error. | 1648| 16200001 | The caller has been released. | 1649 1650以上错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 1651 1652**示例：** 1653 1654 后台启动： 1655 1656 ```ts 1657 import { Caller } from '@ohos.app.ability.UIAbility'; 1658 import Want from '@ohos.app.ability.Want'; 1659 import { BusinessError } from '@ohos.base'; 1660 1661 let caller: Caller; 1662 1663 // 后台启动Ability，不配置parameters 1664 let wantBackground: Want = { 1665 bundleName: 'com.example.myservice', 1666 moduleName: 'entry', 1667 abilityName: 'EntryAbility', 1668 deviceId: '' 1669 }; 1670 1671 try { 1672 this.context.startAbilityByCall(wantBackground) 1673 .then((obj: Caller) => { 1674 // 执行正常业务 1675 caller = obj; 1676 console.log('startAbilityByCall succeed'); 1677 }).catch((error: BusinessError) => { 1678 // 处理业务逻辑错误 1679 console.error('startAbilityByCall failed, error.code: ${error.code}, error.message: ${error.message}'); 1680 }); 1681 } catch (paramError) { 1682 // 处理入参错误异常 1683 console.error('error.code: ${paramError.code}, error.message: ${paramError.message}'); 1684 } 1685 ``` 1686 1687 前台启动： 1688 1689 ```ts 1690 import { Caller } from '@ohos.app.ability.UIAbility'; 1691 import Want from '@ohos.app.ability.Want'; 1692 import { BusinessError } from '@ohos.base'; 1693 1694 let caller: Caller; 1695 1696 // 前台启动Ability，将parameters中的'ohos.aafwk.param.callAbilityToForeground'配置为true 1697 let wantForeground: Want = { 1698 bundleName: 'com.example.myservice', 1699 moduleName: 'entry', 1700 abilityName: 'EntryAbility', 1701 deviceId: '', 1702 parameters: { 1703 'ohos.aafwk.param.callAbilityToForeground': true 1704 } 1705 }; 1706 1707 try { 1708 this.context.startAbilityByCall(wantForeground) 1709 .then((obj: Caller) => { 1710 // 执行正常业务 1711 caller = obj; 1712 console.log('startAbilityByCall succeed'); 1713 }).catch((error: BusinessError) => { 1714 // 处理业务逻辑错误 1715 console.error('startAbilityByCall failed, error.code: ${error.code}, error.message: ${error.message}'); 1716 }); 1717 } catch (paramError) { 1718 // 处理入参错误异常 1719 console.error('error.code: ${paramError.code}, error.message: ${paramError.message}'); 1720 } 1721 ``` 1722## ServiceExtensionContext.startRecentAbility 1723 1724startRecentAbility(want: Want, callback: AsyncCallback\<void>): void; 1725 1726启动一个指定的Ability，如果这个Ability有多个实例，将拉起最近启动的那个实例。启动结果以callback的形式返回开发者。 1727 1728使用规则： 1729 - 调用方应用位于后台时，使用该接口启动Ability需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限 1730 - 跨应用场景下，目标Ability的exported属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限 1731 - 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md) 1732 1733**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 1734 1735**系统API**: 此接口为系统接口，三方应用不支持调用。 1736 1737**参数：** 1738 1739| 参数名 | 类型 | 必填 | 说明 | 1740| -------- | -------- | -------- | -------- | 1741| want | [Want](js-apis-app-ability-want.md) | 是 | 需要启动Ability的want信息。 | 1742| callback | AsyncCallback\<void> | 是 | 指定的回调函数的结果。 | 1743 1744**错误码：** 1745 1746以下错误码的详细介绍请参见[errcode-ability](../errorcodes/errorcode-ability.md)。 1747 1748| 错误码ID | 错误信息 | 1749| ------- | -------------------------------- | 1750| 16000001 | The specified ability does not exist. | 1751| 16000002 | Incorrect ability type. | 1752| 16000004 | Can not start invisible component. | 1753| 16000005 | The specified process does not have the permission. | 1754| 16000006 | Cross-user operations are not allowed. | 1755| 16000008 | The crowdtesting application expires. | 1756| 16000009 | An ability cannot be started or stopped in Wukong mode. | 1757| 16000010 | The call with the continuation flag is forbidden. | 1758| 16000011 | The context does not exist. | 1759| 16000050 | Internal error. | 1760| 16000053 | The ability is not on the top of the UI. | 1761| 16000055 | Installation-free timed out. | 1762| 16200001 | The caller has been released. | 1763 1764**示例：** 1765 1766 ```ts 1767import Want from '@ohos.app.ability.Want'; 1768import { BusinessError } from '@ohos.base'; 1769 1770let want: Want = { 1771 bundleName: 'com.example.myapplication', 1772 abilityName: 'EntryAbility' 1773}; 1774 1775try { 1776 this.context.startRecentAbility(want, (err: BusinessError) => { 1777 if (err.code) { 1778 // 处理业务逻辑错误 1779 console.error(`startRecentAbility failed, code is ${err.code}, message is ${err.message}`); 1780 return; 1781 } 1782 // 执行正常业务 1783 console.info('startRecentAbility succeed'); 1784 }); 1785} catch (err) { 1786 // 处理入参错误异常 1787 let code = (err as BusinessError).code; 1788 let message = (err as BusinessError).message; 1789 console.error(`startRecentAbility failed, code is ${code}, message is ${message}`); 1790} 1791 ``` 1792## ServiceExtensionContext.startRecentAbility 1793 1794startRecentAbility(want: Want, options: StartOptions, callback: AsyncCallback\<void>): void; 1795 1796启动一个指定的Ability，如果这个Ability有多个实例，将拉起最近启动的那个实例。启动结果以callback的形式返回开发者。 1797当开发者需要携带启动参数时可以选择此API。 1798 1799使用规则： 1800 - 调用方应用位于后台时，使用该接口启动Ability需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限 1801 - 跨应用场景下，目标Ability的exported属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限 1802 - 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md) 1803 1804**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 1805 1806**系统API**: 此接口为系统接口，三方应用不支持调用。 1807 1808**参数：** 1809 1810| 参数名 | 类型 | 必填 | 说明 | 1811| -------- | -------- | -------- | -------- | 1812| want | [Want](js-apis-app-ability-want.md) | 是 | 需要启动Ability的want信息。 | 1813| options | [StartOptions](js-apis-app-ability-startOptions.md) | 是 | 启动Ability所携带的参数。 | 1814| callback | AsyncCallback\<void> | 是 | 指定的回调函数的结果。 | 1815 1816**错误码：** 1817 1818以下错误码的详细介绍请参见[errcode-ability](../errorcodes/errorcode-ability.md)。 1819 1820| 错误码ID | 错误信息 | 1821| ------- | -------------------------------- | 1822| 16000001 | The specified ability does not exist. | 1823| 16000002 | Incorrect ability type. | 1824| 16000004 | Can not start invisible component. | 1825| 16000005 | The specified process does not have the permission. | 1826| 16000006 | Cross-user operations are not allowed. | 1827| 16000008 | The crowdtesting application expires. | 1828| 16000009 | An ability cannot be started or stopped in Wukong mode. | 1829| 16000010 | The call with the continuation flag is forbidden. | 1830| 16000011 | The context does not exist. | 1831| 16000050 | Internal error. | 1832| 16000053 | The ability is not on the top of the UI. | 1833| 16000055 | Installation-free timed out. | 1834| 16200001 | The caller has been released. | 1835 1836**示例：** 1837 1838 ```ts 1839import Want from '@ohos.app.ability.Want'; 1840import StartOptions from '@ohos.app.ability.StartOptions'; 1841import { BusinessError } from '@ohos.base'; 1842 1843let want: Want = { 1844 deviceId: '', 1845 bundleName: 'com.example.myapplication', 1846 abilityName: 'EntryAbility' 1847}; 1848let options: StartOptions = { 1849 windowMode: 0 1850}; 1851 1852try { 1853 this.context.startRecentAbility(want, options, (err: BusinessError) => { 1854 if (err.code) { 1855 // 处理业务逻辑错误 1856 console.error(`startRecentAbility failed, code is ${err.code}, message is ${err.message}`); 1857 return; 1858 } 1859 // 执行正常业务 1860 console.info('startRecentAbility succeed'); 1861 }); 1862} catch (err) { 1863 // 处理入参错误异常 1864 let code = (err as BusinessError).code; 1865 let message = (err as BusinessError).message; 1866 console.error(`startRecentAbility failed, code is ${code}, message is ${message}`); 1867} 1868 ``` 1869## ServiceExtensionContext.startRecentAbility 1870 1871startRecentAbility(want: Want, options?: StartOptions): Promise\<void>; 1872 1873启动一个指定的Ability，如果这个Ability有多个实例，将拉起最近启动的那个实例。 1874当开发者期望启动结果以Promise形式返回时可以选择此API。 1875 1876使用规则： 1877 - 调用方应用位于后台时，使用该接口启动Ability需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限 1878 - 跨应用场景下，目标Ability的exported属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限 1879 - 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md) 1880 1881**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 1882 1883**系统API**: 此接口为系统接口，三方应用不支持调用。 1884 1885**参数：** 1886 1887| 参数名 | 类型 | 必填 | 说明 | 1888| -------- | -------- | -------- | -------- | 1889| want | [Want](js-apis-app-ability-want.md) | 是 | 需要启动Ability的want信息。 | 1890| options | [StartOptions](js-apis-app-ability-startOptions.md) | 否 | 启动Ability所携带的参数。 | 1891 1892**错误码：** 1893 1894以下错误码的详细介绍请参见[errcode-ability](../errorcodes/errorcode-ability.md)。 1895 1896| 错误码ID | 错误信息 | 1897| ------- | -------------------------------- | 1898| 16000001 | The specified ability does not exist. | 1899| 16000002 | Incorrect ability type. | 1900| 16000004 | Can not start invisible component. | 1901| 16000005 | The specified process does not have the permission. | 1902| 16000006 | Cross-user operations are not allowed. | 1903| 16000008 | The crowdtesting application expires. | 1904| 16000009 | An ability cannot be started or stopped in Wukong mode. | 1905| 16000010 | The call with the continuation flag is forbidden. | 1906| 16000011 | The context does not exist. | 1907| 16000050 | Internal error. | 1908| 16000053 | The ability is not on the top of the UI. | 1909| 16000055 | Installation-free timed out. | 1910| 16200001 | The caller has been released. | 1911 1912**示例：** 1913 1914 ```ts 1915import Want from '@ohos.app.ability.Want'; 1916import StartOptions from '@ohos.app.ability.StartOptions'; 1917import { BusinessError } from '@ohos.base'; 1918 1919let want: Want = { 1920 bundleName: 'com.example.myapplication', 1921 abilityName: 'EntryAbility' 1922}; 1923let options: StartOptions = { 1924 windowMode: 0, 1925}; 1926 1927try { 1928 this.context.startRecentAbility(want, options) 1929 .then(() => { 1930 // 执行正常业务 1931 console.info('startRecentAbility succeed'); 1932 }) 1933 .catch((err: BusinessError) => { 1934 // 处理业务逻辑错误 1935 console.error(`startRecentAbility failed, code is ${err.code}, message is ${err.message}`); 1936 }); 1937} catch (err) { 1938 // 处理入参错误异常 1939 let code = (err as BusinessError).code; 1940 let message = (err as BusinessError).message; 1941 console.error(`startRecentAbility failed, code is ${code}, message is ${message}`); 1942} 1943 ``` 1944 1945## ServiceExtensionContext.startAbilityByCallWithAccount<sup>10+</sup> 1946 1947startAbilityByCallWithAccount(want: Want, accountId: number): Promise<Caller>; 1948 1949根据accountId对指定的Ability进行call调用，并且可以使用返回的Caller通信接口与被调用方进行通信。 1950 1951使用规则： 1952 - 跨用户场景下，Call调用目标Ability时，调用方应用需同时申请`ohos.permission.ABILITY_BACKGROUND_COMMUNICATION`与`ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS`权限 1953 - 调用方应用位于后台时，使用该接口启动Ability需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限 1954 - 跨应用场景下，目标Ability的exported属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限 1955 - 同设备与跨设备场景下，该接口的使用规则存在差异，详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md) 1956 1957**需要权限**: ohos.permission.ABILITY_BACKGROUND_COMMUNICATION, ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS 1958 1959**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 1960 1961**系统API**：此接口为系统接口，三方应用不支持调用。 1962 1963**参数：** 1964 1965| 参数名 | 类型 | 必填 | 说明 | 1966| -------- | -------- | -------- | -------- | 1967| want | [Want](js-apis-app-ability-want.md) | 是 | 传入需要启动的Ability的信息，包含abilityName、moduleName、bundleName、deviceId(可选)、parameters(可选)，其中deviceId缺省或为空表示启动本地Ability，parameters缺省或为空表示后台启动Ability。 | 1968| accountId | number | 是 | 系统帐号的帐号ID，-1表示当前活动用户，详情参考[getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess)。 | 1969 1970**返回值：** 1971 1972| 类型 | 说明 | 1973| -------- | -------- | 1974| Promise<Caller> | 获取要通讯的caller对象。 | 1975 1976**错误码：** 1977 1978以下错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 1979 1980| 错误码ID | 错误信息 | 1981| ------- | -------------------------------- | 1982| 16000001 | The specified ability does not exist. | 1983| 16000002 | Incorrect ability type. | 1984| 16000004 | Can not start invisible component. | 1985| 16000005 | Static permission denied. The specified process does not have the permission. | 1986| 16000006 | Cross-user operations are not allowed. | 1987| 16000008 | The crowdtesting application expires. | 1988| 16000011 | The context does not exist. | 1989| 16000012 | The application is controlled. | 1990| 16000013 | The application is controlled by EDM. | 1991| 16000050 | Internal error. | 1992| 16200001 | The caller has been released. | 1993 1994**示例：** 1995 1996 ```ts 1997 import { Caller } from '@ohos.app.ability.UIAbility'; 1998 import Want from '@ohos.app.ability.Want'; 1999 import StartOptions from '@ohos.app.ability.StartOptions'; 2000 import { BusinessError } from '@ohos.base'; 2001 2002 let caller: Caller; 2003 // 系统账号的账号ID, -1表示当前激活用户 2004 let accountId = -1; 2005 // 指定启动的Ability 2006 let want: Want = { 2007 bundleName: 'com.acts.actscalleeabilityrely', 2008 moduleName: 'entry', 2009 abilityName: 'EntryAbility', 2010 deviceId: '', 2011 parameters: { 2012 // 'ohos.aafwk.param.callAbilityToForeground' 值设置为true时为前台启动, 设置false或不设置为后台启动 2013 'ohos.aafwk.param.callAbilityToForeground': true 2014 } 2015 }; 2016 2017 try { 2018 this.context.startAbilityByCallWithAccount(want, accountId) 2019 .then((obj: Caller) => { 2020 // 执行正常业务 2021 caller = obj; 2022 console.log('startAbilityByCallWithAccount succeed'); 2023 }).catch((error: BusinessError) => { 2024 // 处理业务逻辑错误 2025 console.error('startAbilityByCallWithAccount failed, error.code: ${error.code}, error.message: ${error.message}'); 2026 }); 2027 } catch (paramError) { 2028 // 处理入参错误异常 2029 console.error('error.code: ${paramError.code}, error.message: ${paramError.message}'); 2030 } 2031 ```