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> 本模块接口仅可在Stage模型下使用。 9 10## 导入模块 11 12```ts 13import UIExtensionContentSession from '@ohos.app.ability.UIExtensionContentSession'; 14``` 15 16## UIExtensionContentSession.sendData 17 18sendData(data: { [key: string]: Object }): void 19 20发送数据给UIExtensionComponent控件。 21 22**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 23 24**系统API**：此接口为系统接口，三方应用不支持调用。 25 26**参数：** 27 28| 参数名 | 类型 | 必填 | 说明 | 29| -------- | -------- | -------- | -------- | 30| data | {[key: string]: Object} | 是 | 发送给UIExtensionComponent控件的数据参数。 | 31 32**错误码：** 33 34| 错误码ID | 错误信息 | 35| ------- | -------------------------------- | 36| 16000050 | Internal error. | 37 38错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 39 40## UIExtensionContentSession.setReceiveDataCallback 41 42setReceiveDataCallback(callback: (data: { [key: string]: Object }) => void): void 43 44设置从UIExtensionComponent控件接收数据的回调方法。 45 46**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 47 48**系统API**：此接口为系统接口，三方应用不支持调用。 49 50**参数：** 51 52| 参数名 | 类型 | 必填 | 说明 | 53| -------- | -------- | -------- | -------- | 54| callback | (data: { [key: string]: Object }) => void | 是 | 接收数据的回调方法。 | 55 56**错误码：** 57 58| 错误码ID | 错误信息 | 59| ------- | -------------------------------- | 60| 16000050 | Internal error. | 61 62错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 63 64## UIExtensionContentSession.loadContent 65 66loadContent(path: string, storage?: LocalStorage): void; 67 68为当前UIExtensionComponent控件对应的窗口加载与LocalStorage相关联的具体页面内容。 69 70**系统能力：** SystemCapability.Ability.AbilityRuntime.Core 71 72**参数：** 73 74| 参数名 | 类型 | 必填 | 说明 | 75| ------- | ----------------------------------------------- | ---- | ------------------------------------------------------------ | 76| path | string | 是 | 设置加载页面的路径。 | 77| storage | [LocalStorage](../../quick-start/arkts-localstorage.md) | 否 | 存储单元，为应用程序范围内的可变状态属性和非可变状态属性提供存储。默认为空。 | 78 79**错误码：** 80 81| 错误码ID | 错误信息 | 82| ------- | -------------------------------- | 83| 16000050 | Internal error. | 84 85错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 86 87## UIExtensionContentSession.startAbility 88 89startAbility(want: Want, callback: AsyncCallback<void>): void; 90 91启动Ability（callback形式）。 92 93使用规则： 94 - 对应UIExtensionComponent控件所在的应用需要处于前台获焦状态。 95 - 调用方应用位于后台时，使用该接口启动Ability需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限。 96 - 跨应用场景下，目标Ability的exported属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限。 97 - 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md)。 98 99**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 100 101**系统API**：此接口为系统接口，三方应用不支持调用。 102 103**参数：** 104 105| 参数名 | 类型 | 必填 | 说明 | 106| -------- | -------- | -------- | -------- | 107| want | [Want](js-apis-app-ability-want.md) | 是 | 启动Ability的want信息。 | 108| callback | AsyncCallback<void> | 是 | callback形式返回启动结果。 | 109 110**错误码：** 111 112| 错误码ID | 错误信息 | 113| ------- | -------------------------------- | 114| 16000001 | The specified ability does not exist. | 115| 16000002 | Incorrect ability type. | 116| 16000004 | Can not start invisible component. | 117| 16000005 | The specified process does not have the permission. | 118| 16000006 | Cross-user operations are not allowed. | 119| 16000008 | The crowdtesting application expires. | 120| 16000009 | An ability cannot be started or stopped in Wukong mode. | 121| 16000010 | The call with the continuation flag is forbidden. | 122| 16000011 | The context does not exist. | 123| 16000012 | The application is controlled. | 124| 16000013 | The application is controlled by EDM. | 125| 16000050 | Internal error. | 126| 16000053 | The ability is not on the top of the UI. | 127| 16000055 | Installation-free timed out. | 128| 16200001 | The caller has been released. | 129 130错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 131 132## UIExtensionContentSession.startAbility 133 134startAbility(want: Want, options: StartOptions, callback: AsyncCallback<void>): void; 135 136启动Ability（callback形式）。 137 138使用规则： 139 - 对应UIExtensionComponent控件所在的应用需要处于前台获焦状态。 140 - 调用方应用位于后台时，使用该接口启动Ability需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限。 141 - 跨应用场景下，目标Ability的exported属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限。 142 - 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md)。 143 144**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 145 146**系统API**：此接口为系统接口，三方应用不支持调用。 147 148**参数：** 149 150| 参数名 | 类型 | 必填 | 说明 | 151| -------- | -------- | -------- | -------- | 152| want | [Want](js-apis-app-ability-want.md) | 是 | 启动Ability的want信息。 | 153| options | [StartOptions](js-apis-app-ability-startOptions.md) | 是 | 启动Ability所携带的参数。 | 154| callback | AsyncCallback<void> | 是 | callback形式返回启动结果。 | 155 156**错误码：** 157 158| 错误码ID | 错误信息 | 159| ------- | -------------------------------- | 160| 16000001 | The specified ability does not exist. | 161| 16000004 | Can not start invisible component. | 162| 16000005 | The specified process does not have the permission. | 163| 16000006 | Cross-user operations are not allowed. | 164| 16000008 | The crowdtesting application expires. | 165| 16000009 | An ability cannot be started or stopped in Wukong mode. | 166| 16000011 | The context does not exist. | 167| 16000012 | The application is controlled. | 168| 16000013 | The application is controlled by EDM. | 169| 16000050 | Internal error. | 170| 16000053 | The ability is not on the top of the UI. | 171| 16000055 | Installation-free timed out. | 172| 16200001 | The caller has been released. | 173 174错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 175 176## UIExtensionContentSession.startAbility 177 178startAbility(want: Want, options?: StartOptions): Promise<void>; 179 180启动Ability（promise形式）。 181 182使用规则： 183 - 对应UIExtensionComponent控件所在的应用需要处于前台获焦状态。 184 - 调用方应用位于后台时，使用该接口启动Ability需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限。 185 - 跨应用场景下，目标Ability的exported属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限。 186 - 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md)。 187 188**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 189 190**系统API**：此接口为系统接口，三方应用不支持调用。 191 192**参数：** 193 194| 参数名 | 类型 | 必填 | 说明 | 195| -------- | -------- | -------- | -------- | 196| want | [Want](js-apis-app-ability-want.md) | 是 | 启动Ability的want信息。 | 197| options | [StartOptions](js-apis-app-ability-startOptions.md) | 否 | 启动Ability所携带的参数。 | 198 199**返回值：** 200 201| 类型 | 说明 | 202| -------- | -------- | 203| Promise<void> | Promise形式返回启动结果。 | 204 205**错误码：** 206 207| 错误码ID | 错误信息 | 208| ------- | -------------------------------- | 209| 16000001 | The specified ability does not exist. | 210| 16000002 | Incorrect ability type. | 211| 16000004 | Can not start invisible component. | 212| 16000005 | The specified process does not have the permission. | 213| 16000006 | Cross-user operations are not allowed. | 214| 16000008 | The crowdtesting application expires. | 215| 16000009 | An ability cannot be started or stopped in Wukong mode. | 216| 16000010 | The call with the continuation flag is forbidden. | 217| 16000011 | The context does not exist. | 218| 16000012 | The application is controlled. | 219| 16000013 | The application is controlled by EDM. | 220| 16000050 | Internal error. | 221| 16000053 | The ability is not on the top of the UI. | 222| 16000055 | Installation-free timed out. | 223| 16200001 | The caller has been released. | 224 225错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 226 227## UIExtensionContentSession.startAbilityForResult 228 229startAbilityForResult(want: Want, callback: AsyncCallback<AbilityResult>): void; 230 231启动一个Ability，在Ability终止后返回结果给调用方(callback形式)。Ability的终止方式包括以下几种情况: 232 - 正常情况下可通过调用[terminateSelfWithResult](js-apis-inner-application-uiAbilityContext.md#uiabilitycontextterminateselfwithresult)接口使之终止并且返回结果给调用方。 233 - 异常情况下比如杀死Ability会返回异常信息给调用方, 异常信息中resultCode为-1。 234 - 如果被启动的Ability模式是单实例模式, 不同应用多次调用该接口启动这个Ability，当这个Ability调用[terminateSelfWithResult](js-apis-inner-application-uiAbilityContext.md#uiabilitycontextterminateselfwithresult)接口使之终止时，只将正常结果返回给最后一个调用方, 其它调用方返回异常信息, 异常信息中resultCode为-1。 235 236使用规则： 237 - 对应UIExtensionComponent控件所在的应用需要处于前台获焦状态。 238 - 调用方应用位于后台时，使用该接口启动Ability需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限。 239 - 跨应用场景下，目标Ability的exported属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限。 240 - 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md)。 241 242**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 243 244**系统API**：此接口为系统接口，三方应用不支持调用。 245 246**参数：** 247 248| 参数名 | 类型 | 必填 | 说明 | 249| -------- | -------- | -------- | -------- | 250| want |[Want](js-apis-app-ability-want.md) | 是 | 启动Ability的want信息。 | 251| callback | AsyncCallback<[AbilityResult](js-apis-inner-ability-abilityResult.md)> | 是 | 执行结果回调函数。 | 252 253**错误码：** 254 255| 错误码ID | 错误信息 | 256| ------- | -------------------------------- | 257| 16000001 | The specified ability does not exist. | 258| 16000002 | Incorrect ability type. | 259| 16000004 | Can not start invisible component. | 260| 16000005 | The specified process does not have the permission. | 261| 16000006 | Cross-user operations are not allowed. | 262| 16000008 | The crowdtesting application expires. | 263| 16000009 | An ability cannot be started or stopped in Wukong mode. | 264| 16000010 | The call with the continuation flag is forbidden. | 265| 16000011 | The context does not exist. | 266| 16000012 | The application is controlled. | 267| 16000013 | The application is controlled by EDM. | 268| 16000050 | Internal error. | 269| 16000053 | The ability is not on the top of the UI. | 270| 16000055 | Installation-free timed out. | 271| 16200001 | The caller has been released. | 272 273错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 274 275## UIExtensionContentSession.startAbilityForResult 276 277startAbilityForResult(want: Want, options: StartOptions, callback: AsyncCallback<AbilityResult>): void; 278 279启动一个Ability，在Ability终止后返回结果给调用方(callback形式)。Ability的终止方式包括以下几种情况: 280 - 正常情况下可通过调用[terminateSelfWithResult](js-apis-inner-application-uiAbilityContext.md#uiabilitycontextterminateselfwithresult)接口使之终止并且返回结果给调用方。 281 - 异常情况下比如杀死Ability会返回异常信息给调用方，异常信息中resultCode为-1。 282 - 如果被启动的Ability模式是单实例模式, 不同应用多次调用该接口启动这个Ability，当这个Ability调用[terminateSelfWithResult](js-apis-inner-application-uiAbilityContext.md#uiabilitycontextterminateselfwithresult)接口使之终止时，只将正常结果返回给最后一个调用方，其它调用方返回异常信息, 异常信息中resultCode为-1。 283 284使用规则： 285 - 对应UIExtensionComponent控件所在的应用需要处于前台获焦状态。 286 - 调用方应用位于后台时，使用该接口启动Ability需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限。 287 - 跨应用场景下，目标Ability的exported属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限。 288 - 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md)。 289 290**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 291 292**系统API**：此接口为系统接口，三方应用不支持调用。 293 294**参数：** 295 296| 参数名 | 类型 | 必填 | 说明 | 297| -------- | -------- | -------- | -------- | 298| want |[Want](js-apis-app-ability-want.md) | 是 | 启动Ability的want信息。 | 299| options | [StartOptions](js-apis-app-ability-startOptions.md) | 是 | 启动Ability所携带的参数。 | 300| callback | AsyncCallback<[AbilityResult](js-apis-inner-ability-abilityResult.md)> | 是 | 执行结果回调函数。 | 301 302**错误码：** 303 304| 错误码ID | 错误信息 | 305| ------- | -------------------------------- | 306| 16000001 | The specified ability does not exist. | 307| 16000004 | Can not start invisible component. | 308| 16000005 | The specified process does not have the permission. | 309| 16000006 | Cross-user operations are not allowed. | 310| 16000008 | The crowdtesting application expires. | 311| 16000009 | An ability cannot be started or stopped in Wukong mode. | 312| 16000011 | The context does not exist. | 313| 16000012 | The application is controlled. | 314| 16000013 | The application is controlled by EDM. | 315| 16000050 | Internal error. | 316| 16000053 | The ability is not on the top of the UI. | 317| 16000055 | Installation-free timed out. | 318| 16200001 | The caller has been released. | 319 320错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 321 322## UIExtensionContentSession.startAbilityForResult 323 324startAbilityForResult(want: Want, options?: StartOptions): Promise<AbilityResult>; 325 326启动一个Ability，在Ability终止后返回结果给调用方(promise形式)。Ability的终止方式包括以下几种情况: 327 - 正常情况下可通过调用[terminateSelfWithResult](js-apis-inner-application-uiAbilityContext.md#uiabilitycontextterminateselfwithresult)接口使之终止并且返回结果给调用方。 328 - 异常情况下比如杀死Ability会返回异常信息给调用方, 异常信息中resultCode为-1。 329 - 如果被启动的Ability模式是单实例模式, 不同应用多次调用该接口启动这个Ability，当这个Ability调用[terminateSelfWithResult](js-apis-inner-application-uiAbilityContext.md#uiabilitycontextterminateselfwithresult)接口使之终止时，只将正常结果返回给最后一个调用方, 其它调用方返回异常信息, 异常信息中resultCode为-1。 330 331使用规则： 332 - 对应UIExtensionComponent控件所在的应用需要处于前台获焦状态。 333 - 调用方应用位于后台时，使用该接口启动Ability需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限。 334 - 跨应用场景下，目标Ability的exported属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限。 335 - 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md)。 336 337**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 338 339**系统API**：此接口为系统接口，三方应用不支持调用。 340 341**参数：** 342 343| 参数名 | 类型 | 必填 | 说明 | 344| -------- | -------- | -------- | -------- | 345| want | [Want](js-apis-app-ability-want.md) | 是 | 启动Ability的want信息。 | 346| options | [StartOptions](js-apis-app-ability-startOptions.md) | 否 | 启动Ability所携带的参数。 | 347 348 349**返回值：** 350 351| 类型 | 说明 | 352| -------- | -------- | 353| Promise<[AbilityResult](js-apis-inner-ability-abilityResult.md)> | Promise形式返回执行结果。 | 354 355**错误码：** 356 357| 错误码ID | 错误信息 | 358| ------- | -------------------------------- | 359| 16000001 | The specified ability does not exist. | 360| 16000002 | Incorrect ability type. | 361| 16000004 | Can not start invisible component. | 362| 16000005 | The specified process does not have the permission. | 363| 16000006 | Cross-user operations are not allowed. | 364| 16000008 | The crowdtesting application expires. | 365| 16000009 | An ability cannot be started or stopped in Wukong mode. | 366| 16000010 | The call with the continuation flag is forbidden. | 367| 16000011 | The context does not exist. | 368| 16000012 | The application is controlled. | 369| 16000013 | The application is controlled by EDM. | 370| 16000050 | Internal error. | 371| 16000053 | The ability is not on the top of the UI. | 372| 16000055 | Installation-free timed out. | 373| 16200001 | The caller has been released. | 374 375错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 376 377## UIExtensionContentSession.terminateSelf 378 379terminateSelf(callback: AsyncCallback<void>): void; 380 381停止UIExtensionContentSession对应的窗口界面对象（callback形式）。 382 383**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 384 385**参数：** 386 387| 参数名 | 类型 | 必填 | 说明 | 388| -------- | -------- | -------- | -------- | 389| callback | AsyncCallback<void> | 是 | 停止UIExtensionContentSession对应的窗口界面对象的回调函数。 | 390 391## UIExtensionContentSession.terminateSelf 392 393terminateSelf(): Promise<void>; 394 395停止UIExtensionContentSession对应的窗口界面对象（promise形式）。 396 397**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 398 399**返回值：** 400 401| 类型 | 说明 | 402| -------- | -------- | 403| Promise<void> | 停止UIExtensionContentSession对应的窗口界面对象的回调函数。 | 404 405## UIExtensionContentSession.terminateSelfWithResult 406 407terminateSelfWithResult(parameter: AbilityResult, callback: AsyncCallback<void>): void; 408 409停止UIExtensionContentSession对应的窗口界面对象，并将结果返回给UIExtensionComponent控件（callback形式）。 410 411**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 412 413**参数：** 414 415| 参数名 | 类型 | 必填 | 说明 | 416| -------- | -------- | -------- | -------- | 417| parameter | [AbilityResult](js-apis-inner-ability-abilityResult.md) | 是 | 返回给UIExtensionComponent控件的信息。 | 418| callback | AsyncCallback<void> | 是 | callback形式返回停止结果。 | 419 420## UIExtensionContentSession.terminateSelfWithResult 421 422terminateSelfWithResult(parameter: AbilityResult): Promise<void>; 423 424停止UIExtensionContentSession对应的窗口界面对象，并将结果返回给UIExtensionComponent控件（promise形式）。 425 426**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 427 428**参数：** 429 430| 参数名 | 类型 | 必填 | 说明 | 431| -------- | -------- | -------- | -------- | 432| parameter | [AbilityResult](js-apis-inner-ability-abilityResult.md) | 是 | 返回给UIExtensionComponent控件的信息。 | 433 434**返回值：** 435 436| 类型 | 说明 | 437| -------- | -------- | 438| Promise<void> | promise形式返回停止结果。 | 439 440## UIExtensionContentSession.setWindowBackgroundColor 441 442setWindowBackgroundColor(color: string): void 443 444设置UIExtensionAbility加载界面的背景色。该接口需要在[loadContent()](#uiextensioncontentsessionloadcontent)调用生效后使用。 445 446**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 447 448**系统API**：此接口为系统接口，三方应用不支持调用。 449 450**参数：** 451 452| 参数名 | 类型 | 必填 | 说明 | 453| -------- | -------- | -------- | -------- | 454| color | string | 是 | 需要设置的背景色，为十六进制RGB或ARGB颜色，不区分大小写，例如`#00FF00`或`#FF00FF00`。 | 455 456**错误码：** 457 458| 错误码ID | 错误信息 | 459| ------- | -------------------------------- | 460| 16000050 | Internal error. | 461 462错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 463 464## UIExtensionContentSession.setWindowPrivacyMode 465 466setWindowPrivacyMode(isPrivacyMode: boolean): Promise<void> 467 468设置窗口是否为隐私模式，使用Promise异步回调。设置为隐私模式的窗口，窗口内容将无法被截屏或录屏。 469 470**系统能力：** SystemCapability.Ability.AbilityRuntime.Core 471 472**需要权限：** ohos.permission.PRIVACY_WINDOW 473 474**参数：** 475 476| 参数名 | 类型 | 必填 | 说明 | 477| ------------- | ------- | -- | ----------------------------------------------------- | 478| isPrivacyMode | boolean | 是 | 窗口是否为隐私模式。true表示模式开启；false表示模式关闭。 | 479 480**返回值：** 481 482| 类型 | 说明 | 483| ------------------- | ------------------------ | 484| Promise<void> | 无返回结果的Promise对象。 | 485 486## UIExtensionContentSession.setWindowPrivacyMode 487 488setWindowPrivacyMode(isPrivacyMode: boolean, callback: AsyncCallback<void>): void 489 490设置窗口是否为隐私模式，使用callback异步回调。设置为隐私模式的窗口，窗口内容将无法被截屏或录屏。 491 492**系统能力：** SystemCapability.Ability.AbilityRuntime.Core 493 494**需要权限：** ohos.permission.PRIVACY_WINDOW 495 496**参数：** 497 498| 参数名 | 类型 | 必填 | 说明 | 499| ------------- | ------------------------- | -- | ------------------------------------------------------ | 500| isPrivacyMode | boolean | 是 | 窗口是否为隐私模式。true表示模式开启；false表示模式关闭。 | 501| callback | AsyncCallback<void> | 是 | 回调函数。 | 502