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.<br>                                                             |
60
61## FormDimension
62
63| Name                      | Description    |
64| -------------------------- | -------- |
65| Dimension_1_2              | 1 x 2 widget. |
66| Dimension_2_2              | 2 x 2 widget. |
67| Dimension_2_4              | 2 x 4 widget. |
68| Dimension_4_4              | 4 x 4 widget. |
69| Dimension_2_1<sup>9+</sup> | 2 x 1 widget. |
70| Dimension_1_1<sup>11+</sup> | 1 x 1 widget. |
71| Dimension_6_4<sup>12+</sup> | 6 x 4 widget. |
72
73## FormRenderingMode<sup>11+</sup>
74| Name                      | Description    |
75| -------------------------- | -------- |
76| FULL_COLOR                 | Full color mode.|
77| SINGLE_COLOR               | Single color mode.|
78
79## Attributes
80
81### size
82
83size(value: { width: number; height: number })
84
85Sets the size for the widget.
86
87**System API**: This is a system API.
88
89**System capability**: SystemCapability.ArkUI.ArkUI.Full
90
91**Parameters**
92
93| Name | Type                                                     | Mandatory | Description      |
94| ------ | --------------------------------------------------------- | ---- | ---------- |
95| value  | {<br>width?: number,<br>height?: number<br>} | Yes  | Width and height. |
96
97### moduleName
98
99moduleName(value: string)
100
101Sets the module name for the widget.
102
103**System API**: This is a system API.
104
105**System capability**: SystemCapability.ArkUI.ArkUI.Full
106
107**Parameters**
108
109| Name | Type  | Mandatory | Description          |
110| ------ | ------ | ---- | -------------- |
111| value  | string | Yes  | Module name of the widget. |
112
113### dimension
114
115dimension(value: FormDimension)
116
117Sets the dimensions for the widget. The 2 x 2, 4 x 4, and 4 x 2 options are available.
118
119**System API**: This is a system API.
120
121**System capability**: SystemCapability.ArkUI.ArkUI.Full
122
123**Parameters**
124
125| Name | Type                           | Mandatory | Description                                |
126| ------ | ------------------------------- | ---- | ------------------------------------ |
127| value  | [FormDimension](#formdimension) | Yes  | Dimensions of the widget.<br>Default value: **Dimension_2_2** |
128
129### allowUpdate
130
131allowUpdate(value: boolean)
132
133Sets whether to allow the widget to update.
134
135**System API**: This is a system API.
136
137**System capability**: SystemCapability.ArkUI.ArkUI.Full
138
139**Parameters**
140
141| Name | Type   | Mandatory | Description                               |
142| ------ | ------- | ---- | ----------------------------------- |
143| value  | boolean | Yes  | Whether to allow the widget to update.<br>Default value: **true** |
144
145### visibility
146
147visibility(value: Visibility)
148
149Sets whether the widget is visible.
150
151**System API**: This is a system API.
152
153**System capability**: SystemCapability.ArkUI.ArkUI.Full
154
155**Parameters**
156
157| Name | Type                                         | Mandatory | Description                                  |
158| ------ | --------------------------------------------- | ---- | -------------------------------------- |
159| value  | [Visibility](ts-appendix-enums.md#visibility) | Yes  | Whether the widget is visible.<br>Default value: **Visible** |
160
161## Events
162
163### onAcquired
164
165onAcquired(callback: Callback[\<FormCallbackInfo>](#formcallbackinfo12)): FormComponentAttribute
166
167Called when the widget is obtained.
168
169**System API**: This is a system API.
170
171**System capability**: SystemCapability.ArkUI.ArkUI.Full
172
173**Parameters**
174
175| Name | Type                               | Mandatory | Description      |
176| ------ | ----------------------------------- | ---- | ---------- |
177| Callback | [FormCallbackInfo](#formcallbackinfo12) | Yes  | Widget ID. |
178
179### onError
180
181onError(callback: (info: { errcode: number; msg: string }) => void)
182
183Called when an error occurs during component loading.
184
185**System API**: This is a system API.
186
187**System capability**: SystemCapability.ArkUI.ArkUI.Full
188
189**Parameters**
190
191| Name | Type                                                        | Mandatory | Description                                           |
192| ------ | ------------------------------------------------------------ | ---- | ----------------------------------------------- |
193| info   |  { errcode: number, msg: string } | Yes  | **errcode**: error code.<br>**msg**: error information. |
194
195### onRouter
196
197onRouter(callback: (info: any) =&gt; void)
198
199Called when routing occurs for the widget. This API returns information in [routerEvent](../js-service-widget-ui/js-service-widget-syntax-hml.md#event-binding).
200
201**System API**: This is a system API.
202
203**System capability**: SystemCapability.ArkUI.ArkUI.Full
204
205**Parameters**
206
207| Name | Type | Mandatory | Description                                                        |
208| ------ | ---- | ---- | ------------------------------------------------------------ |
209| info   | any  | Yes  | Information in [routerEvent](../js-service-widget-ui/js-service-widget-syntax-hml.md#event-binding). |
210
211### onUninstall
212
213onUninstall(callback: Callback[\<FormCallbackInfo>](#formcallbackinfo12)): FormComponentAttribute
214
215Called when the widget is uninstalled. This API returns the ID of the uninstalled widget.
216
217**System API**: This is a system API.
218
219**System capability**: SystemCapability.ArkUI.ArkUI.Full
220
221**Parameters**
222
223| Name | Type                               | Mandatory | Description      |
224| ------ | ----------------------------------- | ---- | ---------- |
225| Callback   | [FormCallbackInfo](#formcallbackinfo12) | Yes  | Widget ID. |
226
227
228## Example
229
230
231
232This example creates a 2 x 2 widget and registers event callbacks.
233```ts
234//card.ets
235@Entry
236@Component
237struct CardExample {
238  @State formId:string = '0';
239  build() {
240    Column() {
241      Text('this is a card')
242        .fontSize(50)
243        .fontWeight(FontWeight.Bold)
244      FormComponent({
245        id:this.formId,
246        name:"Form1",
247        bundle:"com.example.cardexample",
248        ability:"FormAbility",
249        module:"entry",
250        dimension:FormDimension.Dimension_2_2,
251        temporary:false
252      })
253        .allowUpdate(true)
254        .size({width:360,height:360})
255        .visibility(Visibility.Visible)
256        .onAcquired((form: FormCallbackInfo)=>{
257          console.log(`form info : ${JSON.stringify(form)}`);
258          // Invalid form id
259          if (form.id == -1) {
260            this.formId = form.idString;
261          } else {
262            this.formId = form.id.toString();
263          }
264        })
265        .onError((err)=>{
266          console.log(`fail to add form, err: ${JSON.stringify(err)}`);
267        })
268        .onUninstall((form: FormCallbackInfo)=>{
269          console.log(`uninstall form success : ${JSON.stringify(form)}`);
270          // Invalid form id
271          if (form.id == -1) {
272            this.formId = form.idString;
273          } else {
274            this.formId = form.id.toString();
275          }
276        })
277    }
278    .width('100%')
279    .height('100%')
280  }
281}
282```
283
284![Form](figures/form.png)
285