harmony 鸿蒙FormComponent (System API)

  • 2025-06-12
  • 浏览 (4)

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.

FormInfo12+

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.

FormCallbackInfo12+

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.

FormRenderingMode11+

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) =&gt; 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%')
  }
}

Form

你可能感兴趣的鸿蒙文章

harmony 鸿蒙ArcButton

harmony 鸿蒙ArcSlider

harmony 鸿蒙Chip

harmony 鸿蒙ChipGroup

harmony 鸿蒙ComposeListItem

harmony 鸿蒙ComposeTitleBar

harmony 鸿蒙advanced.Counter

harmony 鸿蒙Dialog Box (Dialog)

harmony 鸿蒙DialogV2

harmony 鸿蒙DownloadFileButton

0  赞
  • 所属分类： 后端技术
  • 本文标签：
  • 版权声明： 原创文章如转载，请注明本文链接: https://m.seaxiang.com/blog/nvFO3t
热门推荐
标签云
Linux Java Spring Spring Boot docker 大数据 前端 生活 maven golang 软件 spring cloud fintech mac vscode 其他 区块链 以太坊 V神 开发者 技术 股票 git greenplum 分布式事务 chrome mysql flink kafka 设计模式 原理 鸿蒙 seo
最新文章
本文目录