1# @ohos.app.form.FormExtensionAbility (FormExtensionAbility)
2
3The **FormExtensionAbility** module provides lifecycle callbacks invoked when a widget is created, destroyed, or updated.
4
5> **NOTE**
6>
7> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.
8>
9> The following modules cannot be referenced in the FormExtensionAbility, as doing so may cause the program to exit abnormally:
10> - @ohos.ability.particleAbility (ParticleAbility)
11> - @ohos.multimedia.audio (Audio Management)
12> - @ohos.multimedia.camera (Camera Management)
13> - @ohos.multimedia.media (Media)
14> - @ohos.resourceschedule.backgroundTaskManager (Background Task Management)
15
16## Modules to Import
17
18```ts
19import { FormExtensionAbility } from '@kit.FormKit';
20```
21
22## Attributes
23
24**Model restriction**: This API can be used only in the stage model.
25
26**System capability**: SystemCapability.Ability.Form
27
28| Name   | Type                                                        | Readable| Writable| Description                                                        |
29| ------- | ------------------------------------------------------------ | ---- | ---- | ------------------------------------------------------------ |
30| context | [FormExtensionContext](js-apis-inner-application-formExtensionContext.md) | Yes  | No  | Context of the FormExtensionAbility. This context is inherited from [ExtensionContext](../apis-ability-kit/js-apis-inner-application-extensionContext.md).<br>**Atomic service API**: This API can be used in atomic services since API version 11.|
31
32## onAddForm
33
34onAddForm(want: Want): formBindingData.FormBindingData
35
36Called to notify the widget provider that a **Form** instance (widget) is being created.
37
38**Model restriction**: This API can be used only in the stage model.
39
40**Atomic service API**: This API can be used in atomic services since API version 11.
41
42**System capability**: SystemCapability.Ability.Form
43
44**Parameters**
45
46| Name| Type                                  | Mandatory| Description                                                        |
47| ------ | -------------------------------------- | ---- | ------------------------------------------------------------ |
48| want   | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes  | Want information related to the FormExtensionAbility, including the widget ID, name, and style. The information must be managed as persistent data to facilitate subsequent widget update and deletion.|
49
50**Return value**
51
52| Type                                                        | Description                                                       |
53| ------------------------------------------------------------ | ----------------------------------------------------------- |
54| [formBindingData.FormBindingData](js-apis-app-form-formBindingData.md#formbindingdata) | A **formBindingData.FormBindingData** object containing the data to be displayed on the widget.|
55
56**Example**
57
58```ts
59import { formBindingData, FormExtensionAbility } from '@kit.FormKit';
60import { Want } from '@kit.AbilityKit';
61
62export default class MyFormExtensionAbility extends FormExtensionAbility {
63  onAddForm(want: Want) {
64    console.log(`FormExtensionAbility onAddForm, want: ${want.abilityName}`);
65    let dataObj1: Record<string, string> = {
66      'temperature': '11c',
67      'time': '11:00'
68    };
69
70    let obj1: formBindingData.FormBindingData = formBindingData.createFormBindingData(dataObj1);
71    return obj1;
72  }
73}
74```
75
76## onCastToNormalForm
77
78onCastToNormalForm(formId: string): void
79
80Called to notify the widget provider that a temporary widget is being converted to a normal one.
81
82**Model restriction**: This API can be used only in the stage model.
83
84**Atomic service API**: This API can be used in atomic services since API version 11.
85
86**System capability**: SystemCapability.Ability.Form
87
88**Parameters**
89
90| Name| Type  | Mandatory| Description                    |
91| ------ | ------ | ---- | ------------------------ |
92| formId | string | Yes  | ID of the widget that requests to be converted to a normal one.|
93
94**Example**
95
96```ts
97import { FormExtensionAbility } from '@kit.FormKit';
98
99export default class MyFormExtensionAbility extends FormExtensionAbility {
100  onCastToNormalForm(formId: string) {
101    console.log(`FormExtensionAbility onCastToNormalForm, formId: ${formId}`);
102  }
103};
104```
105
106## onUpdateForm
107
108onUpdateForm(formId: string, wantParams?: Record<string, Object>): void
109
110Called to notify the widget provider that a widget is being updated, with update parameters carried. After obtaining the latest data, your application should call [updateForm](js-apis-app-form-formProvider.md#updateform) of **formProvider** to update the widget data.
111
112**Model restriction**: This API can be used only in the stage model.
113
114**Atomic service API**: This API can be used in atomic services since API version 11.
115
116**System capability**: SystemCapability.Ability.Form
117
118**Parameters**
119
120| Name| Type  | Mandatory| Description              |
121| ------ | ------ | ---- | ------------------ |
122| formId | string | Yes  | ID of the widget that requests to be updated.|
123| wantParams<sup>12+</sup> | Record<string, Object> | No  | Parameters used for the update.|
124
125**Example**
126
127```ts
128import { formBindingData, FormExtensionAbility, formProvider } from '@kit.FormKit';
129import { BusinessError } from '@kit.BasicServicesKit';
130
131export default class MyFormExtensionAbility extends FormExtensionAbility {
132  onUpdateForm(formId: string, wantParams?: Record<string, Object>) {
133    console.log(`FormExtensionAbility onUpdateForm, formId: ${formId},
134        wantPara: ${wantParams?.['ohos.extra.param.key.host_bg_inverse_color']}`);
135    let param: Record<string, string> = {
136      'temperature': '22c',
137      'time': '22:00'
138    }
139    let obj2: formBindingData.FormBindingData = formBindingData.createFormBindingData(param);
140    formProvider.updateForm(formId, obj2).then(() => {
141      console.log(`FormExtensionAbility context updateForm`);
142    }).catch((error: BusinessError) => {
143      console.error(`FormExtensionAbility context updateForm failed, data: ${error}`);
144    });
145  }
146};
147```
148
149## onChangeFormVisibility
150
151onChangeFormVisibility(newStatus: Record\<string, number>): void
152
153Called to notify the widget provider that the widget visibility status is being changed.
154This API is valid only for system applications when **formVisibleNotify** is set to **true**.
155
156**Model restriction**: This API can be used only in the stage model.
157
158**System capability**: SystemCapability.Ability.Form
159
160**Parameters**
161
162| Name | Type  | Mandatory| Description                  |
163| ------- | ------ | ---- | ---------------------- |
164| newStatus  | Record\<string, number> | Yes  | ID and visibility status of the widget to be changed.|
165
166**Example**
167
168```ts
169import { formBindingData, FormExtensionAbility, formProvider } from '@kit.FormKit';
170import { BusinessError } from '@kit.BasicServicesKit';
171
172// According to the ArkTS specification, **Object.keys** and **for..in...** cannot be used in .ets files to obtain the key value of an object. Use the user-defined function **getObjKeys** instead.
173// Extract this function to a .ts file and export it. Import this function to the required .ets file before using it.
174function getObjKeys(obj: Object): string[] {
175  let keys = Object.keys(obj);
176  return keys;
177}
178
179export default class MyFormExtensionAbility extends FormExtensionAbility {
180  onChangeFormVisibility(newStatus: Record<string, number>) {
181    console.log(`FormExtensionAbility onChangeFormVisibility, newStatus: ${newStatus}`);
182    let param: Record<string, string> = {
183      'temperature': '22c',
184      'time': '22:00'
185    }
186    let obj2: formBindingData.FormBindingData = formBindingData.createFormBindingData(param);
187
188    let keys: string[] = getObjKeys(newStatus);
189
190    for (let i: number = 0; i < keys.length; i++) {
191      console.log(`FormExtensionAbility onChangeFormVisibility, key: ${keys[i]}, value= ${newStatus[keys[i]]}`);
192      formProvider.updateForm(keys[i], obj2).then(() => {
193        console.log(`FormExtensionAbility context updateForm`);
194      }).catch((error: BusinessError) => {
195        console.error(`Operation updateForm failed. Cause: ${JSON.stringify(error)}`);
196      });
197    }
198  }
199};
200```
201
202## onFormEvent
203
204onFormEvent(formId: string, message: string): void
205
206Called to instruct the widget provider to process the widget event.
207
208**Model restriction**: This API can be used only in the stage model.
209
210**Atomic service API**: This API can be used in atomic services since API version 11.
211
212**System capability**: SystemCapability.Ability.Form
213
214**Parameters**
215
216| Name | Type  | Mandatory| Description                  |
217| ------- | ------ | ---- | ---------------------- |
218| formId  | string | Yes  | ID of the widget that requests the event.|
219| message | string | Yes  | Event message.            |
220
221**Example**
222
223```ts
224import { FormExtensionAbility } from '@kit.FormKit';
225
226export default class MyFormExtensionAbility extends FormExtensionAbility {
227  onFormEvent(formId: string, message: string) {
228    console.log(`FormExtensionAbility onFormEvent, formId: ${formId}, message: ${message}`);
229  }
230};
231```
232
233## onRemoveForm
234
235onRemoveForm(formId: string): void
236
237Called to notify the widget provider that a **Form** instance (widget) is being destroyed.
238
239**Model restriction**: This API can be used only in the stage model.
240
241**Atomic service API**: This API can be used in atomic services since API version 11.
242
243**System capability**: SystemCapability.Ability.Form
244
245**Parameters**
246
247| Name| Type  | Mandatory| Description              |
248| ------ | ------ | ---- | ------------------ |
249| formId | string | Yes  | ID of the widget to be destroyed.|
250
251**Example**
252
253```ts
254import { FormExtensionAbility } from '@kit.FormKit';
255
256export default class MyFormExtensionAbility extends FormExtensionAbility {
257  onRemoveForm(formId: string) {
258    console.log(`FormExtensionAbility onRemoveForm, formId: ${formId}`);
259  }
260};
261```
262
263## onConfigurationUpdate
264
265onConfigurationUpdate(newConfig: Configuration): void
266
267Called when the configuration of the environment where the FormExtensionAbility is running is updated.
268This lifecycle callback is triggered only when the configuration is updated while the FormExtensionAbility is alive. If no operation is performed within 10 seconds after a **FormExtensionAbility** instance is created, the instance will be deleted.
269
270**Model restriction**: This API can be used only in the stage model.
271
272**Atomic service API**: This API can be used in atomic services since API version 11.
273
274**System capability**: SystemCapability.Ability.Form
275
276**Parameters**
277
278| Name| Type| Mandatory| Description|
279| -------- | -------- | -------- | -------- |
280| newConfig | [Configuration](../apis-ability-kit/js-apis-app-ability-configuration.md) | Yes| New configuration.|
281
282**Example**
283
284```ts
285import { FormExtensionAbility } from '@kit.FormKit';
286import { Configuration } from '@kit.AbilityKit';
287
288export default class MyFormExtensionAbility extends FormExtensionAbility {
289  onConfigurationUpdate(newConfig: Configuration) {
290    // This lifecycle callback is triggered only when the configuration is updated while the FormExtensionAbility is alive.
291    // If no operation is performed within 10 seconds after a FormExtensionAbility instance is created, the instance will be deleted.
292    console.log(`onConfigurationUpdate, config: ${JSON.stringify(newConfig)}`);
293  }
294};
295```
296
297## onAcquireFormState
298
299onAcquireFormState?(want: Want): formInfo.FormState
300
301Called to notify the widget provider that the widget host is requesting the widget state. By default, the initial widget state is returned. (You can override this API as required.)
302
303**Model restriction**: This API can be used only in the stage model.
304
305**Atomic service API**: This API can be used in atomic services since API version 11.
306
307**System capability**: SystemCapability.Ability.Form
308
309**Parameters**
310
311| Name| Type| Mandatory| Description|
312| -------- | -------- | -------- | -------- |
313| want | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes| Description of the widget state, including the bundle name, ability name, module name, widget name, and widget dimension.|
314
315**Example**
316
317```ts
318import { FormExtensionAbility, formInfo } from '@kit.FormKit';
319import { Want } from '@kit.AbilityKit';
320
321export default class MyFormExtensionAbility extends FormExtensionAbility {
322  onAcquireFormState(want: Want) {
323    console.log(`FormExtensionAbility onAcquireFormState, want: ${want}`);
324    return formInfo.FormState.UNKNOWN;
325  }
326};
327```
328
329## onStop<sup>12+</sup>
330
331onStop?(): void
332
333Called when the widget process of the widget provider exits.
334
335**Model restriction**: This API can be used only in the stage model.
336
337**Atomic service API**: This API can be used in atomic services since API version 12.
338
339**System capability**: SystemCapability.Ability.Form
340
341**Example**
342
343```ts
344import { FormExtensionAbility } from '@kit.FormKit';
345
346export default class MyFormExtensionAbility extends FormExtensionAbility {
347  onStop() {
348    console.log(`FormExtensionAbility onStop`);
349  }
350}
351```
352