FormComponent (System API)

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.

• To use this component, you must have the system signature.

• The APIs provided by this module are system APIs.

Required Permissions

ohos.permission.REQUIRE_FORM, ohos.permission.GET_BUNDLE_INFO_PRIVILEGED

Child Components

Not supported

APIs

FormComponent (value: FormInfo)

Creates a FormComponent instance to display the provided widget.

Parameters

Name	Type	Mandatory	Description
value	FormInfo	Yes	Widget information.

FormInfo¹²⁺

Provides the widget information.

Name	Type	Mandatory	Description
id	number |string	Yes	Widget ID. Set this parameter to 0 for a new widget. NOTE Different widget hosts cannot use the same ID. If a widget host uses the same ID for two widgets, the one added later is displayed.
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	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.
renderingMode	FormRenderingMode	No	Widget rendering mode. The options are as follows: - 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. - 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. NOTE If the system does not support unified rendering, the widget framework does not set the widget background to transparent in single color mode.

FormCallbackInfo¹²⁺

Represents the parameters for obtaining a widget ID (formId) when querying or uninstalling a widget.

Name	Type	Mandatory	Description
id	number	Yes	Widget ID of the number type. NOTE 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.
idString	string	Yes	Widget ID of the string type.
isLocked18+	boolean	Yes	Whether the widget is locked. The value true means that the widget is locked, and false means the opposite.

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.
Dimension_1_111+	1 x 1 widget.
Dimension_6_412+	6 x 4 widget.
Dimension_2_318+	2 x 3 widget. Available for wearable devices.
Dimension_3_318+	3 x 3 widget. Available for wearable devices.

FormRenderingMode¹¹⁺

Name	Description
FULL_COLOR	Full color mode.
SINGLE_COLOR	Single color mode.

Attributes

size

size(value: { width: number; height: number })

Sets the size for the widget.

System API: This is a system API.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
value	{ width?: number, height?: number }	Yes	Width and height.

moduleName

moduleName(value: string)

Sets the module name for the widget.

System API: This is a system API.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
value	string	Yes	Module name of the widget.

dimension

dimension(value: FormDimension)

Sets the dimensions for the widget. The 2 x 2, 4 x 4, and 4 x 2 options are available.

System API: This is a system API.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
value	FormDimension	Yes	Dimensions of the widget. Default value: Dimension_2_2

allowUpdate

allowUpdate(value: boolean)

Sets whether to allow the widget to update.

System API: This is a system API.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
value	boolean	Yes	Whether to allow the widget to update. Default value: true

visibility

visibility(value: Visibility)

Sets whether the widget is visible.

System API: This is a system API.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
value	Visibility	Yes	Whether the widget is visible. Default value: Visible

Events

onAcquired

onAcquired(callback: Callback<FormCallbackInfo>): FormComponentAttribute

Called when the widget is obtained.

System API: This is a system API.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
Callback	FormCallbackInfo	Yes	Widget ID.

onError

onError(callback: (info: { errcode: number; msg: string }) => void)

Called when an error occurs during component loading.

System API: This is a system API.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
info	{ errcode: number, msg: string }	Yes	errcode: error code. msg: error message.

onRouter

onRouter(callback: (info: any) => void)

Called when routing occurs for the widget. This API returns information in routerEvent.

System API: This is a system API.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
info	any	Yes	Information in routerEvent.

onUninstall

onUninstall(callback: Callback<FormCallbackInfo>): FormComponentAttribute

Called when the widget is uninstalled. This API returns the ID of the uninstalled widget.

System API: This is a system API.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
Callback	FormCallbackInfo	Yes	Widget ID.

Example

This example creates a 2 x 2 widget and registers event callbacks.

//card.ets
@Entry
@Component
struct CardExample {
  @State formId:string = '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: FormCallbackInfo)=>{
          console.log(`form info : ${JSON.stringify(form)}`);
          // Invalid form id
          if (form.id == -1) {
            this.formId = form.idString;
          } else {
            this.formId = form.id.toString();
          }
        })
        .onError((err)=>{
          console.log(`fail to add form, err: ${JSON.stringify(err)}`);
        })
        .onUninstall((form: FormCallbackInfo)=>{
          console.log(`uninstall form success : ${JSON.stringify(form)}`);
          // Invalid form id
          if (form.id == -1) {
            this.formId = form.idString;
          } else {
            this.formId = form.id.toString();
          }
        })
    }
    .width('100%')
    .height('100%')
  }
}

你可能感兴趣的鸿蒙文章

harmony 鸿蒙ArcButton

harmony 鸿蒙ArcSlider

harmony 鸿蒙Chip

harmony 鸿蒙ChipGroup

harmony 鸿蒙ComposeListItem

harmony 鸿蒙ComposeTitleBar

harmony 鸿蒙advanced.Counter

harmony 鸿蒙Dialog Box (Dialog)

harmony 鸿蒙DialogV2

harmony 鸿蒙DownloadFileButton