1# FormComponent (System API) 2 3The **FormComponent** is used to display widgets. 4 5> **NOTE** 6> 7> - This component is supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. 8> 9> - This component is intended for the widget host. For details about the widget provider, see [JS Service Widget UI Components](../js-service-widget-ui/js-service-widget-file.md). 10> 11> - To use this component, you must have the system signature. 12> 13> - The APIs provided by this module are system APIs. 14 15## Required Permissions 16 17ohos.permission.REQUIRE_FORM, ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 18 19 20## Child Components 21 22Not supported 23 24 25## APIs 26 27FormComponent (value: FormInfo) 28 29Creates a **FormComponent** instance to display the provided widget. 30 31**Parameters** 32 33| Name | Type | Mandatory| Description | 34| --------- | ------------------------------- | ---- | ----------------------------------------------------------------------- | 35| value | [FormInfo](#forminfo12) | Yes | Widget information. | 36 37## FormInfo<sup>12+</sup> 38 39Provides the widget information. 40 41| Name | Type | Mandatory| Description | 42| --------- | ------------------------------- | ---- |-------| 43| id | number \| string | Yes | Widget ID. Set this parameter to **0** for a new widget.<br>**NOTE**<br>Different widget hosts cannot use the same ID.<br>If a widget host uses the same ID for two widgets, the one added later is displayed. | 44| name | string | Yes | Widget name. | 45| bundle | string | Yes | Bundle name of the widget. | 46| ability | string | Yes | Ability name of the widget. | 47| module | string | Yes | Module name of the widget. | 48| dimension | [FormDimension](#formdimension) | No | Dimensions of the widget. The widgets in the 2 x 2, 4 x 4, and 4 x 2 dimensions are supported.<br>Default value: **Dimension_2_2**| 49| temporary | boolean | No | Whether the widget is a temporary one. | 50| renderingMode | [FormRenderingMode](#formrenderingmode11) | No | Widget rendering mode. The options are as follows:<br>- **FULL_COLOR** (default): full color mode, where the widget framework does not change the widget effect, which means that the widget is displayed in the effect as you set it.<br>- **SINGLE_COLOR**: single color mode, where the widget framework sets the widget background to transparent. In this mode you need to set the widget style based on the best practices.<br>**NOTE**<br>If the system does not support unified rendering, the widget framework does not set the widget background to transparent in single color mode.| 51 52## FormCallbackInfo<sup>12+</sup> 53 54Represents the parameters for obtaining a widget ID (**formId**) when querying or uninstalling a widget. 55 56| Name | Type | Mandatory| Description | 57| --------- | ------------------------------- | ---- | ----------------------------------------------------------------------- | 58| id | number | Yes | Widget ID of the number type.<br>**NOTE**<br>If the obtained ID is **-1**, the ID is greater than or equal to 2^53. In this case, you need to use **idString** to obtain the ID. | 59| idString | string | Yes | Widget ID of the string type. | 60| isLocked<sup>18+</sup> |boolean | Yes | Whether the widget is [locked](../../apis-form-kit/js-apis-app-form-formHost-sys.md#updateformlockedstate18). The value **true** means that the widget is locked, and **false** means the opposite. | 61 62## FormDimension 63 64| Name | Description | 65| -------------------------- | -------- | 66| Dimension_1_2 | 1 x 2 widget.| 67| Dimension_2_2 | 2 x 2 widget.| 68| Dimension_2_4 | 2 x 4 widget.| 69| Dimension_4_4 | 4 x 4 widget.| 70| Dimension_2_1<sup>9+</sup> | 2 x 1 widget.| 71| Dimension_1_1<sup>11+</sup> | 1 x 1 widget.| 72| Dimension_6_4<sup>12+</sup> | 6 x 4 widget.| 73| Dimension_2_3<sup>18+</sup> | 2 x 3 widget. Available for wearable devices.| 74| Dimension_3_3<sup>18+</sup> | 3 x 3 widget. Available for wearable devices.| 75 76## FormRenderingMode<sup>11+</sup> 77| Name | Description | 78| -------------------------- | -------- | 79| FULL_COLOR | Full color mode.| 80| SINGLE_COLOR | Single color mode.| 81 82## Attributes 83 84### size 85 86size(value: { width: number; height: number }) 87 88Sets the size for the widget. 89 90**System API**: This is a system API. 91 92**System capability**: SystemCapability.ArkUI.ArkUI.Full 93 94**Parameters** 95 96| Name| Type | Mandatory| Description | 97| ------ | --------------------------------------------------------- | ---- | ---------- | 98| value | {<br>width?: number,<br>height?: number<br>} | Yes | Width and height.| 99 100### moduleName 101 102moduleName(value: string) 103 104Sets the module name for the widget. 105 106**System API**: This is a system API. 107 108**System capability**: SystemCapability.ArkUI.ArkUI.Full 109 110**Parameters** 111 112| Name| Type | Mandatory| Description | 113| ------ | ------ | ---- | -------------- | 114| value | string | Yes | Module name of the widget.| 115 116### dimension 117 118dimension(value: FormDimension) 119 120Sets the dimensions for the widget. The 2 x 2, 4 x 4, and 4 x 2 options are available. 121 122**System API**: This is a system API. 123 124**System capability**: SystemCapability.ArkUI.ArkUI.Full 125 126**Parameters** 127 128| Name| Type | Mandatory| Description | 129| ------ | ------------------------------- | ---- | ------------------------------------ | 130| value | [FormDimension](#formdimension) | Yes | Dimensions of the widget.<br>Default value: **Dimension_2_2**| 131 132### allowUpdate 133 134allowUpdate(value: boolean) 135 136Sets whether to allow the widget to update. 137 138**System API**: This is a system API. 139 140**System capability**: SystemCapability.ArkUI.ArkUI.Full 141 142**Parameters** 143 144| Name| Type | Mandatory| Description | 145| ------ | ------- | ---- | ----------------------------------- | 146| value | boolean | Yes | Whether to allow the widget to update.<br>Default value: **true**| 147 148### visibility 149 150visibility(value: Visibility) 151 152Sets whether the widget is visible. 153 154**System API**: This is a system API. 155 156**System capability**: SystemCapability.ArkUI.ArkUI.Full 157 158**Parameters** 159 160| Name| Type | Mandatory| Description | 161| ------ | --------------------------------------------- | ---- | -------------------------------------- | 162| value | [Visibility](ts-appendix-enums.md#visibility) | Yes | Whether the widget is visible.<br>Default value: **Visible**| 163 164## Events 165 166### onAcquired 167 168onAcquired(callback: Callback[\<FormCallbackInfo>](#formcallbackinfo12)): FormComponentAttribute 169 170Called when the widget is obtained. 171 172**System API**: This is a system API. 173 174**System capability**: SystemCapability.ArkUI.ArkUI.Full 175 176**Parameters** 177 178| Name| Type | Mandatory| Description | 179| ------ | ----------------------------------- | ---- | ---------- | 180| Callback | [FormCallbackInfo](#formcallbackinfo12) | Yes | Widget ID.| 181 182### onError 183 184onError(callback: (info: { errcode: number; msg: string }) => void) 185 186Called when an error occurs during component loading. 187 188**System API**: This is a system API. 189 190**System capability**: SystemCapability.ArkUI.ArkUI.Full 191 192**Parameters** 193 194| Name| Type | Mandatory| Description | 195| ------ | ------------------------------------------------------------ | ---- | ----------------------------------------------- | 196| info | { errcode: number, msg: string } | Yes | **errcode**: error code.<br>**msg**: error message.| 197 198### onRouter 199 200onRouter(callback: (info: any) => void) 201 202Called when routing occurs for the widget. This API returns information in [routerEvent](../js-service-widget-ui/js-service-widget-syntax-hml.md#event-binding). 203 204**System API**: This is a system API. 205 206**System capability**: SystemCapability.ArkUI.ArkUI.Full 207 208**Parameters** 209 210| Name| Type| Mandatory| Description | 211| ------ | ---- | ---- | ------------------------------------------------------------ | 212| info | any | Yes | Information in [routerEvent](../js-service-widget-ui/js-service-widget-syntax-hml.md#event-binding).| 213 214### onUninstall 215 216onUninstall(callback: Callback[\<FormCallbackInfo>](#formcallbackinfo12)): FormComponentAttribute 217 218Called when the widget is uninstalled. This API returns the ID of the uninstalled widget. 219 220**System API**: This is a system API. 221 222**System capability**: SystemCapability.ArkUI.ArkUI.Full 223 224**Parameters** 225 226| Name| Type | Mandatory| Description | 227| ------ | ----------------------------------- | ---- | ---------- | 228| Callback | [FormCallbackInfo](#formcallbackinfo12) | Yes | Widget ID.| 229 230 231## Example 232 233 234 235This example creates a 2 x 2 widget and registers event callbacks. 236```ts 237//card.ets 238@Entry 239@Component 240struct CardExample { 241 @State formId:string = '0'; 242 build() { 243 Column() { 244 Text('this is a card') 245 .fontSize(50) 246 .fontWeight(FontWeight.Bold) 247 FormComponent({ 248 id:this.formId, 249 name:"Form1", 250 bundle:"com.example.cardexample", 251 ability:"FormAbility", 252 module:"entry", 253 dimension:FormDimension.Dimension_2_2, 254 temporary:false 255 }) 256 .allowUpdate(true) 257 .size({width:360,height:360}) 258 .visibility(Visibility.Visible) 259 .onAcquired((form: FormCallbackInfo)=>{ 260 console.log(`form info : ${JSON.stringify(form)}`); 261 // Invalid form id 262 if (form.id == -1) { 263 this.formId = form.idString; 264 } else { 265 this.formId = form.id.toString(); 266 } 267 }) 268 .onError((err)=>{ 269 console.log(`fail to add form, err: ${JSON.stringify(err)}`); 270 }) 271 .onUninstall((form: FormCallbackInfo)=>{ 272 console.log(`uninstall form success : ${JSON.stringify(form)}`); 273 // Invalid form id 274 if (form.id == -1) { 275 this.formId = form.idString; 276 } else { 277 this.formId = form.id.toString(); 278 } 279 }) 280 } 281 .width('100%') 282 .height('100%') 283 } 284} 285``` 286 287 288
