diff --git a/en/application-dev/reference/arkui-ts/figures/form.png b/en/application-dev/reference/arkui-ts/figures/form.png new file mode 100644 index 0000000000000000000000000000000000000000..4586dc5b6e03f856e7c0e7c7a3158d12a574a1bf Binary files /dev/null and b/en/application-dev/reference/arkui-ts/figures/form.png differ diff --git a/en/application-dev/reference/arkui-ts/ts-basic-components-formcomponent.md b/en/application-dev/reference/arkui-ts/ts-basic-components-formcomponent.md new file mode 100644 index 0000000000000000000000000000000000000000..e641340a69dad32e2db89c55ba2d44911d3258b7 --- /dev/null +++ b/en/application-dev/reference/arkui-ts/ts-basic-components-formcomponent.md @@ -0,0 +1,124 @@ +# FormComponent + +The **FormComponent** is used to display widgets. + +> **NOTE** +> +> - This component is supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> +> - This component is intended for the widget host. For details about the widget provider, see [JS Service Widget UI Components](../js-service-widget-ui/Readme-EN.md). +> +> - To use this component, you must have the system signature. + +## Required Permissions + +ohos.permission.GET_BUNDLE_INFO + +ohos.permission.GET_BUNDLE_INFO_PRIVILEGED + +ohos.permission.REQUIRE_FORM + + +## Child Components + +Not supported + + +## APIs + +FormComponent(value: { + id: number; + name: string; + bundle: string; + ability: string; + module: string; + dimension?: FormDimension; + temporary?: boolean + }) + +Creates a **FormComponent** instance to display the provided widget. + +**Parameters** + +| Name | Type | Mandatory| Description | +| --------- | ------------------------------- | ---- | ----------------------------------------------------------------------- | +| id | number | Yes | Widget ID. Set this parameter to **0** for a new widget. | +| name | string | Yes | Widget name. | +| bundle | string | Yes | Bundle name of the widget. | +| ability | string | Yes | Ability name of the widget. | +| module | string | Yes | Module name of the widget. | +| 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.
Default value: **Dimension_2_2**| +| temporary | boolean | No | Whether the widget is a temporary one. | + +## FormDimension + +| Name | Description | +| -------------------------- | -------- | +| Dimension_1_2 | 1 x 2 widget.| +| Dimension_2_2 | 2 x 2 widget.| +| Dimension_2_4 | 2 x 4 widget.| +| Dimension_4_4 | 4 x 4 widget.| +| Dimension_2_19+ | 2 x 1 widget.| + +## Attributes +| Name | Type | Mandatory| Description | +| ----------- | ----------------------------------------------------------------------------------------------------- | ---- | ----------------------------------------------------------------------- | +| size | {
width?: [Length](ts-types.md#length),
height?: [Length](ts-types.md#length)
} | Yes | Size of the widget. | +| moduleName | string | Yes | Module name of the widget. | +| 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.
Default value: **Dimension_2_2**| +| allowUpdate | boolean | No | Whether to allow the widget to update.
Default value: **true** | +| visibility | [Visibility](ts-appendix-enums.md#visibility) | No | Whether the widget is visible.
Default value: **Visible** | + + + +## Events + +| Name | Description | +| ------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | +| onAcquired(callback: (info: { id: number }) => void) | Triggered when a widget is obtained. This API returns the ID of the obtained widget. | +| onError(callback: (info: { errcode: number, msg: string }) => void) | Triggered when an error occurs during component loading.
**errcode**: error code.
**msg**: error information. | +| 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).| +| onUninstall(callback: (info: { id: number }) => void) | Triggered when a widget is uninstalled. This API returns the ID of the uninstalled widget. | + + +## Example + +```ts +//card.ets +@Entry +@Component +struct CardExample { + @State formId:number = 0; + build() { + Column() { + Text('this is a card') + .fontSize(50) + .fontWeight(FontWeight.Bold) + FormComponent({ + id:this.formId, + name:"Form1", + bundle:"com.example.cardexample", + ability:"FormAbility", + module:"entry", + dimension:FormDimension.Dimension_2_2, + temporary:false + }) + .allowUpdate(true) + .size({width:360,height:360}) + .visibility(Visibility.Visible) + .onAcquired((form)=>{ + console.log(`form info : ${JSON.stringify(form)}`); + this.fomId = form.id; + }) + .onError((err)=>{ + console.log(`fail to add form, err: ${JSON.stringify(err)}`); + }) + + } + .width('100%') + .height('100%') + } +} +``` + +![Form](figures/form.png)