1# FormExtension 2 3>  **NOTE** 4> 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. 5 6Provides **FormExtension** APIs. 7 8## Modules to Import 9 10``` 11import FormExtension from '@ohos.application.FormExtension'; 12``` 13 14## Required Permissions 15 16None 17 18## Attributes 19 20**System capability**: SystemCapability.Ability.Form 21 22| Name | Type | Readable| Writable| Description | 23| ------- | ------------------------------------------------------- | ---- | ---- | --------------------------------------------------- | 24| context | [FormExtensionContext](js-apis-formextensioncontext.md) | Yes | No | Context of the **FormExtension**. This class is inherited from **ExtensionContext**.| 25 26## onCreate 27 28onCreate(want: Want): formBindingData.FormBindingData 29 30Called to notify the widget provider that a **Form** instance (widget) has been created. 31 32**System capability**: SystemCapability.Ability.Form 33 34**Parameters** 35 36 | Name| Type | Mandatory| Description | 37 | ------ | -------------------------------------- | ---- | ------------------------------------------------------------ | 38 | want | [Want](js-apis-featureAbility.md#want) | Yes | Information related to the extension, including the widget ID, name, and style. The information must be managed as persistent data to facilitate subsequent widget update and deletion.| 39 40**Return value** 41 42 | Type | Description | 43 | ------------------------------------------------------------ | ----------------------------------------------------------- | 44 | [formBindingData.FormBindingData](js-apis-formbindingdata.md#formbindingdata) | A **formBindingData.FormBindingData** object containing the data to be displayed on the widget.| 45 46**Example** 47 48 ```js 49 export default class MyFormExtension extends FormExtension { 50 onCreate(want) { 51 console.log('FormExtension onCreate, want:' + want.abilityName); 52 let dataObj1 = { 53 temperature:"11c", 54 "time":"11:00" 55 }; 56 let obj1 = formBindingData.createFormBindingData(dataObj1); 57 return obj1; 58 } 59 } 60 ``` 61 62## FormExtension.onCastToNormal 63 64onCastToNormal(formId: string): void 65 66Called to notify the widget provider that a temporary widget has been converted to a normal one. 67 68**System capability**: SystemCapability.Ability.Form 69 70**Parameters** 71 72 | Name| Type | Mandatory| Description | 73 | ------ | ------ | ---- | ------------------------ | 74 | formId | string | Yes | ID of the widget that requests to be converted to a normal one.| 75 76**Example** 77 78 ``` 79 export default class MyFormExtension extends FormExtension { 80 onCastToNormal(formId) { 81 console.log('FormExtension onCastToNormal, formId:' + formId); 82 } 83 } 84 ``` 85 86## FormExtension.onUpdate 87 88onUpdate(formId: string): void 89 90Called to notify the widget provider that a widget has been updated. After obtaining the latest data, the caller invokes **updateForm** of the [FormExtensionContext](js-apis-formextensioncontext.md) class to update the widget data. 91 92**System capability**: SystemCapability.Ability.Form 93 94**Parameters** 95 96 | Name| Type | Mandatory| Description | 97 | ------ | ------ | ---- | ------------------ | 98 | formId | string | Yes | ID of the widget that requests to be updated.| 99 100**Example** 101 102 ```js 103 export default class MyFormExtension extends FormExtension { 104 onUpdate(formId) { 105 console.log('FormExtension onUpdate, formId:' + formId); 106 let obj2 = formBindingData.createFormBindingData({temperature:"22c", time:"22:00"}); 107 this.context.updateForm(formId, obj2) 108 .then((data)=>{ 109 console.log('FormExtension context updateForm, data:' + data); 110 }).catch((error) => { 111 console.error('Operation updateForm failed. Cause: ' + error);}); 112 } 113 } 114 ``` 115 116## FormExtension.onVisibilityChange 117 118onVisibilityChange(newStatus: { [key: string]: number }): void 119 120Called to notify the widget provider of the change of visibility. 121 122**System capability**: SystemCapability.Ability.Form 123 124**Parameters** 125 126 | Name | Type | Mandatory| Description | 127 | --------- | ------------------------- | ---- | ---------------------------- | 128 | newStatus | { [key: string]: number } | Yes | ID and visibility status of the widget to be changed.| 129 130**Example** 131 132 ```js 133 export default class MyFormExtension extends FormExtension { 134 onVisibilityChange(newStatus) { 135 console.log('FormExtension onVisibilityChange, newStatus:' + newStatus); 136 let obj2 = formBindingData.createFormBindingData({temperature:"22c", time:"22:00"}); 137 138 for (let key in newStatus) { 139 console.log('FormExtension onVisibilityChange, key:' + key + ", value=" + newStatus[key]); 140 this.context.updateForm(key, obj2) 141 .then((data)=>{ 142 console.log('FormExtension context updateForm, data:' + data); 143 }).catch((error) => { 144 console.error('Operation updateForm failed. Cause: ' + error);}); 145 } 146 } 147 } 148 ``` 149 150## FormExtension.onEvent 151 152onEvent(formId: string, message: string): void 153 154Called to instruct the widget provider to receive and process the widget event. 155 156**System capability**: SystemCapability.Ability.Form 157 158**Parameters** 159 160 | Name | Type | Mandatory| Description | 161 | ------- | ------ | ---- | ---------------------- | 162 | formId | string | Yes | ID of the widget that requests the event.| 163 | message | string | Yes | Event message. | 164 165**Example** 166 167 ```js 168 export default class MyFormExtension extends FormExtension { 169 onEvent(formId, message) { 170 console.log('FormExtension onEvent, formId:' + formId + ", message:" + message); 171 } 172 } 173 ``` 174 175## FormExtension.onDestroy 176 177onDestroy(formId: string): void 178 179Called to notify the widget provider that a **Form** instance (widget) has been destroyed. 180 181**System capability**: SystemCapability.Ability.Form 182 183**Parameters** 184 185 | Name| Type | Mandatory| Description | 186 | ------ | ------ | ---- | ------------------ | 187 | formId | string | Yes | ID of the widget to be destroyed.| 188 189**Example** 190 191 ```js 192 export default class MyFormExtension extends FormExtension { 193 onDestroy(formId) { 194 console.log('FormExtension onDestroy, formId:' + formId); 195 } 196 } 197 ``` 198 199## FormExtension.onConfigurationUpdated 200 201onConfigurationUpdated(config: Configuration): void; 202 203Called when the configuration of the environment where the ability is running is updated. 204 205**System capability**: SystemCapability.Ability.Form 206 207**Parameters** 208 209 | Name| Type| Mandatory| Description| 210 | -------- | -------- | -------- | -------- | 211 | config | [Configuration](#section188911144124715) | Yes| New configuration.| 212 213**Example** 214 215 ```js 216 class MyFormExtension extends MyFormExtension { 217 onConfigurationUpdated(config) { 218 console.log('onConfigurationUpdated, config:' + JSON.stringify(config)); 219 } 220 } 221 ``` 222
