1# @ohos.app.ability.UIExtensionContentSession (带界面扩展能力界面操作类)(系统接口) 2 3UIExtensionContentSession是[UIExtensionAbility](js-apis-app-ability-uiExtensionAbility.md)加载界面内容时创建的实例对象，当UIExtensionComponent控件拉起指定的UIExtensionAbility时，UIExtensionAbility会创建UIExtensionContentSession对象，并通过[onSessionCreate](js-apis-app-ability-uiExtensionAbility.md#onsessioncreate)回调传递给开发者。一个UIExtensionComponent控件对应一个UIExtensionContentSession对象，提供界面加载，结果通知等方法。每个UIExtensionAbility的UIExtensionContentSession之间互不影响，可以各自进行操作。 4 5> **说明：** 6> 7> 本模块首批接口从API version 10 开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8> 9> 本模块接口仅可在Stage模型下使用。 10> 11> 当前页面仅包含本模块的系统接口，其他公开接口参见[@ohos.app.ability.UIExtensionContentSession (带界面扩展能力界面操作类)](js-apis-app-ability-uiExtensionContentSession.md)。 12 13## 导入模块 14 15```ts 16import { UIExtensionContentSession } from '@kit.AbilityKit'; 17``` 18 19## UIExtensionContentSession 20 21### sendData 22 23sendData(data: Record\<string, Object>): void 24 25发送数据给UIExtensionComponent控件。 26 27**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 28 29**系统接口**：此接口为系统接口。 30 31**参数：** 32 33| 参数名 | 类型 | 必填 | 说明 | 34| -------- | -------- | -------- | -------- | 35| data | Record\<string, Object> | 是 | 发送给UIExtensionComponent控件的数据参数。 | 36 37**错误码：** 38 39以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 40 41| 错误码ID | 错误信息 | 42| ------- | -------------------------------- | 43| 202 | Not System App. Interface caller is not a system app. | 44| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 45| 16000050 | Internal error. | 46 47**示例：** 48 49```ts 50import { UIExtensionContentSession } from '@kit.AbilityKit'; 51 52@Entry() 53@Component 54struct Index { 55 private storage: LocalStorage | undefined = this.getUIContext().getSharedLocalStorage(); 56 private session: UIExtensionContentSession | undefined = 57 this.storage?.get<UIExtensionContentSession>('session'); 58 59 build() { 60 RelativeContainer() { 61 Button('SendData') 62 .onClick(() => { 63 let data: Record<string, Object> = { 64 'number': 123456, 65 'message': 'test' 66 }; 67 68 try { 69 this.session?.sendData(data); 70 } catch (err) { 71 console.error('sendData err:' + JSON.stringify(err)); 72 } 73 }) 74 } 75 .height('100%') 76 .width('100%') 77 } 78} 79``` 80 81### setReceiveDataCallback 82 83setReceiveDataCallback(callback: (data: Record\<string, Object>) => void): void 84 85设置从UIExtensionComponent控件接收数据的回调方法。使用callback异步回调。 86 87**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 88 89**系统接口**：此接口为系统接口。 90 91**参数：** 92 93| 参数名 | 类型 | 必填 | 说明 | 94| -------- | -------- | -------- | -------- | 95| callback | (data: Record\<string, Object>) => void | 是 | 回调函数，返回接收的数据。 | 96 97**错误码：** 98 99以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 100 101| 错误码ID | 错误信息 | 102| ------- | -------------------------------- | 103| 202 | Not System App. Interface caller is not a system app. | 104| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 105| 16000050 | Internal error. | 106 107**示例：** 108 109```ts 110import { UIExtensionContentSession } from '@kit.AbilityKit'; 111 112@Entry() 113@Component 114struct Index { 115 storage: LocalStorage | undefined = this.getUIContext().getSharedLocalStorage(); 116 private session: UIExtensionContentSession | undefined = 117 this.storage?.get<UIExtensionContentSession>('session'); 118 119 build() { 120 RelativeContainer() { 121 Button('SendData') 122 .onClick(() => { 123 this.session?.setReceiveDataCallback((data: Record<string, Object>) => { 124 console.info(`Succeeded in setReceiveDataCallback, data: ${JSON.stringify(data)}`); 125 }); 126 }) 127 } 128 .height('100%') 129 .width('100%') 130 } 131} 132``` 133 134### setReceiveDataForResultCallback<sup>11+</sup> 135 136setReceiveDataForResultCallback(callback: (data: Record<string, Object>) => Record<string, Object>): void 137 138设置从UIExtensionComponent控件接收数据带返回值的回调方法。使用callback异步回调。 139 140**系统接口**：此接口为系统接口。 141 142**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 143 144 145**参数：** 146 147| 参数名 | 类型 | 必填 | 说明 | 148| -------- | -------- | -------- |----------------| 149| callback | (data: Record\<string, Object>) => Record\<string, Object> | 是 | 回调函数，返回带返回值的接收的数据。 | 150 151**错误码：** 152 153以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 154 155| 错误码ID | 错误信息 | 156| ------- | -------------------------------- | 157| 202 | Not System App. Interface caller is not a system app. | 158| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 159| 16000050 | Internal error. | 160 161**示例：** 162 163```ts 164import { UIExtensionContentSession } from '@kit.AbilityKit'; 165 166@Entry() 167@Component 168struct Index { 169 storage: LocalStorage | undefined = this.getUIContext().getSharedLocalStorage(); 170 private session: UIExtensionContentSession | undefined = 171 this.storage?.get<UIExtensionContentSession>('session'); 172 173 build() { 174 RelativeContainer() { 175 Button('SetReceiveDataForResultCallback') 176 .onClick(() => { 177 this.session?.setReceiveDataForResultCallback((data: Record<string, Object>) => { 178 console.info(`Succeeded in setReceiveDataCallback, data: ${JSON.stringify(data)}`); 179 return data; 180 }); 181 }) 182 } 183 .height('100%') 184 .width('100%') 185 } 186} 187``` 188 189### startAbility 190 191startAbility(want: Want, callback: AsyncCallback<void>): void 192 193启动Ability。使用callback异步回调。 194 195> **说明：** 196> 197> 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md)。 198> 对应UIExtensionComponent控件所在的应用需要处于前台获焦状态。 199 200**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 201 202**系统接口**：此接口为系统接口。 203 204**参数：** 205 206| 参数名 | 类型 | 必填 | 说明 | 207| -------- | -------- | -------- | -------- | 208| want | [Want](js-apis-app-ability-want.md) | 是 | 启动Ability的want信息。 | 209| callback | AsyncCallback<void> | 是 | 回调函数。当启动成功，err为undefined，否则为错误对象。 | 210 211**错误码：** 212 213以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 214 215| 错误码ID | 错误信息 | 216| ------- | -------------------------------- | 217| 201 | The application does not have permission to call the interface. | 218| 202 | Not System App. Interface caller is not a system app. | 219| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 220| 16000001 | The specified ability does not exist. | 221| 16000002 | Incorrect ability type. | 222| 16000004 | Cannot start an invisible component. | 223| 16000005 | The specified process does not have the permission. | 224| 16000006 | Cross-user operations are not allowed. | 225| 16000008 | The crowdtesting application expires. | 226| 16000009 | An ability cannot be started or stopped in Wukong mode. | 227| 16000010 | The call with the continuation and prepare continuation flag is forbidden. | 228| 16000011 | The context does not exist. | 229| 16000012 | The application is controlled. | 230| 16000013 | The application is controlled by EDM. | 231| 16000050 | Internal error. | 232| 16000053 | The ability is not on the top of the UI. | 233| 16000055 | Installation-free timed out. | 234| 16200001 | The caller has been released. | 235 236**示例：** 237 238```ts 239import { UIExtensionContentSession, UIExtensionAbility, Want } from '@kit.AbilityKit'; 240import { BusinessError } from '@kit.BasicServicesKit'; 241 242export default class UIExtAbility extends UIExtensionAbility { 243 // ... 244 245 onSessionCreate(want: Want, session: UIExtensionContentSession): void { 246 session.startAbility(want, (err: BusinessError) => { 247 if (err) { 248 console.error(`Failed to startAbility, code: ${err.code}, msg: ${err.message}`); 249 return; 250 } 251 console.info(`Succeeded in startAbility`); 252 }) 253 } 254 255 // ... 256} 257``` 258 259### startAbility 260 261startAbility(want: Want, options: StartOptions, callback: AsyncCallback<void>): void 262 263启动Ability。使用callback异步回调。 264 265> **说明：** 266> 267> 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md)。 268> 对应UIExtensionComponent控件所在的应用需要处于前台获焦状态。 269 270**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 271 272**系统接口**：此接口为系统接口。 273 274**参数：** 275 276| 参数名 | 类型 | 必填 | 说明 | 277| -------- | -------- | -------- | -------- | 278| want | [Want](js-apis-app-ability-want.md) | 是 | 启动Ability的want信息。 | 279| options | [StartOptions](js-apis-app-ability-startOptions.md) | 是 | 启动Ability所携带的参数。 | 280| callback | AsyncCallback<void> | 是 | 回调函数。当启动成功，err为undefined，否则为错误对象。 | 281 282**错误码：** 283 284以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 285 286| 错误码ID | 错误信息 | 287| ------- | -------------------------------- | 288| 201 | The application does not have permission to call the interface. | 289| 202 | Not System App. Interface caller is not a system app. | 290| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 291| 16000001 | The specified ability does not exist. | 292| 16000004 | Cannot start an invisible component. | 293| 16000005 | The specified process does not have the permission. | 294| 16000006 | Cross-user operations are not allowed. | 295| 16000008 | The crowdtesting application expires. | 296| 16000009 | An ability cannot be started or stopped in Wukong mode. | 297| 16000011 | The context does not exist. | 298| 16000012 | The application is controlled. | 299| 16000013 | The application is controlled by EDM. | 300| 16000050 | Internal error. | 301| 16000053 | The ability is not on the top of the UI. | 302| 16000055 | Installation-free timed out. | 303| 16200001 | The caller has been released. | 304 305**示例：** 306 307```ts 308import { UIExtensionContentSession, UIExtensionAbility, Want, StartOptions } from '@kit.AbilityKit'; 309import { BusinessError } from '@kit.BasicServicesKit'; 310 311export default class UIExtAbility extends UIExtensionAbility { 312 // ... 313 314 onSessionCreate(want: Want, session: UIExtensionContentSession): void { 315 let startOptions: StartOptions = { 316 displayId: 0 317 }; 318 319 session.startAbility(want, startOptions, (err: BusinessError) => { 320 if (err) { 321 console.error(`Failed to startAbility, code: ${err.code}, msg: ${err.message}`); 322 return; 323 } 324 console.info(`Succeeded in startAbility`); 325 }) 326 } 327 328 // ... 329} 330``` 331 332### startAbility 333 334startAbility(want: Want, options?: StartOptions): Promise<void> 335 336启动Ability。使用Promise异步回调。 337 338> **说明：** 339> 340> 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md)。 341> 对应UIExtensionComponent控件所在的应用需要处于前台获焦状态。 342 343**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 344 345**系统接口**：此接口为系统接口。 346 347**参数：** 348 349| 参数名 | 类型 | 必填 | 说明 | 350| -------- | -------- | -------- | -------- | 351| want | [Want](js-apis-app-ability-want.md) | 是 | 启动Ability的want信息。 | 352| options | [StartOptions](js-apis-app-ability-startOptions.md) | 否 | 启动Ability所携带的参数。 | 353 354**返回值：** 355 356| 类型 | 说明 | 357| -------- | -------- | 358| Promise<void> | Promise对象。无返回结果的Promise对象。 | 359 360**错误码：** 361 362以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 363 364| 错误码ID | 错误信息 | 365| ------- | -------------------------------- | 366| 201 | The application does not have permission to call the interface. | 367| 202 | Not System App. Interface caller is not a system app. | 368| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 369| 16000001 | The specified ability does not exist. | 370| 16000002 | Incorrect ability type. | 371| 16000004 | Cannot start an invisible component. | 372| 16000005 | The specified process does not have the permission. | 373| 16000006 | Cross-user operations are not allowed. | 374| 16000008 | The crowdtesting application expires. | 375| 16000009 | An ability cannot be started or stopped in Wukong mode. | 376| 16000010 | The call with the continuation and prepare continuation flag is forbidden. | 377| 16000011 | The context does not exist. | 378| 16000012 | The application is controlled. | 379| 16000013 | The application is controlled by EDM. | 380| 16000050 | Internal error. | 381| 16000053 | The ability is not on the top of the UI. | 382| 16000055 | Installation-free timed out. | 383| 16200001 | The caller has been released. | 384 385**示例：** 386 387```ts 388import { UIExtensionContentSession, UIExtensionAbility, Want, StartOptions } from '@kit.AbilityKit'; 389import { BusinessError } from '@kit.BasicServicesKit'; 390 391export default class UIExtAbility extends UIExtensionAbility { 392 // ... 393 394 onSessionCreate(want: Want, session: UIExtensionContentSession): void { 395 let startOptions: StartOptions = { 396 displayId: 0 397 }; 398 399 session.startAbility(want, startOptions) 400 .then(() => { 401 console.info(`Succeeded in startAbility`); 402 }) 403 .catch((err: BusinessError) => { 404 console.error(`Failed to startAbility, code: ${err.code}, msg: ${err.message}`); 405 }); 406 } 407 408 // ... 409} 410``` 411 412### startAbilityForResult 413 414startAbilityForResult(want: Want, callback: AsyncCallback<AbilityResult>): void 415 416启动一个Ability，在Ability终止后返回结果给调用方。使用callback异步回调。 417 418Ability的终止方式包括以下几种情况： 419 - 正常情况下可通过调用[terminateSelfWithResult](js-apis-inner-application-uiAbilityContext.md#terminateselfwithresult)接口使之终止并且返回结果给调用方。 420 - 异常情况下比如杀死Ability会返回异常信息给调用方，异常信息中resultCode为-1。 421 - 如果被启动的Ability模式是单实例模式，不同应用多次调用该接口启动这个Ability，当这个Ability调用[terminateSelfWithResult](js-apis-inner-application-uiAbilityContext.md#terminateselfwithresult)接口使之终止时，只将正常结果返回给最后一个调用方，其他调用方返回异常信息，异常信息中resultCode为-1。 422 423> **说明：** 424> 425> 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md)。 426> 对应UIExtensionComponent控件所在的应用需要处于前台获焦状态。 427 428**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 429 430**系统接口**：此接口为系统接口。 431 432**参数：** 433 434| 参数名 | 类型 | 必填 | 说明 | 435| -------- | -------- | -------- | -------- | 436| want |[Want](js-apis-app-ability-want.md) | 是 | 启动Ability的want信息。 | 437| callback | AsyncCallback<[AbilityResult](js-apis-inner-ability-abilityResult.md)> | 是 | 回调函数。当Ability启动并终止成功，err为undefined，data为获取到的结果码和数据；否则为错误对象。 | 438 439**错误码：** 440 441以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 442 443| 错误码ID | 错误信息 | 444| ------- | -------------------------------- | 445| 201 | The application does not have permission to call the interface. | 446| 202 | Not System App. Interface caller is not a system app. | 447| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 448| 16000001 | The specified ability does not exist. | 449| 16000002 | Incorrect ability type. | 450| 16000004 | Cannot start an invisible component. | 451| 16000005 | The specified process does not have the permission. | 452| 16000006 | Cross-user operations are not allowed. | 453| 16000008 | The crowdtesting application expires. | 454| 16000009 | An ability cannot be started or stopped in Wukong mode. | 455| 16000010 | The call with the continuation and prepare continuation flag is forbidden. | 456| 16000011 | The context does not exist. | 457| 16000012 | The application is controlled. | 458| 16000013 | The application is controlled by EDM. | 459| 16000050 | Internal error. | 460| 16000053 | The ability is not on the top of the UI. | 461| 16000055 | Installation-free timed out. | 462| 16200001 | The caller has been released. | 463 464**示例：** 465 466```ts 467import { UIExtensionContentSession, UIExtensionAbility, Want, common } from '@kit.AbilityKit'; 468import { BusinessError } from '@kit.BasicServicesKit'; 469 470export default class UIExtAbility extends UIExtensionAbility { 471 // ... 472 473 onSessionCreate(want: Want, session: UIExtensionContentSession): void { 474 session.startAbilityForResult(want, (err: BusinessError, data: common.AbilityResult) => { 475 if (err) { 476 console.error(`Failed to startAbilityForResult, code: ${err.code}, msg: ${err.message}`); 477 return; 478 } 479 console.info(`Succeeded in startAbilityForResult, data: ${JSON.stringify(data)}`); 480 }) 481 } 482 483 // ... 484} 485``` 486 487### startAbilityForResult 488 489startAbilityForResult(want: Want, options: StartOptions, callback: AsyncCallback<AbilityResult>): void 490 491启动一个Ability，在Ability终止后返回结果给调用方。使用callback异步回调。 492 493Ability的终止方式包括以下几种情况： 494 - 正常情况下可通过调用[terminateSelfWithResult](js-apis-inner-application-uiAbilityContext.md#terminateselfwithresult)接口使之终止并且返回结果给调用方。 495 - 异常情况下比如杀死Ability会返回异常信息给调用方，异常信息中resultCode为-1。 496 - 如果被启动的Ability模式是单实例模式，不同应用多次调用该接口启动这个Ability，当这个Ability调用[terminateSelfWithResult](js-apis-inner-application-uiAbilityContext.md#terminateselfwithresult)接口使之终止时，只将正常结果返回给最后一个调用方，其他调用方返回异常信息，异常信息中resultCode为-1。 497 498> **说明：** 499> 500> 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md)。 501> 对应UIExtensionComponent控件所在的应用需要处于前台获焦状态。 502 503**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 504 505**系统接口**：此接口为系统接口。 506 507**参数：** 508 509| 参数名 | 类型 | 必填 | 说明 | 510| -------- | -------- | -------- | -------- | 511| want |[Want](js-apis-app-ability-want.md) | 是 | 启动Ability的want信息。 | 512| options | [StartOptions](js-apis-app-ability-startOptions.md) | 是 | 启动Ability所携带的参数。 | 513| callback | AsyncCallback<[AbilityResult](js-apis-inner-ability-abilityResult.md)> | 是 | 回调函数。当Ability启动并终止成功，err为undefined，data为获取到的结果码和数据；否则为错误对象。 | 514 515**错误码：** 516 517以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 518 519| 错误码ID | 错误信息 | 520| ------- | -------------------------------- | 521| 201 | The application does not have permission to call the interface. | 522| 202 | Not System App. Interface caller is not a system app. | 523| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 524| 16000001 | The specified ability does not exist. | 525| 16000004 | Cannot start an invisible component. | 526| 16000005 | The specified process does not have the permission. | 527| 16000006 | Cross-user operations are not allowed. | 528| 16000008 | The crowdtesting application expires. | 529| 16000009 | An ability cannot be started or stopped in Wukong mode. | 530| 16000011 | The context does not exist. | 531| 16000012 | The application is controlled. | 532| 16000013 | The application is controlled by EDM. | 533| 16000050 | Internal error. | 534| 16000053 | The ability is not on the top of the UI. | 535| 16000055 | Installation-free timed out. | 536| 16200001 | The caller has been released. | 537 538**示例：** 539 540```ts 541import { UIExtensionContentSession, UIExtensionAbility, Want, StartOptions, common } from '@kit.AbilityKit'; 542import { BusinessError } from '@kit.BasicServicesKit'; 543 544export default class UIExtAbility extends UIExtensionAbility { 545 // ... 546 547 onSessionCreate(want: Want, session: UIExtensionContentSession): void { 548 let startOptions: StartOptions = { 549 displayId: 0 550 }; 551 552 session.startAbilityForResult(want, startOptions, (err: BusinessError, data: common.AbilityResult) => { 553 if (err) { 554 console.error(`Failed to startAbilityForResult, code: ${err.code}, msg: ${err.message}`); 555 return; 556 } 557 console.info(`Succeeded in startAbilityForResult, data: ${JSON.stringify(data)}`); 558 }) 559 } 560 561 // ... 562} 563``` 564 565### startAbilityForResult 566 567startAbilityForResult(want: Want, options?: StartOptions): Promise<AbilityResult> 568 569启动一个Ability，在Ability终止后返回结果给调用方。使用Promise异步回调。 570 571Ability的终止方式包括以下几种情况： 572 - 正常情况下可通过调用[terminateSelfWithResult](js-apis-inner-application-uiAbilityContext.md#terminateselfwithresult)接口使之终止并且返回结果给调用方。 573 - 异常情况下比如杀死Ability会返回异常信息给调用方，异常信息中resultCode为-1。 574 - 如果被启动的Ability模式是单实例模式，不同应用多次调用该接口启动这个Ability，当这个Ability调用[terminateSelfWithResult](js-apis-inner-application-uiAbilityContext.md#terminateselfwithresult)接口使之终止时，只将正常结果返回给最后一个调用方，其他调用方返回异常信息，异常信息中resultCode为-1。 575 576> **说明：** 577> 578> 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md)。 579> 对应UIExtensionComponent控件所在的应用需要处于前台获焦状态。 580 581**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 582 583**系统接口**：此接口为系统接口。 584 585**参数：** 586 587| 参数名 | 类型 | 必填 | 说明 | 588| -------- | -------- | -------- | -------- | 589| want | [Want](js-apis-app-ability-want.md) | 是 | 启动Ability的want信息。 | 590| options | [StartOptions](js-apis-app-ability-startOptions.md) | 否 | 启动Ability所携带的参数。 | 591 592 593**返回值：** 594 595| 类型 | 说明 | 596| -------- | -------- | 597| Promise<[AbilityResult](js-apis-inner-ability-abilityResult.md)> | Promise对象，返回结果码和数据。 | 598 599**错误码：** 600 601以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 602 603| 错误码ID | 错误信息 | 604| ------- | -------------------------------- | 605| 201 | The application does not have permission to call the interface. | 606| 202 | Not System App. Interface caller is not a system app. | 607| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 608| 16000001 | The specified ability does not exist. | 609| 16000002 | Incorrect ability type. | 610| 16000004 | Cannot start an invisible component. | 611| 16000005 | The specified process does not have the permission. | 612| 16000006 | Cross-user operations are not allowed. | 613| 16000008 | The crowdtesting application expires. | 614| 16000009 | An ability cannot be started or stopped in Wukong mode. | 615| 16000010 | The call with the continuation and prepare continuation flag is forbidden. | 616| 16000011 | The context does not exist. | 617| 16000012 | The application is controlled. | 618| 16000013 | The application is controlled by EDM. | 619| 16000050 | Internal error. | 620| 16000053 | The ability is not on the top of the UI. | 621| 16000055 | Installation-free timed out. | 622| 16200001 | The caller has been released. | 623 624**示例：** 625 626```ts 627import { UIExtensionContentSession, UIExtensionAbility, Want, StartOptions, common } from '@kit.AbilityKit'; 628import { BusinessError } from '@kit.BasicServicesKit'; 629 630export default class UIExtAbility extends UIExtensionAbility { 631 // ... 632 633 onSessionCreate(want: Want, session: UIExtensionContentSession): void { 634 let startOptions: StartOptions = { 635 displayId: 0 636 }; 637 638 session.startAbilityForResult(want, startOptions) 639 .then((data: common.AbilityResult) => { 640 console.info(`Succeeded in startAbilityForResult, data: ${JSON.stringify(data)}`); 641 }) 642 .catch((err: BusinessError) => { 643 console.error(`Failed to startAbilityForResult, code: ${err.code}, msg: ${err.message}`); 644 }); 645 } 646 647 // ... 648} 649``` 650 651### setWindowBackgroundColor 652 653setWindowBackgroundColor(color: string): void 654 655设置UIExtensionAbility加载界面的背景色。该接口需要在[loadContent()](js-apis-app-ability-uiExtensionContentSession.md#loadcontent)调用生效后使用。 656 657**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 658 659**系统接口**：此接口为系统接口。 660 661**参数：** 662 663| 参数名 | 类型 | 必填 | 说明 | 664| -------- | -------- | -------- | -------- | 665| color | string | 是 | 需要设置的背景色，为十六进制RGB或ARGB颜色，不区分大小写，例如`#00FF00`或`#FF00FF00`。 | 666 667**错误码：** 668 669以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 670 671| 错误码ID | 错误信息 | 672| ------- | -------------------------------- | 673| 202 | Not System App. Interface caller is not a system app. | 674| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 675| 16000050 | Internal error. | 676 677**示例：** 678 679```ts 680import { UIExtensionContentSession, UIExtensionAbility, Want } from '@kit.AbilityKit'; 681 682export default class UIExtAbility extends UIExtensionAbility { 683 // ... 684 685 onSessionCreate(want: Want, session: UIExtensionContentSession): void { 686 let storage: LocalStorage = new LocalStorage(); 687 storage.setOrCreate('session', session); 688 689 try { 690 session.loadContent('pages/Extension', storage); 691 } catch (err) { 692 console.error('loadContent err:' + JSON.stringify(err)); 693 } 694 695 try { 696 session.setWindowBackgroundColor('#00FF00'); 697 } catch (err) { 698 console.error('setWindowBackgroundColor err:' + JSON.stringify(err)); 699 } 700 } 701 702 // ... 703} 704``` 705 706### startAbilityAsCaller<sup>11+</sup> 707 708startAbilityAsCaller(want: Want, callback: AsyncCallback\<void>): void 709 710初始Ability将自己的caller信息（如BundleName、AbilityName等）置于want参数中，传递给中间层的ExtensionAbility。当ExtensionAbility通过该接口拉起另外一个Ability，被拉起的Ability可以从onCreate生命周期获取到初始Ability的caller信息。使用callback异步回调。 711 712**系统接口**：此接口为系统接口。 713 714**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 715 716**参数：** 717 718| 参数名 | 类型 | 必填 | 说明 | 719| -------- | -------- | -------- | -------- | 720| want | [Want](js-apis-app-ability-want.md) | 是 | 启动Ability的want信息。 | 721| callback | AsyncCallback\<void> | 是 | 回调函数。当启动Ability成功，err为undefined，否则为错误对象。 | 722 723**错误码：** 724 725以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 726 727| 错误码ID | 错误信息 | 728| ------- | -------------------------------- | 729| 201 | The application does not have permission to call the interface. | 730| 202 | Not System App. Interface caller is not a system app. | 731| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 732| 16000001 | The specified ability does not exist. | 733| 16000002 | Incorrect ability type. | 734| 16000004 | Cannot start an invisible component. | 735| 16000005 | The specified process does not have the permission. | 736| 16000006 | Cross-user operations are not allowed. | 737| 16000008 | The crowdtesting application expires. | 738| 16000009 | An ability cannot be started or stopped in Wukong mode. | 739| 16000010 | The call with the continuation and prepare continuation flag is forbidden. | 740| 16000011 | The context does not exist. | 741| 16000012 | The application is controlled. | 742| 16000013 | The application is controlled by EDM. | 743| 16000050 | Internal error. | 744| 16000053 | The ability is not on the top of the UI. | 745| 16000055 | Installation-free timed out. | 746| 16200001 | The caller has been released. | 747 748**示例：** 749 750```ts 751import { UIExtensionContentSession, UIExtensionAbility, Want } from '@kit.AbilityKit'; 752import { BusinessError } from '@kit.BasicServicesKit'; 753 754export default class UIExtAbility extends UIExtensionAbility { 755 // ... 756 757 onSessionCreate(want: Want, session: UIExtensionContentSession): void { 758 let localWant: Want = want; 759 localWant.bundleName = 'com.example.demo'; 760 localWant.moduleName = 'entry'; 761 localWant.abilityName = 'TestAbility'; 762 763 session.startAbilityAsCaller(localWant, (err: BusinessError) => { 764 if (err) { 765 console.error(`Failed to startAbilityAsCaller, code: ${err.code}, msg: ${err.message}`); 766 return; 767 } 768 console.info(`Succeeded in startAbilityAsCaller`); 769 }) 770 } 771 772 // ... 773} 774``` 775 776### startAbilityAsCaller<sup>11+</sup> 777 778startAbilityAsCaller(want: Want, options: StartOptions, callback: AsyncCallback\<void>): void 779 780初始Ability将自己的caller信息（如BundleName、AbilityName等）置于want参数中，传递给中间层的ExtensionAbility。当ExtensionAbility通过该接口拉起另外一个Ability，被拉起的Ability可以从onCreate生命周期获取到初始Ability的caller信息。使用callback异步回调。 781 782**系统接口**：此接口为系统接口。 783 784**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 785 786**参数：** 787 788| 参数名 | 类型 | 必填 | 说明 | 789| -------- | -------- | -------- | -------- | 790| want | [Want](js-apis-app-ability-want.md) | 是 | 启动Ability的want信息。 | 791| options | [StartOptions](js-apis-app-ability-startOptions.md) | 是 | 启动Ability所携带的参数。 | 792| callback | AsyncCallback\<void> | 是 | 回调函数。当启动Ability成功，err为undefined，否则为错误对象。 | 793 794**错误码：** 795 796以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 797 798| 错误码ID | 错误信息 | 799| ------- | -------------------------------- | 800| 201 | The application does not have permission to call the interface. | 801| 202 | Not System App. Interface caller is not a system app. | 802| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 803| 16000001 | The specified ability does not exist. | 804| 16000004 | Cannot start an invisible component. | 805| 16000005 | The specified process does not have the permission. | 806| 16000006 | Cross-user operations are not allowed. | 807| 16000008 | The crowdtesting application expires. | 808| 16000009 | An ability cannot be started or stopped in Wukong mode. | 809| 16000011 | The context does not exist. | 810| 16000012 | The application is controlled. | 811| 16000013 | The application is controlled by EDM. | 812| 16000050 | Internal error. | 813| 16000053 | The ability is not on the top of the UI. | 814| 16000055 | Installation-free timed out. | 815| 16200001 | The caller has been released. | 816 817**示例：** 818 819```ts 820import { UIExtensionContentSession, UIExtensionAbility, Want, StartOptions } from '@kit.AbilityKit'; 821import { BusinessError } from '@kit.BasicServicesKit'; 822 823export default class UIExtAbility extends UIExtensionAbility { 824 // ... 825 826 onSessionCreate(want: Want, session: UIExtensionContentSession): void { 827 let localWant: Want = want; 828 localWant.bundleName = 'com.example.demo'; 829 localWant.moduleName = 'entry'; 830 localWant.abilityName = 'TestAbility'; 831 832 let startOptions: StartOptions = { 833 displayId: 0 834 }; 835 836 session.startAbilityAsCaller(localWant, startOptions, (err: BusinessError) => { 837 if (err) { 838 console.error(`Failed to startAbilityAsCaller, code: ${err.code}, msg: ${err.message}`); 839 return; 840 } 841 console.info(`Succeeded in startAbilityAsCaller`); 842 }) 843 } 844 845 // ... 846} 847``` 848 849### startAbilityAsCaller<sup>11+</sup> 850 851startAbilityAsCaller(want: Want, options?: StartOptions): Promise\<void> 852 853初始Ability将自己的caller信息（如BundleName、AbilityName等）置于want参数中，传递给中间层的ExtensionAbility。当ExtensionAbility通过该接口拉起另外一个Ability，被拉起的Ability可以从onCreate生命周期获取到初始Ability的caller信息。使用Promise异步回调。 854 855**系统接口**：此接口为系统接口。 856 857**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 858 859**参数：** 860 861| 参数名 | 类型 | 必填 | 说明 | 862| -------- | -------- | -------- | -------- | 863| want | [Want](js-apis-app-ability-want.md) | 是 | 启动Ability的want信息。 | 864| options | [StartOptions](js-apis-app-ability-startOptions.md) | 否 | 启动Ability所携带的参数。 | 865 866**返回值：** 867 868| 类型 | 说明 | 869| -------- | -------- | 870| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 871 872**错误码：** 873 874以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 875 876| 错误码ID | 错误信息 | 877| ------- | -------------------------------- | 878| 201 | The application does not have permission to call the interface. | 879| 202 | Not System App. Interface caller is not a system app. | 880| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 881| 16000001 | The specified ability does not exist. | 882| 16000002 | Incorrect ability type. | 883| 16000004 | Cannot start an invisible component. | 884| 16000005 | The specified process does not have the permission. | 885| 16000006 | Cross-user operations are not allowed. | 886| 16000008 | The crowdtesting application expires. | 887| 16000009 | An ability cannot be started or stopped in Wukong mode. | 888| 16000010 | The call with the continuation and prepare continuation flag is forbidden. | 889| 16000011 | The context does not exist. | 890| 16000012 | The application is controlled. | 891| 16000013 | The application is controlled by EDM. | 892| 16000050 | Internal error. | 893| 16000053 | The ability is not on the top of the UI. | 894| 16000055 | Installation-free timed out. | 895| 16200001 | The caller has been released. | 896 897**示例：** 898 899```ts 900import { UIExtensionContentSession, UIExtensionAbility, Want, StartOptions } from '@kit.AbilityKit'; 901import { BusinessError } from '@kit.BasicServicesKit'; 902 903export default class UIExtAbility extends UIExtensionAbility { 904 // ... 905 906 onSessionCreate(want: Want, session: UIExtensionContentSession): void { 907 let localWant: Want = want; 908 localWant.bundleName = 'com.example.demo'; 909 localWant.moduleName = 'entry'; 910 localWant.abilityName = 'TestAbility'; 911 912 let startOptions: StartOptions = { 913 displayId: 0 914 }; 915 916 session.startAbilityAsCaller(localWant, startOptions) 917 .then(() => { 918 console.info(`Succeeded in startAbilityAsCaller`); 919 }) 920 .catch((err: BusinessError) => { 921 console.error(`Failed to startAbilityAsCaller, code: ${err.code}, msg: ${err.message}`); 922 }); 923 } 924 925 // ... 926} 927``` 928 929### getUIExtensionHostWindowProxy<sup>11+</sup> 930 931getUIExtensionHostWindowProxy(): uiExtensionHost.UIExtensionHostWindowProxy 932 933获取当前UIExtension对应的窗口对象，用于通知宽高、位置、避让信息等。 934 935**系统接口**：此接口为系统接口。 936 937**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 938 939**返回值：** 940 941| 类型 | 说明 | 942| -------- | -------- | 943| [uiExtensionHost.UIExtensionHostWindowProxy](../apis-arkui/js-apis-uiExtensionHost-sys.md) | 宿主应用窗口信息。 | 944 945**错误码：** 946 947以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 948 949| 错误码ID | 错误信息 | 950| ------- | -------------------------------- | 951| 202 | Not System App. Interface caller is not a system app. | 952| 16000050 | Internal error. | 953 954**示例：** 955 956```ts 957import { UIExtensionAbility, UIExtensionContentSession, Want } from '@kit.AbilityKit'; 958import { uiExtensionHost } from '@kit.ArkUI'; 959 960const TAG: string = '[UIExtAbility]'; 961 962export default class UIExtAbility extends UIExtensionAbility { 963 onCreate() { 964 console.log(TAG, `UIExtAbility onCreate`); 965 } 966 967 onForeground() { 968 console.log(TAG, `UIExtAbility onForeground`); 969 } 970 971 onBackground() { 972 console.log(TAG, `UIExtAbility onBackground`); 973 } 974 975 onDestroy() { 976 console.log(TAG, `UIExtAbility onDestroy`); 977 } 978 979 onSessionCreate(want: Want, session: UIExtensionContentSession) { 980 let extensionHostWindow = session.getUIExtensionHostWindowProxy(); 981 let data: Record<string, UIExtensionContentSession | uiExtensionHost.UIExtensionHostWindowProxy> = { 982 'session': session, 983 'extensionHostWindow': extensionHostWindow 984 }; 985 let storage: LocalStorage = new LocalStorage(data); 986 987 try { 988 session.loadContent('pages/Extension', storage); 989 } catch (err) { 990 console.error('loadContent err:' + JSON.stringify(err)); 991 } 992 } 993 994 onSessionDestroy(session: UIExtensionContentSession) { 995 console.log(TAG, `UIExtAbility onSessionDestroy`); 996 } 997} 998``` 999