@ohos.app.form.formInfo (formInfo)(系统接口)

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

说明：

本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 当前页面仅包含本模块的系统接口，其他公共接口参见@ohos.app.form.formInfo (formInfo)。

导入模块

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

FormInfo

卡片配置信息。

系统能力： SystemCapability.Ability.Form

名称	类型	只读	可选	说明
previewImages18+	Array<number>	是	是	卡片预览图资源ID。 原子化服务API： 从API version 18开始，该接口支持在原子化服务中使用。 说明： 值为正整数的数组。
enableBlurBackground18+	boolean	是	是	卡片是否使用模糊背板。 - true：开启模糊背板。 - false：关闭模糊背板。
renderingMode18+	RenderingMode	是	是	卡片渲染模式。
resizable20+	boolean	是	是	表示是否可以拖拽卡片调整大小。调整值必须在该卡片或者同groupId卡片的supportDimensions配置列表中。 - true：可以调整大小。 - false：不可以调整大小。
groupId20+	string	是	是	表示一组卡片的共同id。多张卡片的groupId相同且resizable为true时，多张卡片的supportDimensions配置共享。例如，卡片A和B的groupId相同且resizable均为true，则卡片A可以调整为卡片A和B的supportDimensions配置中的任意尺寸。 推荐多张卡片功能相同且需要调整卡片尺寸时配置。
isTemplateForm23+	boolean	是	是	表示卡片是否是模板卡。 - true：是模板卡。 - false：不是模板卡。
isStandbySupported23+	boolean	是	是	卡片是否支持在灵动显示界面展示。 - true：支持灵动显示。 - false：不支持灵动显示。 模型约束： 此接口仅可在Stage模型下使用。
isStandbyAdapted23+	boolean	是	是	卡片是否已适配灵动显示规则。 - true：已适配灵动显示。 - false：未适配灵动显示。 模型约束： 此接口仅可在Stage模型下使用。
isPrivacySensitive23+	boolean	是	是	卡片是否是隐私敏感卡片。 - true：是隐私敏感卡片。 - false：不是隐私敏感卡片。 模型约束： 此接口仅可在Stage模型下使用。
isFontScaleFollowSystem	boolean	否	是	卡片的字体缩放是否跟随系统，默认值为true。 - true：字体缩放跟随系统。 - false：字体缩放不会跟随系统。 模型约束： 此接口仅可在Stage模型下使用。 起始版本： 26.0.0

FormParam

卡片参数枚举。

系统能力： SystemCapability.Ability.Form

名称	值	说明
DEVICE_ID_KEY	'ohos.extra.param.key.device_id'	设备标识。 系统接口： 此接口为系统接口。
THEME_KEY	'ohos.extra.param.key.form_is_theme'	主题标识。 系统接口： 此接口为系统接口。
FORM_MANAGER_SHOW_SINGLE_FORM 23+	'ohos.extra.param.key.form_manager_show_single_form'	打开卡片管理页是否只显示特定单张卡片 - true：表示只显示特定单张卡片。 - false：表示显示所有卡片。 系统接口： 此接口为系统接口。
TEMPLATE_FORM_DETAIL_ID23+	'ohos.extra.param.key.template_form_detail_id'	模板卡片id。 系统接口： 此接口为系统接口。
TEMPLATE_FORM_DATA23+	'ohos.extra.param.key.template_form_data'	模板卡片数据。 系统接口： 此接口为系统接口。
TEMPLATE_FORM_DISPLAY_NAME23+	'ohos.extra.param.key.template_form_display_name'	模板卡片显示名称。 系统接口： 此接口为系统接口。
TEMPLATE_FORM_DESCRIPTION23+	'ohos.extra.param.key.template_form_description'	模板卡片描述　　。 系统接口： 此接口为系统接口。
FORM_FONT_SIZE_SCALE_KEY	'ohos.extra.param.key.form_font_size_scale'	卡片字体大小缩放键值。 系统接口： 此接口为系统接口。 模型约束： 此接口仅可在Stage模型下使用。 起始版本： 26.0.0
FORM_FONT_WEIGHT_SCALE_KEY	'ohos.extra.param.key.form_font_weight_scale'	卡片字重缩放键值。 系统接口： 此接口为系统接口。 模型约束： 此接口仅可在Stage模型下使用。 起始版本： 26.0.0

