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> The APIs of this module can be used only in the stage model. 9 10## Modules to Import 11 12```ts 13import FormExtensionAbility from '@ohos.app.form.FormExtensionAbility'; 14``` 15 16## Attributes 17 18**System capability**: SystemCapability.Ability.Form 19 20| Name | Type | Readable| Writable| Description | 21| ------- | ------------------------------------------------------------ | ---- | ---- | ------------------------------------------------------------ | 22| context | [FormExtensionContext](js-apis-inner-application-formExtensionContext.md) | Yes | No | Context of the FormExtensionAbility. This context is inherited from [ExtensionContext](js-apis-inner-application-extensionContext.md).| 23 24## onAddForm 25 26onAddForm(want: Want): formBindingData.FormBindingData 27 28Called to notify the widget provider that a **Form** instance (widget) is being created. 29 30**System capability**: SystemCapability.Ability.Form 31 32**Parameters** 33 34| Name| Type | Mandatory| Description | 35| ------ | -------------------------------------- | ---- | ------------------------------------------------------------ | 36| want | [Want](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.| 37 38**Return value** 39 40| Type | Description | 41| ------------------------------------------------------------ | ----------------------------------------------------------- | 42| [formBindingData.FormBindingData](js-apis-app-form-formBindingData.md#formbindingdata) | A **formBindingData.FormBindingData** object containing the data to be displayed on the widget.| 43 44**Example** 45 46```ts 47import FormExtensionAbility from '@ohos.app.form.FormExtensionAbility'; 48import formBindingData from '@ohos.app.form.formBindingData'; 49import Want from '@ohos.app.ability.Want'; 50 51export default class MyFormExtensionAbility extends FormExtensionAbility { 52 onAddForm(want: Want) { 53 console.log(`FormExtensionAbility onAddForm, want: ${want.abilityName}`); 54 let dataObj1: Record<string, string> = { 55 'temperature': '11c', 56 'time': '11:00' 57 }; 58 59 let obj1: formBindingData.FormBindingData = formBindingData.createFormBindingData(dataObj1); 60 return obj1; 61 } 62} 63``` 64 65## onCastToNormalForm 66 67onCastToNormalForm(formId: string): void 68 69Called to notify the widget provider that a temporary widget is being converted to a normal one. 70 71**System capability**: SystemCapability.Ability.Form 72 73**Parameters** 74 75| Name| Type | Mandatory| Description | 76| ------ | ------ | ---- | ------------------------ | 77| formId | string | Yes | ID of the widget that requests to be converted to a normal one.| 78 79**Example** 80 81```ts 82import FormExtensionAbility from '@ohos.app.form.FormExtensionAbility'; 83 84export default class MyFormExtensionAbility extends FormExtensionAbility { 85 onCastToNormalForm(formId: string) { 86 console.log(`FormExtensionAbility onCastToNormalForm, formId: ${formId}`); 87 } 88}; 89``` 90 91## onUpdateForm 92 93onUpdateForm(formId: string): void 94 95Called to notify the widget provider that a widget is being updated. After obtaining the latest data, your application should call [updateForm](js-apis-app-form-formProvider.md#updateform) of **formProvider** to update the widget data. 96 97**System capability**: SystemCapability.Ability.Form 98 99**Parameters** 100 101| Name| Type | Mandatory| Description | 102| ------ | ------ | ---- | ------------------ | 103| formId | string | Yes | ID of the widget that requests to be updated.| 104 105**Example** 106 107```ts 108import FormExtensionAbility from '@ohos.app.form.FormExtensionAbility'; 109import formBindingData from '@ohos.app.form.formBindingData'; 110import formProvider from '@ohos.app.form.formProvider'; 111import Base from '@ohos.base'; 112 113export default class MyFormExtensionAbility extends FormExtensionAbility { 114 onUpdateForm(formId: string) { 115 console.log(`FormExtensionAbility onUpdateForm, formId: ${formId}`); 116 let param: Record<string, string> = { 117 'temperature': '22c', 118 'time': '22:00' 119 } 120 let obj2: formBindingData.FormBindingData = formBindingData.createFormBindingData(param); 121 formProvider.updateForm(formId, obj2).then(() => { 122 console.log(`FormExtensionAbility context updateForm`); 123 }).catch((error: Base.BusinessError) => { 124 console.error(`FormExtensionAbility context updateForm failed, data: ${error}`); 125 }); 126 } 127}; 128``` 129 130## onFormEvent 131 132onFormEvent(formId: string, message: string): void 133 134Called to instruct the widget provider to process the widget event. (This API can be used only in JS widget.) 135 136**System capability**: SystemCapability.Ability.Form 137 138**Parameters** 139 140| Name | Type | Mandatory| Description | 141| ------- | ------ | ---- | ---------------------- | 142| formId | string | Yes | ID of the widget that requests the event.| 143| message | string | Yes | Event message. | 144 145**Example** 146 147```ts 148import FormExtensionAbility from '@ohos.app.form.FormExtensionAbility'; 149 150export default class MyFormExtensionAbility extends FormExtensionAbility { 151 onFormEvent(formId: string, message: string) { 152 console.log(`FormExtensionAbility onFormEvent, formId: ${formId}, message: ${message}`); 153 } 154}; 155``` 156 157## onRemoveForm 158 159onRemoveForm(formId: string): void 160 161Called to notify the widget provider that a **Form** instance (widget) is being destroyed. 162 163**System capability**: SystemCapability.Ability.Form 164 165**Parameters** 166 167| Name| Type | Mandatory| Description | 168| ------ | ------ | ---- | ------------------ | 169| formId | string | Yes | ID of the widget to be destroyed.| 170 171**Example** 172 173```ts 174import FormExtensionAbility from '@ohos.app.form.FormExtensionAbility'; 175 176export default class MyFormExtensionAbility extends FormExtensionAbility { 177 onRemoveForm(formId: string) { 178 console.log(`FormExtensionAbility onRemoveForm, formId: ${formId}`); 179 } 180}; 181``` 182 183## onConfigurationUpdate 184 185onConfigurationUpdate(newConfig: Configuration): void 186 187Called when the configuration of the environment where the FormExtensionAbility is running is updated. 188This lifecycle callback is triggered only when the configuration is updated while the FormExtensionAbility is alive. If no operation is performed within 5 seconds after a **FormExtensionAbility** instance is created, the instance will be deleted. 189 190**System capability**: SystemCapability.Ability.Form 191 192**Parameters** 193 194| Name| Type| Mandatory| Description| 195| -------- | -------- | -------- | -------- | 196| newConfig | [Configuration](js-apis-application-configuration.md) | Yes| New configuration.| 197 198**Example** 199 200```ts 201import FormExtensionAbility from '@ohos.app.form.FormExtensionAbility'; 202import { Configuration } from '@ohos.app.ability.Configuration'; 203 204export default class MyFormExtensionAbility extends FormExtensionAbility { 205 onConfigurationUpdate(newConfig: Configuration) { 206 // This lifecycle callback is triggered only when the configuration is updated while the FormExtensionAbility is alive. 207 // If no operation is performed within 5 seconds after a FormExtensionAbility instance is created, the instance will be deleted. 208 console.log(`onConfigurationUpdate, config: ${JSON.stringify(newConfig)}`); 209 } 210}; 211``` 212 213## onAcquireFormState 214 215onAcquireFormState?(want: Want): formInfo.FormState 216 217Called 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.) 218 219**System capability**: SystemCapability.Ability.Form 220 221**Parameters** 222 223| Name| Type| Mandatory| Description| 224| -------- | -------- | -------- | -------- | 225| want | [Want](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.| 226 227**Example** 228 229```ts 230import FormExtensionAbility from '@ohos.app.form.FormExtensionAbility'; 231import formInfo from '@ohos.app.form.formInfo'; 232import Want from '@ohos.app.ability.Want'; 233 234export default class MyFormExtensionAbility extends FormExtensionAbility { 235 onAcquireFormState(want: Want) { 236 console.log(`FormExtensionAbility onAcquireFormState, want: ${want}`); 237 return formInfo.FormState.UNKNOWN; 238 } 239}; 240``` 241