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