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