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