FormUsageState¹¹⁺

卡片当前使用状态枚举。

系统能力： SystemCapability.Ability.Form

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

名称	值	说明
USED	0	表示卡片在使用中。
UNUSED	1	表示卡片未被使用。

RunningFormInfo¹⁰⁺

已添加的卡片信息，包括使用中的以及未使用的卡片。

系统能力： SystemCapability.Ability.Form

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

名称	类型	只读	可选	说明
hostBundleName	string	是	否	使用方卡片所属包的Bundle名称。
visibilityType	VisibilityType	是	否	卡片当前可见类型枚举。
formUsageState11+	FormUsageState	是	否	卡片当前使用状态枚举。默认值为FormUsageState.USED
formDescription11+	string	是	否	提供方卡片配置文件中的描述信息。
extraData12+	Record<string, Object>	是	是	卡片的额外数据。

formProviderFilter¹⁰⁺

卡片提供方信息。

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

系统能力： SystemCapability.Ability.Form

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

名称	类型	只读	可选	说明
bundleName	string	否	否	提供方卡片所属包的Bundle名称。
formName	string	否	是	卡片名称。
moduleName	string	否	是	卡片所属模块的模块名称。
abilityName	string	否	是	卡片所属的Ability名称。
isUnusedIncluded11+	boolean	否	是	是否包含未使用的卡片。 - true：包含未使用的卡片。 - false：不包含未使用的卡片。 默认值：false。

FormInfoFilter

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

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

系统能力： SystemCapability.Ability.Form

名称	类型	必填	说明
bundleName12+	string	否	选填，仅保留含bundleName与提供值相符的卡片信息，未填写时则不通过bundleName进行过滤。 系统接口： 此接口为系统接口。
supportedDimensions12+	Array<number>	否	选填，仅保留含supportedDimensions提供值相符的卡片信息，未填写时则不通过supportedDimensions进行过滤。 系统接口： 此接口为系统接口。 说明： 最大长度为9，数值取值范围[1, 9]的的整数的数组，数值5从API version 9开始支持，从API version 20开始废弃。 具体规格参考 formInfo.FormDimension。
supportedShapes12+	Array<number>	否	选填，仅保留含supportedShapes提供值相符的卡片信息，未填写时则不通过supportedShapes进行过滤。 系统接口： 此接口为系统接口。 说明： 只有1和2两个值。1代表方形，2代表圆形。

FormLocation¹²⁺

卡片当前位置枚举。

系统能力：SystemCapability.Ability.Form

名称	值	说明
OTHER	-1	表示卡片位于其他位置。
DESKTOP	0	表示卡片位于桌面。 原子化服务API： 从API version 20开始，该接口支持在原子化服务中使用。
FORM_CENTER	1	表示卡片位于桌面的卡片中心。 原子化服务API： 从API version 20开始，该接口支持在原子化服务中使用。
FORM_MANAGER	2	表示卡片位于桌面的卡片管理器。 原子化服务API： 从API version 20开始，该接口支持在原子化服务中使用。
NEGATIVE_SCREEN	3	表示卡片位于负一屏。 原子化服务API： 从API version 20开始，该接口支持在原子化服务中使用。
FORM_CENTER_NEGATIVE_SCREEN	4	表示卡片位于负一屏的服务中心。
FORM_MANAGER_NEGATIVE_SCREEN	5	表示卡片位于负一屏的卡片管理器。
SCREEN_LOCK	6	表示卡片位于锁屏。 原子化服务API： 从API version 20开始，该接口支持在原子化服务中使用。
AI_SUGGESTION	7	表示卡片位于AI智慧助手推荐区。 原子化服务API： 从API version 20开始，该接口支持在原子化服务中使用。
STANDBY23+	8	表示卡片位于灵动显示界面。 原子化服务API： 从API version 23开始，该接口支持在原子化服务中使用。 模型约束： 此接口仅可在Stage模型下使用。

PublishFormResult¹²⁺

发布卡片加桌结果。

