1# FormComponent 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## Required Permissions 14 15ohos.permission.REQUIRE_FORM 16 17 18## Child Components 19 20Not supported 21 22 23## APIs 24 25FormComponent(value: { 26 id: number; 27 name: string; 28 bundle: string; 29 ability: string; 30 module: string; 31 dimension?: FormDimension; 32 temporary?: boolean 33 }) 34 35Creates a **FormComponent** instance to display the provided widget. 36 37**Parameters** 38 39| Name | Type | Mandatory| Description | 40| --------- | ------------------------------- | ---- | ----------------------------------------------------------------------- | 41| id | number | Yes | Widget ID. Set this parameter to **0** for a new widget. | 42| name | string | Yes | Widget name. | 43| bundle | string | Yes | Bundle name of the widget. | 44| ability | string | Yes | Ability name of the widget. | 45| module | string | Yes | Module name of the widget. | 46| 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**| 47| temporary | boolean | No | Whether the widget is a temporary one. | 48 49## FormDimension 50 51| Name | Description | 52| -------------------------- | -------- | 53| Dimension_1_2 | 1 x 2 widget.| 54| Dimension_2_2 | 2 x 2 widget.| 55| Dimension_2_4 | 2 x 4 widget.| 56| Dimension_4_4 | 4 x 4 widget.| 57| Dimension_2_1<sup>9+</sup> | 2 x 1 widget.| 58 59## Attributes 60| Name | Type | Mandatory| Description | 61| ----------- | ----------------------------------------------------------------------------------------------------- | ---- | ----------------------------------------------------------------------- | 62| size | {<br>width?: [Length](ts-types.md#length),<br>height?: [Length](ts-types.md#length)<br>} | Yes | Size of the widget. | 63| moduleName | string | Yes | Module name of the widget. | 64| 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**| 65| allowUpdate | boolean | No | Whether to allow the widget to update.<br>Default value: **true** | 66| visibility | [Visibility](ts-appendix-enums.md#visibility) | No | Whether the widget is visible.<br>Default value: **Visible** | 67 68 69 70## Events 71 72| Name | Description | 73| ------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | 74| onAcquired(callback: (info: { id: number }) => void) | Triggered when a widget is obtained. This API returns the ID of the obtained widget. | 75| onError(callback: (info: { errcode: number, msg: string }) => void) | Triggered when an error occurs during component loading.<br>**errcode**: error code.<br>**msg**: error information. | 76| onRouter(callback: (info: any) => void) | Triggered when routing occurs for the widget. This API returns information in [routerEvent](../js-service-widget-ui/js-service-widget-syntax-hml.md#event-binding).| 77| onUninstall(callback: (info: { id: number }) => void) | Triggered when a widget is uninstalled. This API returns the ID of the uninstalled widget. | 78 79 80## Example 81 82```ts 83//card.ets 84@Entry 85@Component 86struct CardExample { 87 @State formId:number = 0; 88 build() { 89 Column() { 90 Text('this is a card') 91 .fontSize(50) 92 .fontWeight(FontWeight.Bold) 93 FormComponent({ 94 id:this.formId, 95 name:"Form1", 96 bundle:"com.example.cardexample", 97 ability:"FormAbility", 98 module:"entry", 99 dimension:FormDimension.Dimension_2_2, 100 temporary:false 101 }) 102 .allowUpdate(true) 103 .size({width:360,height:360}) 104 .visibility(Visibility.Visible) 105 .onAcquired((form)=>{ 106 console.log(`form info : ${JSON.stringify(form)}`); 107 this.formId = form.id; 108 }) 109 .onError((err)=>{ 110 console.log(`fail to add form, err: ${JSON.stringify(err)}`); 111 }) 112 113 } 114 .width('100%') 115 .height('100%') 116 } 117} 118``` 119 120 121
