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) has been created. 29 30**System capability**: SystemCapability.Ability.Form 31 32**Parameters** 33 34| Name| Type | Mandatory| Description | 35| ------ | -------------------------------------- | ---- | ------------------------------------------------------------ | 36| want | [Want](js-apis-application-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'; 49 50export default class MyFormExtensionAbility extends FormExtensionAbility { 51 onAddForm(want) { 52 console.log('FormExtensionAbility onAddForm, want:' + want.abilityName); 53 let dataObj1 = { 54 temperature:'11c', 55 'time':'11:00' 56 }; 57 let obj1 = formBindingData.createFormBindingData(dataObj1); 58 return obj1; 59 } 60} 61``` 62 63## onCastToNormalForm 64 65onCastToNormalForm(formId: string): void 66 67Called to notify the widget provider that a temporary widget has been converted to a normal one. 68 69**System capability**: SystemCapability.Ability.Form 70 71**Parameters** 72 73| Name| Type | Mandatory| Description | 74| ------ | ------ | ---- | ------------------------ | 75| formId | string | Yes | ID of the widget that requests to be converted to a normal one.| 76 77**Example** 78 79```ts 80export default class MyFormExtensionAbility extends FormExtensionAbility { 81 onCastToNormalForm(formId) { 82 console.log('FormExtensionAbility onCastToNormalForm, formId:' + formId); 83 } 84} 85``` 86 87## onUpdateForm 88 89onUpdateForm(formId: string): void 90 91Called to notify the widget provider that a widget has been updated. After obtaining the latest data, your application should call **updateForm** of [FormExtensionContext](js-apis-inner-application-formExtensionContext.md) to update the widget data. 92 93**System capability**: SystemCapability.Ability.Form 94 95**Parameters** 96 97| Name| Type | Mandatory| Description | 98| ------ | ------ | ---- | ------------------ | 99| formId | string | Yes | ID of the widget that requests to be updated.| 100 101**Example** 102 103```ts 104import formBindingData from '@ohos.app.form.formBindingData'; 105export default class MyFormExtensionAbility extends FormExtensionAbility { 106 onUpdateForm(formId) { 107 console.log('FormExtensionAbility onUpdateForm, formId:' + formId); 108 let obj2 = formBindingData.createFormBindingData({temperature:'22c', time:'22:00'}); 109 this.context.updateForm(formId, obj2).then((data)=>{ 110 console.log('FormExtensionAbility context updateForm, data:' + data); 111 }).catch((error) => { 112 console.error('Operation updateForm failed. Cause: ' + error);}); 113 } 114} 115``` 116 117## onChangeFormVisibility 118 119onChangeFormVisibility(newStatus: { [key: string]: number }): void 120 121Called to notify the widget provider of the change of visibility. 122 123**System capability**: SystemCapability.Ability.Form 124 125**Parameters** 126 127| Name | Type | Mandatory| Description | 128| --------- | ------------------------- | ---- | ---------------------------- | 129| newStatus | { [key: string]: number } | Yes | ID and visibility status of the widget to be changed.| 130 131**Example** 132 133```ts 134import formBindingData from '@ohos.app.form.formBindingData'; 135export default class MyFormExtensionAbility extends FormExtensionAbility { 136 onChangeFormVisibility(newStatus) { 137 console.log('FormExtensionAbility onChangeFormVisibility, newStatus:' + newStatus); 138 let obj2 = formBindingData.createFormBindingData({temperature:'22c', time:'22:00'}); 139 140 for (let key in newStatus) { 141 console.log('FormExtensionAbility onChangeFormVisibility, key:' + key + ', value=' + newStatus[key]); 142 this.context.updateForm(key, obj2).then((data)=>{ 143 console.log('FormExtensionAbility context updateForm, data:' + data); 144 }).catch((error) => { 145 console.error('Operation updateForm failed. Cause: ' + error);}); 146 } 147 } 148}; 149``` 150 151## onFormEvent 152 153onFormEvent(formId: string, message: string): void 154 155Called to instruct the widget provider to receive and process the widget event. 156 157**System capability**: SystemCapability.Ability.Form 158 159**Parameters** 160 161| Name | Type | Mandatory| Description | 162| ------- | ------ | ---- | ---------------------- | 163| formId | string | Yes | ID of the widget that requests the event.| 164| message | string | Yes | Event message. | 165 166**Example** 167 168```ts 169export default class MyFormExtension extends FormExtensionAbility { 170 onFormEvent(formId, message) { 171 console.log('FormExtensionAbility onFormEvent, formId:' + formId + ', message:' + message); 172 } 173} 174``` 175 176## onRemoveForm 177 178onRemoveForm(formId: string): void 179 180Called to notify the widget provider that a **Form** instance (widget) has been destroyed. 181 182**System capability**: SystemCapability.Ability.Form 183 184**Parameters** 185 186| Name| Type | Mandatory| Description | 187| ------ | ------ | ---- | ------------------ | 188| formId | string | Yes | ID of the widget to be destroyed.| 189 190**Example** 191 192```ts 193export default class MyFormExtensionAbility extends FormExtensionAbility { 194 onRemoveForm(formId) { 195 console.log('FormExtensionAbility onRemoveForm, formId:' + formId); 196 } 197} 198``` 199 200## onConfigurationUpdate 201 202onConfigurationUpdate(newConfig: Configuration): void; 203 204Called when the configuration of the environment where the ability is running is updated. 205 206**System capability**: SystemCapability.Ability.Form 207 208**Parameters** 209 210| Name| Type| Mandatory| Description| 211| -------- | -------- | -------- | -------- | 212| newConfig | [Configuration](js-apis-application-configuration.md) | Yes| New configuration.| 213 214**Example** 215 216```ts 217class MyFormExtensionAbility extends FormExtensionAbility { 218 onConfigurationUpdate(config) { 219 console.log('onConfigurationUpdate, config:' + JSON.stringify(config)); 220 } 221} 222``` 223 224## onAcquireFormState 225 226onAcquireFormState?(want: Want): formInfo.FormState; 227 228Called when the widget provider receives the status query result of a widget. By default, the initial state is returned. 229 230**System capability**: SystemCapability.Ability.Form 231 232**Parameters** 233 234| Name| Type| Mandatory| Description| 235| -------- | -------- | -------- | -------- | 236| want | [Want](js-apis-application-want.md) | Yes| Description of the widget state, including the bundle name, ability name, module name, widget name, and widget dimension.| 237 238**Example** 239 240```ts 241import formInfo from '@ohos.app.form.formInfo'; 242class MyFormExtensionAbility extends FormExtensionAbility { 243 onAcquireFormState(want) { 244 console.log('FormExtensionAbility onAcquireFormState, want:' + want); 245 return formInfo.FormState.UNKNOWN; 246 } 247} 248``` 249 250## onShareForm 251 252onShareForm?(formId: string): { [key: string]: Object } 253 254Called by the widget provider to receive shared widget data. 255 256**System API**: This is a system API. 257 258**System capability**: SystemCapability.Ability.Form 259 260**Parameters** 261 262| Name| Type| Mandatory| Description| 263| -------- | -------- | -------- | -------- | 264| formId | string | Yes | Widget ID.| 265 266**Return value** 267 268| Type | Description | 269| ------------------------------------------------------------ | ----------------------------------------------------------- | 270| {[key: string]: any} | Data to be shared by the widget, in the form of key-value pairs.| 271 272**Example** 273 274```ts 275class MyFormExtensionAbility extends FormExtensionAbility { 276 onShareForm(formId) { 277 console.log('FormExtensionAbility onShareForm, formId:' + formId); 278 let wantParams = { 279 'temperature':'20', 280 'time':'2022-8-8 09:59', 281 }; 282 return wantParams; 283 } 284} 285``` 286