系统能力： SystemCapability.Ability.Form

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

名称	类型	只读	可选	说明
code	PublishFormErrorCode	否	否	发布卡片加桌错误码。
message	string	否	否	设置卡片加桌结果返回信息。

PublishFormErrorCode¹²⁺

发布卡片加桌错误码枚举。

系统能力：SystemCapability.Ability.Form

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

名称	值	说明
SUCCESS	0	表示卡片加桌成功。
NO_SPACE	1	表示没有空间添加卡片。
PARAM_ERROR	2	表示参数检查失败。
INTERNAL_ERROR	3	表示卡片处理过程中出现内部错误。

RenderingMode¹⁸⁺

卡片支持的渲染模式枚举。

系统能力： SystemCapability.Ability.Form

名称	值	说明
AUTO_COLOR	0	表示自动模式。
FULL_COLOR	1	表示全色模式。
SINGLE_COLOR	2	表示单色模式。

OverflowRequest²⁰⁺

互动卡片动效请求信息。

系统能力： SystemCapability.Ability.Form

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

名称	类型	只读	可选	说明
formId	string	否	否	卡片id。
isOverflow	boolean	否	否	动效请求类型标记，true 表示互动卡片请求触发动效，false 表示互动卡片请求取消动效。
overflowInfo	formInfo.OverflowInfo	否	是	动效请求参数信息，包括动效时长（单位：ms）和动效区域（动效区域范围以卡片左上角为原点，单位为vp），默认值为空。

ChangeSceneAnimationStateRequest²⁰⁺

互动卡片状态切换请求信息。互动卡片状态分为激活态和非激活态，非激活态下，互动卡片同普通卡片一致；激活态下，互动卡片支持拉起卡片提供方所开发的LiveFormExtensionAbility进程，实现互动卡片动效。

系统能力： SystemCapability.Ability.Form

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

名称	类型	只读	可选	说明
formId	string	否	否	卡片id。
state	number	否	否	状态切换请求类型标记：1 表示请求切换为激活态，0 表示请求切换为非激活态。

FunInteractionParams²⁰⁺

趣味交互卡片配置参数。

系统能力： SystemCapability.Ability.Form

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

名称	类型	只读	可选	说明
abilityName	string	否	是	趣味交互场景 extensionAbility 名称，默认为空。
targetBundleName	string	否	否	趣味交互场景主包包名。
subBundleName	string	否	否	趣味交互场景趣味交互场景独立分包名。
keepStateDuration	number	否	是	趣味交互场景无交互时，激活态保持时长。默认值为10000，单位ms。取值为(0,60000]的整数，超过取值范围则取最大值60000。 说明： 在API版本26.0.0之前该字段为(0,10000]的整数，超过取值范围则取默认值10000。

SceneAnimationParams²⁰⁺

场景动效卡片配置参数。

系统能力： SystemCapability.Ability.Form

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

名称	类型	只读	可选	说明
abilityName	string	否	否	场景动效 extensionAbility 名称，如卡片提供方LiveFormExtensionAbility名称。
disabledDesktopBehaviors	string	否	是	支持的取值包括SWIPE_DESKTOP（滑动桌面）、PULL_DOWN_SEARCH（下拉全搜）、LONG_CLICK（长按）、DRAG（拖动）。可以取值一个或多个，不同行为通过 | 拼接，例如SWIPE_DESKTOP|PULL_DOWN_SEARCH。缺省表示不禁用任何行为。
triggerTypes	Array<SceneAnimationTriggerType>	否	是	场景动效卡片触发类型。 模型约束： 此接口仅可在Stage模型下使用。 起始版本： 26.0.0

GetFormRectInfoCallback²⁰⁺

type GetFormRectInfoCallback = (formId: string) => Promise<formInfo.Rect>

卡片位置、尺寸查询回调。使用Promise异步回调。

系统能力： SystemCapability.Ability.Form

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

参数：

参数名	类型	必填	说明
formId	string	是	卡片Id。

返回值：

类型	说明
Promise<formInfo.Rect>	Promise对象，返回卡片相对屏幕左上角的的位置信息和卡片尺寸信息。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
202	The application is not a system application.

