@ohos.app.form.formInfo (formInfo)

formInfo模块提供了卡片信息和状态等相关类型和枚举。

说明：

本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

导入模块

import { formInfo } from '@kit.FormKit';

FormInfo

卡片配置信息。

系统能力： SystemCapability.Ability.Form

名称	类型	只读	可选	说明
bundleName	string	否	否	卡片所属包的Bundle名称。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
moduleName	string	否	否	卡片所属模块的模块名称。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
abilityName	string	否	否	卡片所属的Ability名称。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
name	string	否	否	卡片名称。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
displayName¹¹⁺	string	否	否	卡片展示名称。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
displayNameId¹¹⁺	number	否	否	卡片预览时标识卡片名称的ID。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。说明：数值为大于0小于2^32的整数。
description	string	否	否	卡片描述。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
descriptionId¹⁰⁺	number	否	否	卡片描述id。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。说明：数值为大于0小于2^32的整数。
type	FormType	否	否	卡片类型。当前支持JS卡片、ArkTS卡片。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
jsComponentName	string	否	否	js卡片的组件名。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
colorMode^(deprecated)	ColorMode	否	否	卡片颜色模式。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。说明：从API version 9开始支持，从API version 20开始废弃。应用卡片需要支持深浅色两种显示模式，无替代接口。
isDefault	boolean	否	否	卡片是否是默认卡片。 - true：默认卡片。 - false：非默认卡片。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
updateEnabled	boolean	否	否	卡片是否使能更新。 - true：表示支持周期性刷新。 - false：表示不支持周期性刷新。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
formVisibleNotify	boolean	否	否	卡片是否使能可见通知。 - true：通知卡片提供方可见状态变化。 - false：不通知卡片提供方可见状态变化。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
scheduledUpdateTime	string	否	否	卡片更新时间。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
formConfigAbility	string	否	否	卡片配置ability。指定长按卡片弹出的选择框内，编辑选项所对应的ability。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
updateDuration	number	否	否	卡片更新周期。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。说明：数值为[0, 336]的整数。
defaultDimension	number	否	否	卡片规格。具体可选规格参考FormDimension。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。说明：数值为[1, 9]的整数，数值5从API version 9开始支持，从API version 20开始废弃。
supportDimensions	Array<number>	否	否	卡片支持的规格。具体可选规格参考FormDimension。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。说明：最大长度为9，数值取值范围[1, 9]的整数的数组，数值5从API version 9开始支持，从API version 20开始废弃。
customizeData	Record<string, string>	否	否	卡片用户数据。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
isDynamic¹⁰⁺	boolean	否	否	卡片是否为动态卡片。仅ArkTS卡片区分动静态卡片，JS卡片均为动态卡片。 - true：为动态卡片。 - false：为静态卡片。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
transparencyEnabled¹¹⁺	boolean	否	否	卡片是否支持设置背景透明度。 ArkTS卡片由用户配置决定是否支持，JS卡片均不支持。 - true：表示是透明卡片。 - false：表示不是透明卡片。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
supportedShapes¹²⁺	Array<number>	否	否	卡片支持的形状。具体可选形状参考FormShape¹²⁺ 原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。说明： 1代表方形，2代表圆形。

FormType

支持的卡片类型枚举。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Ability.Form

名称	值	说明
JS	1	卡片类型为JS。
eTS	2	卡片类型为ArkTS。

ColorMode^(deprecated)

卡片主题样式统一跟随系统的颜色模式，卡片支持的颜色模式枚举。

说明：

从API version 9开始支持，从API version 20开始废弃。应用卡片需要支持深浅色两种显示模式，无替代接口。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Ability.Form

名称	值	说明
MODE_AUTO	-1	表示自动模式。
MODE_DARK	0	表示暗色。
MODE_LIGHT	1	表示亮色。

FormStateInfo

卡片状态信息。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Ability.Form

名称	类型	只读	可选	说明
formState	FormState	否	否	卡片状态。
want	Want	否	否	Want文本内容。

FormState

卡片状态枚举。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Ability.Form

名称	值	说明
UNKNOWN	-1	表示未知状态。
DEFAULT	0	表示默认状态。
READY	1	表示就绪状态。

FormParam

卡片参数枚举。

系统能力： SystemCapability.Ability.Form

