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## 导入模块 12 13```ts 14import { UIExtensionContentSession } from '@kit.AbilityKit'; 15``` 16 17## UIExtensionContentSession.loadContent 18 19loadContent(path: string, storage?: LocalStorage): void 20 21为当前UIExtensionComponent控件对应的窗口加载与LocalStorage相关联的具体页面内容。 22 23**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 24 25**参数：** 26 27| 参数名 | 类型 | 必填 | 说明 | 28| ------- | ----------------------------------------------- | ---- | ------------------------------------------------------------ | 29| path | string | 是 | 设置加载页面的路径。 | 30| storage | [LocalStorage](../../quick-start/arkts-localstorage.md) | 否 | 存储单元，为应用程序范围内的可变状态属性和非可变状态属性提供存储。默认为空。 | 31 32**错误码：** 33 34以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 35 36| 错误码ID | 错误信息 | 37| ------- | -------------------------------- | 38| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 39| 16000050 | Internal error. | 40 41**示例：** 42 43```ts 44import { UIExtensionContentSession, UIExtensionAbility, Want } from '@kit.AbilityKit'; 45 46export default class UIExtAbility extends UIExtensionAbility { 47 // ... 48 49 onSessionCreate(want: Want, session: UIExtensionContentSession): void { 50 let storage: LocalStorage = new LocalStorage(); 51 storage.setOrCreate('session', session); 52 session.loadContent('pages/Extension', storage); 53 } 54 55 // ... 56} 57``` 58 59## UIExtensionContentSession.terminateSelf 60 61terminateSelf(callback: AsyncCallback<void>): void 62 63停止UIExtensionContentSession对应的窗口界面对象。使用callback异步回调。 64 65**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 66 67**参数：** 68 69| 参数名 | 类型 | 必填 | 说明 | 70| -------- | -------- | -------- | -------- | 71| callback | AsyncCallback<void> | 是 | 回调函数。当停止UIExtensionContentSession对应的窗口界面对象成功，err为undefined，否则为错误对象。 | 72 73**错误码：** 74 75以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 76 77| 错误码ID | 错误信息 | 78| ------- | -------------------------------- | 79| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 80 81**示例：** 82 83```ts 84import { UIExtensionContentSession } from '@kit.AbilityKit'; 85import { BusinessError } from '@kit.BasicServicesKit'; 86 87let storage = LocalStorage.getShared(); 88 89@Entry(storage) 90@Component 91struct Index { 92 private session: UIExtensionContentSession | undefined = 93 storage.get<UIExtensionContentSession>('session'); 94 95 build() { 96 RelativeContainer() { 97 Button('TerminateSelf') 98 .onClick(() => { 99 this.session?.terminateSelf((err: BusinessError) => { 100 if (err) { 101 console.error(`Failed to terminate self, code: ${err.code}, msg: ${err.message}`); 102 return; 103 } 104 console.info(`Successed in terminating self.`); 105 }); 106 107 storage.clear(); 108 }) 109 } 110 .height('100%') 111 .width('100%') 112 } 113} 114``` 115 116## UIExtensionContentSession.terminateSelf 117 118terminateSelf(): Promise<void> 119 120停止UIExtensionContentSession对应的窗口界面对象。使用Promise异步回调。 121 122**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 123 124**返回值：** 125 126| 类型 | 说明 | 127| -------- | -------- | 128| Promise<void> | Promise对象。无返回结果的Promise对象。 | 129 130**示例：** 131 132```ts 133import { UIExtensionContentSession } from '@kit.AbilityKit'; 134import { BusinessError } from '@kit.BasicServicesKit'; 135 136let storage = LocalStorage.getShared(); 137 138@Entry(storage) 139@Component 140struct Index { 141 private session: UIExtensionContentSession | undefined = 142 storage.get<UIExtensionContentSession>('session'); 143 144 build() { 145 RelativeContainer() { 146 Button('TerminateSelf') 147 .onClick(() => { 148 this.session?.terminateSelf() 149 .then(() => { 150 console.info(`Successed in terminating self.`); 151 }) 152 .catch((err: BusinessError) => { 153 console.error(`Failed to terminate self, code: ${err.code}, msg: ${err.message}`); 154 }); 155 156 storage.clear(); 157 }) 158 } 159 .height('100%') 160 .width('100%') 161 } 162} 163``` 164 165## UIExtensionContentSession.terminateSelfWithResult 166 167terminateSelfWithResult(parameter: AbilityResult, callback: AsyncCallback<void>): void 168 169停止UIExtensionContentSession对应的窗口界面对象，并将结果返回给UIExtensionComponent控件。使用callback异步回调。 170 171**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 172 173**参数：** 174 175| 参数名 | 类型 | 必填 | 说明 | 176| -------- | -------- | -------- | -------- | 177| parameter | [AbilityResult](js-apis-inner-ability-abilityResult.md) | 是 | 返回给UIExtensionComponent控件的信息。 | 178| callback | AsyncCallback<void> | 是 | 回调函数。当停止成功，err为undefined，否则为错误对象。 | 179 180**错误码：** 181 182以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 183 184| 错误码ID | 错误信息 | 185| ------- | -------------------------------- | 186| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 187 188**示例：** 189 190```ts 191import { UIExtensionContentSession, common } from '@kit.AbilityKit'; 192import { BusinessError } from '@kit.BasicServicesKit'; 193 194let storage = LocalStorage.getShared(); 195 196@Entry(storage) 197@Component 198struct Index { 199 private session: UIExtensionContentSession | undefined = 200 storage.get<UIExtensionContentSession>('session'); 201 202 build() { 203 RelativeContainer() { 204 Button('TerminateSelfWithResult') 205 .onClick(() => { 206 let abilityResult: common.AbilityResult = { 207 resultCode: 0, 208 want: { 209 bundleName: 'com.ohos.uiextensioncontentsession', 210 parameters: { 211 'result': 123456 212 } 213 } 214 }; 215 216 this.session?.terminateSelfWithResult(abilityResult, (err: BusinessError) => { 217 if (err) { 218 console.error(`Failed to terminate self with result, code: ${err.code}, msg: ${err.message}`); 219 return; 220 } 221 console.info(`Successed in terminating self with result.`); 222 }); 223 224 storage.clear(); 225 }) 226 } 227 .height('100%') 228 .width('100%') 229 } 230} 231``` 232 233## UIExtensionContentSession.terminateSelfWithResult 234 235terminateSelfWithResult(parameter: AbilityResult): Promise<void> 236 237停止UIExtensionContentSession对应的窗口界面对象，并将结果返回给UIExtensionComponent控件。使用Promise异步回调。 238 239**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 240 241**参数：** 242 243| 参数名 | 类型 | 必填 | 说明 | 244| -------- | -------- | -------- | -------- | 245| parameter | [AbilityResult](js-apis-inner-ability-abilityResult.md) | 是 | 返回给UIExtensionComponent控件的信息。 | 246 247**返回值：** 248 249| 类型 | 说明 | 250| -------- | -------- | 251| Promise<void> | Promise对象。无返回结果的Promise对象。 | 252 253**错误码：** 254 255以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 256 257| 错误码ID | 错误信息 | 258| ------- | -------------------------------- | 259| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 260 261**示例：** 262 263```ts 264import { UIExtensionContentSession, common } from '@kit.AbilityKit'; 265import { BusinessError } from '@kit.BasicServicesKit'; 266 267let storage = LocalStorage.getShared(); 268 269@Entry(storage) 270@Component 271struct Index { 272 private session: UIExtensionContentSession | undefined = 273 storage.get<UIExtensionContentSession>('session'); 274 275 build() { 276 RelativeContainer() { 277 Button('TerminateSelfWithResult') 278 .onClick(() => { 279 let abilityResult: common.AbilityResult = { 280 resultCode: 0, 281 want: { 282 bundleName: 'com.ohos.uiextensioncontentsession', 283 parameters: { 284 'result': 123456 285 } 286 } 287 }; 288 289 this.session?.terminateSelfWithResult(abilityResult) 290 .then(() => { 291 console.info(`Successed in terminating self with result.`); 292 }) 293 .catch((err: BusinessError) => { 294 console.error(`Failed to terminate self with result, code: ${err.code}, msg: ${err.message}`); 295 }); 296 297 storage.clear(); 298 }) 299 } 300 .height('100%') 301 .width('100%') 302 } 303} 304``` 305 306## UIExtensionContentSession.setWindowPrivacyMode 307 308setWindowPrivacyMode(isPrivacyMode: boolean): Promise<void> 309 310设置窗口是否为隐私模式。设置为隐私模式的窗口，窗口内容将无法被截屏或录屏。使用Promise异步回调。 311 312**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 313 314**需要权限**：ohos.permission.PRIVACY_WINDOW 315 316**参数：** 317 318| 参数名 | 类型 | 必填 | 说明 | 319| ------------- | ------- | -- | ----------------------------------------------------- | 320| isPrivacyMode | boolean | 是 | 窗口是否为隐私模式。true表示模式开启；false表示模式关闭。 | 321 322**返回值：** 323 324| 类型 | 说明 | 325| ------------------- | ------------------------ | 326| Promise<void> | Promise对象。无返回结果的Promise对象。 | 327 328**错误码：** 329 330以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 331 332| 错误码ID | 错误信息 | 333| ------- | -------------------------------- | 334| 201 | The application does not have permission to call the interface. | 335| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 336 337**示例：** 338 339```ts 340import { UIExtensionContentSession, UIExtensionAbility, Want } from '@kit.AbilityKit'; 341import { BusinessError } from '@kit.BasicServicesKit'; 342 343export default class UIExtAbility extends UIExtensionAbility { 344 // ... 345 346 onSessionCreate(want: Want, session: UIExtensionContentSession): void { 347 let isPrivacyMode: boolean = true; 348 try { 349 session.setWindowPrivacyMode(isPrivacyMode) 350 .then(() => { 351 console.info(`Successed in setting window to privacy mode.`); 352 }) 353 .catch((err: BusinessError) => { 354 console.error(`Failed to set window to privacy mode, code: ${err.code}, msg: ${err.message}`); 355 }); 356 } catch (e) { 357 let code = (e as BusinessError).code; 358 let msg = (e as BusinessError).message; 359 console.error(`Failed to set window to privacy mode, code: ${code}, msg: ${msg}`); 360 } 361 } 362 363 // ... 364} 365``` 366 367## UIExtensionContentSession.setWindowPrivacyMode 368 369setWindowPrivacyMode(isPrivacyMode: boolean, callback: AsyncCallback<void>): void 370 371设置窗口是否为隐私模式。设置为隐私模式的窗口，窗口内容将无法被截屏或录屏。使用callback异步回调。 372 373**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 374 375**需要权限**：ohos.permission.PRIVACY_WINDOW 376 377**参数：** 378 379| 参数名 | 类型 | 必填 | 说明 | 380| ------------- | ------------------------- | -- | ------------------------------------------------------ | 381| isPrivacyMode | boolean | 是 | 窗口是否为隐私模式。true表示模式开启；false表示模式关闭。 | 382| callback | AsyncCallback<void> | 是 | 回调函数。当设置成功，err为undefined，否则为错误对象。 | 383 384**错误码：** 385 386以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)。 387 388| 错误码ID | 错误信息 | 389| ------- | -------------------------------- | 390| 201 | The application does not have permission to call the interface. | 391| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 392 393**示例：** 394 395```ts 396import { UIExtensionContentSession, UIExtensionAbility, Want } from '@kit.AbilityKit'; 397import { BusinessError } from '@kit.BasicServicesKit'; 398 399export default class UIExtAbility extends UIExtensionAbility { 400 // ... 401 402 onSessionCreate(want: Want, session: UIExtensionContentSession): void { 403 let isPrivacyMode: boolean = true; 404 try { 405 session.setWindowPrivacyMode(isPrivacyMode, (err: BusinessError) => { 406 if (err) { 407 console.error(`Failed to set window to privacy mode, code: ${err.code}, msg: ${err.message}`); 408 return; 409 } 410 console.info(`Successed in setting window to privacy mode.`); 411 }); 412 } catch (e) { 413 let code = (e as BusinessError).code; 414 let msg = (e as BusinessError).message; 415 console.error(`Failed to set window to privacy mode, code: ${code}, msg: ${msg}`); 416 } 417 } 418 419 // ... 420} 421``` 422 423## UIExtensionContentSession.startAbilityByType<sup>11+</sup> 424 425startAbilityByType(type: string, wantParam: Record<string, Object>, 426 abilityStartCallback: AbilityStartCallback, callback: AsyncCallback\<void>): void 427 428通过type隐式启动UIExtensionAbility。使用callback异步回调。仅支持处于前台的应用调用。 429 430**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 431 432**参数：** 433 434| 参数名 | 类型 | 必填 | 说明 | 435| -------- | -------- | -------- | -------- | 436| type | string | 是 | 显示拉起的UIExtensionAbility类型<!--Del-->，取值详见[通过startAbilityByType接口拉起垂类面板](../../application-models/start-intent-panel.md#匹配规则)<!--DelEnd-->。 | 437| wantParam | Record<string, Object> | 是 | 表示扩展参数。 | 438| abilityStartCallback | [AbilityStartCallback](js-apis-inner-application-abilityStartCallback.md) | 是 | 回调函数，返回启动失败后的详细错误信息。 | 439| callback | AsyncCallback\<void> | 是 |回调函数。当启动Ability成功，err为undefined，否则为错误对象。 | 440 441**错误码：** 442 443以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 444 445| 错误码ID | 错误信息 | 446| ------- | -------------------------------- | 447| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 448| 16000050 | Internal error. | 449 450**示例：** 451 452```ts 453import { UIExtensionContentSession, UIExtensionAbility, Want, common } from '@kit.AbilityKit'; 454import { BusinessError } from '@kit.BasicServicesKit'; 455 456export default class UIExtAbility extends UIExtensionAbility { 457 // ... 458 459 onSessionCreate(want: Want, session: UIExtensionContentSession): void { 460 let wantParams: Record<string, Object> = { 461 'sceneType': 1 462 }; 463 let abilityStartCallback: common.AbilityStartCallback = { 464 onError: (code: number, name: string, message: string) => { 465 console.error(`onError, code: ${code}, name: ${name}, msg: ${message}`); 466 }, 467 onResult: (result: common.AbilityResult) => { 468 console.info(`onResult, result: ${JSON.stringify(result)}`); 469 } 470 }; 471 472 session.startAbilityByType('test', wantParams, abilityStartCallback, (err: BusinessError) => { 473 if (err) { 474 console.error(`Failed to startAbilityByType, code: ${err.code}, msg: ${err.message}`); 475 return; 476 } 477 console.info(`Successed in startAbilityByType`); 478 }); 479 } 480 481 // ... 482} 483``` 484 485## UIExtensionContentSession.startAbilityByType<sup>11+</sup> 486 487startAbilityByType(type: string, wantParam: Record<string, Object>, 488 abilityStartCallback: AbilityStartCallback): Promise\<void> 489 490通过type隐式启动UIExtensionAbility。使用Promise异步回调。仅支持处于前台的应用调用。 491 492**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 493 494**参数：** 495 496| 参数名 | 类型 | 必填 | 说明 | 497| -------- | -------- | -------- | -------- | 498| type | string | 是 | 显示拉起的UIExtensionAbility类型<!--Del-->，取值详见[通过startAbilityByType接口拉起垂类面板](../../application-models/start-intent-panel.md#匹配规则)<!--DelEnd-->。 | 499| wantParam | Record<string, Object> | 是 | 表示扩展参数。 | 500| abilityStartCallback | [AbilityStartCallback](js-apis-inner-application-abilityStartCallback.md) | 是 | 回调函数，返回启动失败后的详细错误信息。 | 501 502**返回值：** 503 504| 类型 | 说明 | 505| -------- | -------- | 506| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 507 508**错误码：** 509 510以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[元能力子系统错误码](errorcode-ability.md)。 511 512| 错误码ID | 错误信息 | 513| ------- | -------------------------------- | 514| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 515| 16000050 | Internal error. | 516 517**示例：** 518 519```ts 520import { UIExtensionContentSession, UIExtensionAbility, Want, common } from '@kit.AbilityKit'; 521import { BusinessError } from '@kit.BasicServicesKit'; 522 523export default class UIExtAbility extends UIExtensionAbility { 524 // ... 525 526 onSessionCreate(want: Want, session: UIExtensionContentSession): void { 527 let wantParams: Record<string, Object> = { 528 'sceneType': 1 529 }; 530 let abilityStartCallback: common.AbilityStartCallback = { 531 onError: (code: number, name: string, message: string) => { 532 console.error(`onError, code: ${code}, name: ${name}, msg: ${message}`); 533 }, 534 onResult: (result: common.AbilityResult) => { 535 console.info(`onResult, result: ${JSON.stringify(result)}`); 536 } 537 }; 538 539 session.startAbilityByType('test', wantParams, abilityStartCallback) 540 .then(() => { 541 console.info(`Successed in startAbilityByType`); 542 }) 543 .catch((err: BusinessError) => { 544 console.error(`Failed to startAbilityByType, code: ${err.code}, msg: ${err.message}`); 545 }); 546 } 547 548 // ... 549} 550``` 551 552## UIExtensionContentSession.getUIExtensionWindowProxy<sup>12+</sup> 553 554getUIExtensionWindowProxy(): uiExtension.WindowProxy 555 556获取UIExtension窗口代理。 557 558**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 559 560**返回值：** 561 562| 类型 | 说明 | 563| -------- | -------- | 564| uiExtension.WindowProxy | 返回UIExtension的窗口代理。 | 565 566**错误码：** 567 568以下错误码详细介绍请参考[元能力子系统错误码](errorcode-ability.md)。 569 570| 错误码ID | 错误信息 | 571| ------- | -------------------------------- | 572| 16000050 | Internal error. | 573 574**示例：** 575 576```ts 577// Index.ets 578import { UIExtensionContentSession } from '@kit.AbilityKit'; 579import uiExtension from '@ohos.arkui.uiExtension'; 580 581let storage = LocalStorage.getShared(); 582 583@Entry(storage) 584@Component 585struct Extension { 586 @State message: string = 'EmbeddedUIExtensionAbility Index'; 587 private session: UIExtensionContentSession | undefined = storage.get<UIExtensionContentSession>('session'); 588 private extensionWindow: uiExtension.WindowProxy | undefined = this.session?.getUIExtensionWindowProxy(); 589 590 aboutToAppear(): void { 591 this.extensionWindow?.on('windowSizeChange', (size) => { 592 console.info(`size = ${JSON.stringify(size)}`); 593 }); 594 this.extensionWindow?.on('avoidAreaChange', (info) => { 595 console.info(`type = ${JSON.stringify(info.type)}, area = ${JSON.stringify(info.area)}`); 596 }); 597 } 598 599 aboutToDisappear(): void { 600 this.extensionWindow?.off('windowSizeChange'); 601 this.extensionWindow?.off('avoidAreaChange'); 602 } 603 604 build() { 605 Column() { 606 Text(this.message) 607 .fontSize(20) 608 .fontWeight(FontWeight.Bold) 609 } 610 .width('100%') 611 } 612} 613```