示例：

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

// 卡片使用方需要对查询请求进行处理，计算并返回卡片尺寸、位置信息
let getFormRectInfoCallback: formInfo.GetFormRectInfoCallback =
  (formId: string): Promise<formInfo.Rect> => {
    return new Promise<formInfo.Rect>((resolve: Function) => {
      console.info(`formId is ${formId}`);
      let formRect: formInfo.Rect = {
        left: 0,
        top: 0,
        width: 0,
        height: 0
      };
      resolve(formRect);
    })
  };

TemplateFormDetailInfo²³⁺

模板卡对应的真实卡片信息。

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

系统能力： SystemCapability.Ability.Form

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

名称	类型	只读	可选	说明
bundleName	string	否	否	卡片所属包的Bundle名称。
moduleName	string	否	否	卡片所属模块的模块名称。
abilityName	string	否	否	卡片所属的Ability名称。
formName	string	否	否	卡片名称。
dimension	string	否	否	卡片规格
detailId	string	否	否	卡片信息id
displayName	string	否	否	卡片展示名称
description	string	否	否	卡片描述

TemplateFormDetailInfoCallback²³⁺

type TemplateFormDetailInfoCallback = (info: Array<TemplateFormDetailInfo>) => void

模板卡真实卡片信息回调。

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

系统能力： SystemCapability.Ability.Form

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

参数：

参数名	类型	必填	说明
info	Array<TemplateFormDetailInfo>	是	模板卡真实卡片信息。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
202	The application is not a system application.

示例：

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

let templateFormDetailInfoCallback: formInfo.TemplateFormDetailInfoCallback =
  (info: Array<formInfo.TemplateFormDetailInfo>): void => {
    console.info('template form detail info callback success.');
  };

PublishFormCrossBundleInfo²³⁺

跨应用加卡管控信息。

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

系统能力： SystemCapability.Ability.Form

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

名称	类型	只读	可选	说明
callerBundleName	string	否	否	跨应用加卡拉起方的Bundle名称。
targetBundleName	string	否	否	跨应用加卡被拉起方的Bundle名称。
targetTemplateFormDetailId	string	否	否	被添加的真实卡片信息id

PublishFormCrossBundleControlCallback²³⁺

type PublishFormCrossBundleControlCallback = (info: PublishFormCrossBundleInfo) => boolean

跨应用加卡管控回调。

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

系统能力： SystemCapability.Ability.Form

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

参数：

参数名	类型	必填	说明
info	PublishFormCrossBundleInfo	是	跨应用加卡管控信息。

返回值：

类型	说明
boolean	跨应用加卡管控结果。 - true：表示管控通过。 - false：表示管控未通过。

示例：

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

let publishFormCrossBundleControlCallback: formInfo.PublishFormCrossBundleControlCallback =
  (info: formInfo.PublishFormCrossBundleInfo): boolean => {
    console.info('publish form cross bundle info callback success.');
    return true;
  };

SceneAnimationTriggerType

场景动效卡片触发类型枚举。

起始版本： 26.0.0

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

系统能力： SystemCapability.Ability.Form

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

名称	值	说明
SHAKE	1	摇一摇。

GetWantParamsCallback

type GetWantParamsCallback = (formInfo: Array<FormInfo>) => Array<Record<string, Object>>

获取卡片参数回调。

起始版本： 26.0.0

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

系统能力： SystemCapability.Ability.Form

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

参数：

参数名	类型	必填	说明
formInfo	Array<FormInfo>	是	卡片信息列表。

返回值：

类型	说明
Array<Record<string, Object>>	返回卡片参数列表，与输入的卡片信息列表一一对应。

示例：

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

let getWantParamsCallback: formInfo.GetWantParamsCallback =
  (formInfo: Array<formInfo.FormInfo>): Array<Record<string, Object>> => {
    console.info('get want params callback, form count: ' + formInfo.length);
    let wantParamsList: Array<Record<string, Object>> = [];
    for (let i = 0; i < formInfo.length; i++) {
      let params: Record<string, Object> = {
        'key': 'value'
      };
      wantParamsList.push(params);
    }
    return wantParamsList;
  };