名称	值	说明
IDENTITY_KEY	'ohos.extra.param.key.form_identity'	卡片标识。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
DIMENSION_KEY	'ohos.extra.param.key.form_dimension'	卡片规格，规格尺寸参考FormDimension。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
NAME_KEY	'ohos.extra.param.key.form_name'	卡片名称。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
MODULE_NAME_KEY	'ohos.extra.param.key.module_name'	卡片所属模块名称。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
WIDTH_KEY	'ohos.extra.param.key.form_width'	卡片宽度。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
HEIGHT_KEY	'ohos.extra.param.key.form_height'	卡片高度。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
TEMPORARY_KEY	'ohos.extra.param.key.form_temporary'	临时卡片。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
ABILITY_NAME_KEY	'ohos.extra.param.key.ability_name'	ability名称。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
BUNDLE_NAME_KEY	'ohos.extra.param.key.bundle_name'	Bundle名称。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
LAUNCH_REASON_KEY¹⁰⁺	'ohos.extra.param.key.form_launch_reason'	卡片创建原因。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
PARAM_FORM_CUSTOMIZE_KEY¹⁰⁺	'ohos.extra.param.key.form_customize'	自定义数据。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
FORM_RENDERING_MODE_KEY¹¹⁺	'ohos.extra.param.key.form_rendering_mode'	卡片渲染模式。原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。
HOST_BG_INVERSE_COLOR_KEY¹²⁺	'ohos.extra.param.key.host_bg_inverse_color'	卡片使用方的背景反色颜色值。原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。
FORM_LOCATION_KEY¹²⁺	'ohos.extra.param.key.form_location'	卡片位置。 OTHER -1 （其他位置） DESKTOP 0 （桌面） FORM_CENTER 1 （桌面的卡片中心） FORM_MANAGER 2 （桌面的卡片管理器） NEGATIVE_SCREEN 3 （负一屏） FORM_CENTER_NEGATIVE_SCREEN 4 （负一屏的服务中心） FORM_MANAGER_NEGATIVE_SCREEN 5 （负一屏的卡片管理器） SCREEN_LOCK 6 （锁屏） AI_SUGGESTION 7 （AI智慧助手推荐区） STANDBY 8 （待机屏保显示界面）
FORM_PERMISSION_NAME_KEY¹²⁺	'ohos.extra.param.key.permission_name'	用户授权权限名称。原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。
FORM_PERMISSION_GRANTED_KEY¹²⁺	'ohos.extra.param.key.permission_granted'	用户是否授权。原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。
ORIGINAL_FORM_KEY²⁰⁺	'ohos.extra.param.key.original_form_id'	用groupId关联的一组卡片，在调整大小时，会先创建新尺寸的卡片，再删除旧尺寸的卡片。新尺寸卡片创建时want参数会通过该key传递旧尺寸卡片的卡片id。原子化服务API：从API version 20开始，该接口支持在原子化服务中使用。
EDIT_FORM_KEY²²⁺	'ohos.extra.param.key.edit_form_id'	在半模态页面的卡片编辑中，通过onAddForm回调函数传递该key表示被编辑的卡片id，用来确保预览卡片与被编辑卡片信息同步。如果卡片onAddForm回调函数中携带了该key，则说明当前卡片为半模态页面中的预览卡片，需要基于被编辑卡片来筛选预览卡片内容。原子化服务API：从API version 22开始，该接口支持在原子化服务中使用。
UPDATE_FORM_REASON_KEY²⁴⁺	'ohos.extra.param.key.update_form_reason'	卡片更新的原因，请参考FormUpdateReason。原子化服务API：从API version 24开始，该接口支持在原子化服务中使用。模型约束：此接口仅可在Stage模型下使用。

FormDimension

定义卡片尺寸枚举。

系统能力： SystemCapability.Ability.Form

名称	值	说明
Dimension_1_2	1	1 x 2 form。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
Dimension_2_2	2	2 x 2 form。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
Dimension_2_4	3	2 x 4 form。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
Dimension_4_4	4	4 x 4 form。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。
Dimension_2_1^(deprecated)	5	2 x 1 form。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。说明：该字段从API version 9开始支持，从API version 20开始废弃。
DIMENSION_1_1¹¹⁺	6	1 x 1 form。原子化服务API：从API version 11开始，该接口支持在原子化服务中使用。说明：该尺寸仅在锁屏卡片上生效。
DIMENSION_6_4¹²⁺	7	6 x 4 form。原子化服务API：从API version 12开始，该接口支持在原子化服务中使用。
DIMENSION_2_3¹⁸⁺	8	2 x 3 form。原子化服务API：从API version 18开始，该接口支持在原子化服务中使用。设备行为差异：该字段仅在Wearable上生效，在其他设备类型中无效果。
DIMENSION_3_3¹⁸⁺	9	3 x 3 form。原子化服务API：从API version 18开始，该接口支持在原子化服务中使用。设备行为差异：该字段仅在Wearable上生效，在其他设备类型中无效果。

