1# @ohos.app.ability.UIExtensionContentSession (UI Operation Class for ExtensionAbilities with UI)
2
3**UIExtensionContentSession** is an instance created when the [UIExtensionAbility](js-apis-app-ability-uiExtensionAbility.md) loads UI content. When the UIExtensionComponent starts a UIExtensionAbility, the UIExtensionAbility creates a UIExtensionContentSession instance and returns it through the [onSessionCreate](js-apis-app-ability-uiExtensionAbility.md#uiextensionabilityonsessioncreate) callback. One UIExtensionComponent corresponds to one **UIExtensionContentSession** instance, which provides methods such as UI loading and result notification. The **UIExtensionContentSession** instances of multiple UIExtensionAbilities are operated separately.
4
5> **NOTE**
6>
7> The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version.
8>
9> The APIs of this module can be used only in the stage model.
10
11## Modules to Import
12
13```ts
14import { UIExtensionContentSession } from '@kit.AbilityKit';
15```
16
17## UIExtensionContentSession.loadContent
18
19loadContent(path: string, storage?: LocalStorage): void
20
21Loads content from a page associated with a local storage to the window corresponding to the current UIExtensionComponent.
22
23**System capability**: SystemCapability.Ability.AbilityRuntime.Core
24
25**Parameters**
26
27| Name | Type                                           | Mandatory| Description                                                        |
28| ------- | ----------------------------------------------- | ---- | ------------------------------------------------------------ |
29| path    | string                                          | Yes  | Path of the page from which the content will be loaded.                                        |
30| storage | [LocalStorage](../../quick-start/arkts-localstorage.md) | No  | A storage unit, which provides storage for variable state properties and non-variable state properties of an application. This parameter is left blank by default.|
31
32**Error codes**
33
34For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md).
35
36| ID| Error Message|
37| ------- | -------------------------------- |
38| 401      | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
39| 16000050 | Internal error. |
40
41## UIExtensionContentSession.terminateSelf
42
43terminateSelf(callback: AsyncCallback<void>): void
44
45Stops the window object corresponding to this **UIExtensionContentSession** instance. This API uses an asynchronous callback to return the result.
46
47**System capability**: SystemCapability.Ability.AbilityRuntime.Core
48
49**Parameters**
50
51| Name| Type| Mandatory| Description|
52| -------- | -------- | -------- | -------- |
53| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the window object is stopped, **err** is **undefined**; otherwise, **err** is an error object.|
54
55**Error codes**
56
57For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
58
59| ID| Error Message|
60| ------- | -------------------------------- |
61| 401      | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
62
63## UIExtensionContentSession.terminateSelf
64
65terminateSelf(): Promise<void>
66
67Stops the window object corresponding to this **UIExtensionContentSession** instance. This API uses a promise to return the result.
68
69**System capability**: SystemCapability.Ability.AbilityRuntime.Core
70
71**Return value**
72
73| Type| Description|
74| -------- | -------- |
75| Promise<void> | Promise that returns no value.|
76
77## UIExtensionContentSession.terminateSelfWithResult
78
79terminateSelfWithResult(parameter: AbilityResult, callback: AsyncCallback<void>): void
80
81Stops the window object corresponding to this **UIExtensionContentSession** instance and returns the result to the UIExtensionComponent. This API uses an asynchronous callback to return the result.
82
83**System capability**: SystemCapability.Ability.AbilityRuntime.Core
84
85**Parameters**
86
87| Name| Type| Mandatory| Description|
88| -------- | -------- | -------- | -------- |
89| parameter | [AbilityResult](js-apis-inner-ability-abilityResult.md) | Yes| Result returned to the UIExtensionComponent.|
90| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the window object is stopped, **err** is **undefined**; otherwise, **err** is an error object.|
91
92**Error codes**
93
94For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
95
96| ID| Error Message|
97| ------- | -------------------------------- |
98| 401      | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
99
100## UIExtensionContentSession.terminateSelfWithResult
101
102terminateSelfWithResult(parameter: AbilityResult): Promise<void>
103
104Stops the window object corresponding to this **UIExtensionContentSession** instance and returns the result to the UIExtensionComponent. This API uses a promise to return the result.
105
106**System capability**: SystemCapability.Ability.AbilityRuntime.Core
107
108**Parameters**
109
110| Name| Type| Mandatory| Description|
111| -------- | -------- | -------- | -------- |
112| parameter | [AbilityResult](js-apis-inner-ability-abilityResult.md) | Yes| Result returned to the UIExtensionComponent.|
113
114**Return value**
115
116| Type| Description|
117| -------- | -------- |
118| Promise<void> | Promise that returns no value.|
119
120**Error codes**
121
122For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
123
124| ID| Error Message|
125| ------- | -------------------------------- |
126| 401      | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
127
128## UIExtensionContentSession.setWindowPrivacyMode
129
130setWindowPrivacyMode(isPrivacyMode: boolean): Promise<void>
131
132Sets whether the window is in privacy mode. A window in privacy mode cannot be captured or recorded. This API uses a promise to return the result.
133
134**System capability**: SystemCapability.Ability.AbilityRuntime.Core
135
136**Required permissions**: ohos.permission.PRIVACY_WINDOW
137
138**Parameters**
139
140| Name| Type| Mandatory| Description|
141| ------------- | ------- | -- | ----------------------------------------------------- |
142| isPrivacyMode | boolean | Yes| Whether the window is in privacy mode. The value **true** means that the window is in privacy mode, and **false** means the opposite.|
143
144**Return value**
145
146| Type| Description|
147| ------------------- | ------------------------ |
148| Promise<void> | Promise that returns no value.|
149
150**Error codes**
151
152For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
153
154| ID| Error Message|
155| ------- | -------------------------------- |
156| 201      | The application does not have permission to call the interface. |
157| 401      | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
158
159## UIExtensionContentSession.setWindowPrivacyMode
160
161setWindowPrivacyMode(isPrivacyMode: boolean, callback: AsyncCallback<void>): void
162
163Sets whether the window is in privacy mode. A window in privacy mode cannot be captured or recorded. This API uses an asynchronous callback to return the result.
164
165**System capability**: SystemCapability.Ability.AbilityRuntime.Core
166
167**Required permissions**: ohos.permission.PRIVACY_WINDOW
168
169**Parameters**
170
171| Name| Type| Mandatory| Description|
172| ------------- | ------------------------- | -- | ------------------------------------------------------ |
173| isPrivacyMode | boolean                   | Yes| Whether the window is in privacy mode. The value **true** means that the window is in privacy mode, and **false** means the opposite. |
174| callback      | AsyncCallback<void> | Yes| Callback used to return the result. If the setting is successful, **err** is **undefined**. Otherwise, **err** is an error object.|
175
176**Error codes**
177
178For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
179
180| ID| Error Message|
181| ------- | -------------------------------- |
182| 201      | The application does not have permission to call the interface. |
183| 401      | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
184
185## UIExtensionContentSession.startAbilityByType<sup>11+</sup>
186
187startAbilityByType(type: string, wantParam: Record<string, Object>,
188    abilityStartCallback: AbilityStartCallback, callback: AsyncCallback\<void>): void
189
190Implicitly starts a given type of UIExtensionAbility. This API uses an asynchronous callback to return the result. It can be called only by applications running in the foreground.
191
192**System capability**: SystemCapability.Ability.AbilityRuntime.Core
193
194**Parameters**
195
196| Name| Type| Mandatory| Description|
197| -------- | -------- | -------- | -------- |
198| type | string | Yes| Type of the UIExtensionAbility to start.<!--Del--> For details, see [Starting an Application of the Specified Type](../../application-models/start-intent-panel.md#matching-rules).<!--DelEnd-->|
199| wantParam | Record<string, Object> | Yes| Extended parameter.|
200| abilityStartCallback | [AbilityStartCallback](js-apis-inner-application-abilityStartCallback.md) | Yes| Callback used to return the detailed error information if the startup fails.|
201| callback | AsyncCallback\<void> | Yes|Callback used to return the result. If the ability is started, **err** is **undefined**; otherwise, **err** is an error object.|
202
203**Error codes**
204
205For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md).
206
207| ID| Error Message|
208| ------- | -------------------------------- |
209| 401      | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
210| 16000050 | Internal error. |
211
212## UIExtensionContentSession.startAbilityByType<sup>11+</sup>
213
214startAbilityByType(type: string, wantParam: Record<string, Object>,
215    abilityStartCallback: AbilityStartCallback): Promise\<void>
216
217Implicitly starts a given type of UIExtensionAbility. This API uses a promise to return the result. It can be called only by applications running in the foreground.
218
219**System capability**: SystemCapability.Ability.AbilityRuntime.Core
220
221**Parameters**
222
223| Name| Type| Mandatory| Description|
224| -------- | -------- | -------- | -------- |
225| type | string | Yes| Type of the UIExtensionAbility to start.<!--Del--> For details, see [Starting an Application of the Specified Type](../../application-models/start-intent-panel.md#matching-rules).<!--DelEnd-->|
226| wantParam | Record<string, Object> | Yes| Extended parameter.|
227| abilityStartCallback | [AbilityStartCallback](js-apis-inner-application-abilityStartCallback.md) | Yes| Callback used to return the detailed error information if the startup fails.|
228
229**Return value**
230
231| Type| Description|
232| -------- | -------- |
233| Promise\<void> | Promise that returns no value.|
234
235**Error codes**
236
237For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ability Error Codes](errorcode-ability.md).
238
239| ID| Error Message|
240| ------- | -------------------------------- |
241| 401      | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. |
242| 16000050 | Internal error. |
243
244## UIExtensionContentSession.getUIExtensionWindowProxy<sup>12+</sup>
245
246getUIExtensionWindowProxy(): uiExtension.WindowProxy
247
248Obtains the window proxy of this UIExtensionAbility.
249
250**System capability**: SystemCapability.Ability.AbilityRuntime.Core
251
252**Return value**
253
254| Type| Description|
255| -------- | -------- |
256| uiExtension.WindowProxy | Window proxy.|
257
258**Error codes**
259
260For details about the error codes, see [Ability Error Codes](errorcode-ability.md).
261
262| ID| Error Message|
263| ------- | -------------------------------- |
264| 16000050 | Internal error. |
265
266**Example**
267
268```ts
269// Index.ets
270import { UIExtensionContentSession } from '@kit.AbilityKit';
271import uiExtension from '@ohos.arkui.uiExtension';
272
273let storage = LocalStorage.getShared();
274
275@Entry(storage)
276@Component
277struct Extension {
278  @State message: string = 'EmbeddedUIExtensionAbility Index';
279  private session: UIExtensionContentSession | undefined = storage.get<UIExtensionContentSession>('session');
280  private extensionWindow: uiExtension.WindowProxy | undefined = this.session?.getUIExtensionWindowProxy();
281
282  aboutToAppear(): void {
283    this.extensionWindow?.on('windowSizeChange', (size) => {
284      console.info(`size = ${JSON.stringify(size)}`);
285    });
286    this.extensionWindow?.on('avoidAreaChange', (info) => {
287      console.info(`type = ${JSON.stringify(info.type)}, area = ${JSON.stringify(info.area)}`);
288    });
289  }
290
291  aboutToDisappear(): void {
292    this.extensionWindow?.off('windowSizeChange');
293    this.extensionWindow?.off('avoidAreaChange');
294  }
295
296  build() {
297    Column() {
298      Text(this.message)
299        .fontSize(20)
300        .fontWeight(FontWeight.Bold)
301    }
302    .width('100%')
303  }
304}
305```
306
307 <!--no_check-->