FormComponent (系统接口)

提供卡片组件，实现卡片的显示功能。

说明：

• 该组件从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。

• 该组件为卡片组件的使用方，对应提供方的使用参考文档JS服务卡片UI组件。

• 该组件使用需要具有系统签名。

• 本模块为系统接口。

权限

ohos.permission.REQUIRE_FORM, ohos.permission.GET_BUNDLE_INFO_PRIVILEGED

子组件

无

接口

FormComponent (value: FormInfo)

创建卡片组件，用于显示提供的卡片。

参数：

参数名	参数类型	必填	参数描述
value	FormInfo	是	卡片信息。

FormInfo¹²⁺

卡片信息。

参数名	参数类型	必填	参数描述
id	number | string	是	卡片标识（新建卡片填0）。 说明： 不同使用方不可使用相同id。 同一使用方使用相同id时，显示后添加的卡片。
name	string	是	卡片名称。
bundle	string	是	目标卡片包名。
ability	string	是	目标卡片Ability名称。
module	string	是	卡片模块名称。
dimension	FormDimension	否	卡片尺寸，支持2 * 2，4 * 4，4 * 2类型卡片。 默认值：Dimension_2_2。
temporary	boolean	否	卡片是否为临时卡片。
renderingMode	FormRenderingMode	否	卡片渲染模式。取值如下，默认值为 FULL_COLOR。 - FULL_COLOR：代表全色模式，卡片框架不会对卡片效果做出修改，保持和卡片开发者设置的效果不变。 - SINGLE_COLOR：代表单色模式，卡片框架会把卡片背景设为透明，开发者需按最佳实践设置卡片风格。 说明： 如果系统不支持统一渲染模式，卡片框架在单色模式下也不会把卡片背景设为透明。

FormCallbackInfo¹²⁺

卡片查询或者卸载时获取formId的参数。

参数名	参数类型	必填	参数描述
id	number	是	卡片标识（number类型）。 说明： 如果获取到的id为-1，说明id大于等于2^53，需要使用idString获取。
idString	string	是	卡片标识（string类型）。
isLocked18+	boolean	是	标识卡片是否为管控状态，true表示管控状态，false表示非管控状态。

FormDimension

名称	描述
Dimension_1_2	1*2 卡片
Dimension_2_2	2*2 卡片
Dimension_2_4	2*4 卡片
Dimension_4_4	4*4 卡片
Dimension_2_19+	2*1 卡片
Dimension_1_111+	1*1 卡片
Dimension_6_412+	6*4 卡片
Dimension_2_318+	2*3 卡片为穿戴设备使用
Dimension_3_318+	3*3 卡片为穿戴设备使用

FormRenderingMode¹¹⁺

名称	描述
FULL_COLOR	全色模式。
SINGLE_COLOR	单色模式。

属性

size

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

设置高宽尺寸。

系统接口： 此接口为系统接口。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	{ width?: number, height?: number }	是	宽高尺寸。

moduleName

moduleName(value: string)

设置卡片模块名称。

系统接口： 此接口为系统接口。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	string	是	卡片模块名称。

dimension

dimension(value: FormDimension)

设置卡片尺寸，支持2 * 2，4 * 4，4 * 2类型卡片。

系统接口： 此接口为系统接口。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	FormDimension	是	卡片尺寸。 默认值：Dimension_2_2

allowUpdate

allowUpdate(value: boolean)

设置是否允许卡片更新。

系统接口： 此接口为系统接口。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	boolean	是	是否允许卡片更新。 默认值：true

visibility

visibility(value: Visibility)

设置是否允许卡片可见。

系统接口： 此接口为系统接口。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	Visibility	是	是否允许卡片可见。 默认值：Visible

事件

onAcquired

onAcquired(callback: Callback<FormCallbackInfo>): FormComponentAttribute

获取到卡片后触发，返回卡片的id。

系统接口： 此接口为系统接口。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
Callback	FormCallbackInfo	是	卡片的id。

onError

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

组件加载错误回调。

系统接口： 此接口为系统接口。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
info	{ errcode: number, msg: string }	是	errcode: 错误码。 msg: 错误信息。

onRouter

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

组件路由事件回调，返回routerEvent中的信息。

系统接口： 此接口为系统接口。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
info	any	是	routerEvent中的信息。

onUninstall

onUninstall(callback: Callback<FormCallbackInfo>): FormComponentAttribute

组件卸载回调，返回卸载卡片的id。

系统接口： 此接口为系统接口。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
Callback	FormCallbackInfo	是	卡片的id。

示例

卡片示例。

该示例创建一张2 * 2尺寸大小的卡片，并注册事件回调。

//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%')
  }
}