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