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