FormShape¹²⁺

定义卡片形状枚举。

原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Ability.Form

名称	值	说明
RECT	1	方形 form。
CIRCLE	2	圆形 form。

FormInfoFilter

卡片信息过滤器，仅将符合过滤器内要求的卡片信息返回。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Ability.Form

名称	类型	只读	可选	说明
moduleName	string	否	是	选填，仅保留含moduleName与提供值相符的卡片信息，未填写时则不通过moduleName进行过滤。

VisibilityType

卡片当前可见类型枚举。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Ability.Form

名称	值	说明
UNKNOWN¹⁰⁺	0	表示卡片为未知。
FORM_VISIBLE	1	表示卡片为可见。
FORM_INVISIBLE	2	表示卡片为不可见。

LaunchReason¹⁰⁺

卡片创建原因枚举。

原子化服务API： 从API version 11开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Ability.Form

名称	值	说明
FORM_DEFAULT	1	表示卡片创建原因为默认创建。
FORM_SHARE	2	表示卡片创建原因为共享创建。
FORM_SIZE_CHANGE²⁰⁺	3	表示卡片创建原因为尺寸变化。原子化服务API：从API version 20开始，该接口支持在原子化服务中使用。

FormUpdateReason²⁴⁺

卡片更新原因枚举。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.Ability.Form

原子化服务API： 从API version 24开始，该接口支持在原子化服务中使用。

名称	值	说明
UNKNOWN	-1	卡片更新的原因未知。
FORM_NODE_REUSE	0	卡片更新的原因是节点复用。

OverflowInfo²⁰⁺

互动卡片动效信息。

原子化服务API： 从API version 20开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Ability.Form

名称	类型	只读	可选	说明
area	Rect	否	否	描述互动卡片动效区域范围，以卡片左上角为原点。
duration	number	否	否	互动卡片动效持续时长，单位ms。取值为大于0的整数，针对三方应用，取值要求不大于3500，系统应用无此限制。
useDefaultAnimation	boolean	否	是	互动卡片状态切换时是否启动系统提供的默认动效，默认为true。 - true：表示系统提供默认切换动效。 - false：表示系统不提供切换动效，画面直接切换，适合切换时非激活态和激活态UI完全一致的场景。

Rect²⁰⁺

通用矩形区域信息。可用于描述卡片位置、互动卡片动效区域等信息。

原子化服务API： 从API version 20开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Ability.Form

名称	类型	只读	可选	说明
left	number	否	否	描述矩形的左上角顶点的 x 坐标，单位：vp，范围参考请求参数约束。
top	number	否	否	描述矩形的左上角顶点的 y 坐标，单位：vp，范围参考请求参数约束。
width	number	否	否	描述矩形的宽度，单位：vp，范围参考请求参数约束。
height	number	否	否	描述矩形的高度，单位：vp，范围参考请求参数约束。

FormLocation²⁰⁺

卡片当前位置枚举。

原子化服务API： 从API version 20开始，该接口支持在原子化服务中使用。

系统能力：SystemCapability.Ability.Form

名称	值	说明
DESKTOP	0	表示卡片位于桌面。
FORM_CENTER	1	表示卡片位于桌面的卡片中心。
FORM_MANAGER	2	表示卡片位于桌面的卡片管理器。

RunningFormInfo²⁰⁺

已经添加到桌面的卡片信息。

原子化服务API： 从API version 20开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Ability.Form

名称	类型	只读	可选	说明
formId	string	是	否	卡片标识。
bundleName	string	是	否	卡片提供方所属包的Bundle名称。
moduleName	string	是	否	卡片所属模块的名称。
abilityName	string	是	否	卡片所属的Ability名称。
formName	string	是	否	卡片名称。
dimension	number	是	否	卡片尺寸，取值及其对应含义请参考FormDimension。说明：取值范围[1, 9]的整数，数值5从API version 9开始支持，从API version 20开始废弃。
formLocation	FormLocation	是	否	卡片位置信息。

@ohos.app.form.formInfo (formInfo)

导入模块

FormInfo

FormType

ColorMode(deprecated)

FormStateInfo

FormState

FormParam

FormDimension

FormShape12+

FormInfoFilter

VisibilityType

LaunchReason10+

FormUpdateReason24+

OverflowInfo20+

Rect20+

FormLocation20+

RunningFormInfo20+

ColorMode^(deprecated)

FormShape¹²⁺

LaunchReason¹⁰⁺

FormUpdateReason²⁴⁺

OverflowInfo²⁰⁺

Rect²⁰⁺

FormLocation²⁰⁺

RunningFormInfo²⁰⁺