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