1# @ohos.app.form.formInfo (formInfo)(系统接口) 2<!--Kit: Form Kit--> 3<!--Subsystem: Ability--> 4<!--Owner: @cx983299475--> 5<!--Designer: @xueyulong--> 6<!--Tester: @chenmingze--> 7<!--Adviser: @Brilliantry_Rui--> 8 9formInfo模块提供了卡片信息和状态等相关类型和枚举。 10 11> **说明：** 12> 13> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 14> 当前页面仅包含本模块的系统接口，其他公共接口参见[@ohos.app.form.formInfo (formInfo)](./js-apis-app-form-formInfo.md)。 15 16## 导入模块 17 18```ts 19import { formInfo } from '@kit.FormKit'; 20``` 21 22## FormInfo 23 24卡片配置信息。 25 26**系统能力：** SystemCapability.Ability.Form 27 28| 名称 | 类型 | 可读 | 可写 | 说明 | 29| ----------- | -------- | -------- | -------------------- | ------------------------------------------------------------ | 30| previewImages<sup>18+</sup> | Array<number> | 是 | 否 | 卡片预览图资源ID。<br>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。| 31| enableBlurBackground<sup>18+</sup> | boolean | 是 | 否 | 卡片是否使用模糊背板。 | 32| renderingMode<sup>18+</sup>|[RenderingMode](./js-apis-app-form-formInfo-sys.md#renderingmode18)|是|否|卡片渲染模式。| 33| resizable<sup>20+</sup> | boolean | 是 | 否 | 表示是否可以拖拽卡片调整大小。调整值必须在该卡片或者同groupId卡片的supportDimensions配置列表中。<br>**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 | 34| groupId<sup>20+</sup> | string | 是 | 否 | 表示一组卡片的共同id。多张卡片的groupId相同且resizable为true时，多张卡片的supportDimensions配置共享。例如，卡片A和B的groupId相同且resizable均为true，则卡片A可以调整为卡片A和B的supportDimensions配置中的任意尺寸。<br>推荐多张卡片功能相同且需要调整卡片尺寸时配置。<br>**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 | 35 36 37## FormParam 38 39卡片参数枚举。 40 41**系统能力：** SystemCapability.Ability.Form 42 43| 名称 | 值 | 说明 | 44| ----------- | ---- | ------------ | 45| DEVICE_ID_KEY | 'ohos.extra.param.key.device_id' | 设备标识。 <br>**系统接口：** 此接口为系统接口。 | 46 47## FormUsageState 48 49卡片当前使用状态枚举。 50 51**系统能力：** SystemCapability.Ability.Form 52 53**系统接口：** 此接口为系统接口。 54 55| 名称 | 值 | 说明 | 56| ----------- | ---- | ------------ | 57| USED<sup>11+</sup> | 0 | 表示卡片在使用中。 | 58| UNUSED<sup>11+</sup> | 1 | 表示卡片未被使用。 | 59 60## RunningFormInfo<sup>10+</sup> 61 62已添加的卡片信息，包括使用中的以及未使用的卡片。 63 64**系统能力：** SystemCapability.Ability.Form 65 66**系统接口：** 此接口为系统接口。 67 68| 名称 | 类型 | 可读 | 可写 | 说明 | 69| ----------- | -------- | -------- | -------------------- | ------------------------------------------------------------ | 70| hostBundleName | string | 是 | 否 | 使用方卡片所属包的Bundle名称。 | 71| visibilityType | [VisibilityType](js-apis-app-form-formInfo.md#visibilitytype) | 是 | 否 | 卡片当前可见类型枚举。 | 72| formUsageState<sup>11+</sup> | [FormUsageState](#formusagestate) | 是 | 否 | 卡片当前使用状态枚举。 | 73| formDescription<sup>11+</sup> | string | 是 | 否 | 提供方卡片配置文件中的描述信息。 | 74 75## formProviderFilter<sup>10+</sup> 76 77卡片提供方信息。 78 79**模型约束：** 此接口仅可在Stage模型下使用。 80 81**系统能力：** SystemCapability.Ability.Form 82 83**系统接口：** 此接口为系统接口。 84 85| 名称 | 类型 | 可读 | 可写 | 说明 | 86| ----------- | -------- | -------- | -------------------- | ------------------------------------------------------------ | 87| bundleName | string | 是 | 是 | 提供方卡片所属包的Bundle名称。 | 88| formName | string | 是 | 是 | 卡片名称。 | 89| moduleName | string | 是 | 是 | 卡片所属模块的模块名称。 | 90| abilityName | string | 是 | 是 | 卡片所属的Ability名称。 | 91| isUnusedIncluded<sup>11+</sup> | boolean | 是 | 是 | 是否包含未使用的卡片。<br/>- true：包含未使用的卡片。<br/>- false：不包含未使用的卡片。<br/>默认值：false。 | 92 93 94## FormInfoFilter 95 96卡片信息过滤器，仅将符合过滤器内要求的卡片信息返回。 97 98**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 99 100**系统能力：** SystemCapability.Ability.Form 101 102| 名称 | 类型 | 必填 |说明 | 103| ----------- | ---- | ------------ |------------ | 104| bundleName | string |否 | 选填，仅保留含bundleName与提供值相符的卡片信息，未填写时则不通过bundleName进行过滤。<br>**系统接口：** 此接口为系统接口。 | 105| supportedDimensions | Array\<number\> |否 | 选填，仅保留含supportedDimensions提供值相符的卡片信息，未填写时则不通过supportedDimensions进行过滤。<br>**系统接口：** 此接口为系统接口。 | 106| supportedShapes<sup>12+</sup> | Array\<number\> |否 | 选填，仅保留含supportedShapes提供值相符的卡片信息，未填写时则不通过supportedShapes进行过滤。<br>**系统接口：** 此接口为系统接口。 | 107 108## FormLocation<sup>12+</sup> 109 110卡片当前位置枚举。 111 112**系统能力**：SystemCapability.Ability.Form 113 114| 名称 | 值 | 说明 | 115| ---------------------------- | ---- | -------------------------------- | 116| OTHER | -1 | 表示卡片位于其他位置。 | 117| DESKTOP | 0 | 表示卡片位于桌面。 | 118| FORM_CENTER | 1 | 表示卡片位于桌面的卡片中心。 | 119| FORM_MANAGER | 2 | 表示卡片位于桌面的卡片管理器。 | 120| NEGATIVE_SCREEN | 3 | 表示卡片位于负一屏。 | 121| FORM_CENTER_NEGATIVE_SCREEN | 4 | 表示卡片位于负一屏的服务中心。 | 122| FORM_MANAGER_NEGATIVE_SCREEN | 5 | 表示卡片位于负一屏的卡片管理器。 | 123| SCREEN_LOCK | 6 | 表示卡片位于锁屏。 | 124| AI_SUGGESTION | 7 | 表示卡片位于小艺建议推荐区。 | 125 126## PublishFormResult<sup>12+</sup> 127 128发布卡片加桌结果。 129 130**系统能力：** SystemCapability.Ability.Form 131 132| 名称 | 类型 | 可读 | 可写 | 说明 | 133| ------- | --------------------------------------------- | ---- | ---- | -------------------------- | 134| code | [PublishFormErrorCode](#publishformerrorcode12) | 是 | 否 | 发布卡片加桌错误码。 | 135| message | string | 是 | 否 | 设置卡片加桌结果返回信息。 | 136 137## PublishFormErrorCode<sup>12+</sup> 138 139发布卡片加桌错误码枚举。 140 141**系统能力**：SystemCapability.Ability.Form 142 143| 名称 | 值 | 说明 | 144| -------------- | ---- | -------------------------------- | 145| SUCCESS | 0 | 表示卡片加桌成功。 | 146| NO_SPACE | 1 | 表示没有空间添加卡片。 | 147| PARAM_ERROR | 2 | 表示参数检查失败。 | 148| INTERNAL_ERROR | 3 | 表示卡片处理过程中出现内部错误。 | 149 150## RenderingMode<sup>18+</sup> 151 152卡片支持的渲染模式枚举。 153 154**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 155 156**系统能力：** SystemCapability.Ability.Form 157 158| 名称 | 值 | 说明 | 159| ----------- | ---- | ------------ | 160| AUTO_COLOR | 0 | 表示自动模式。 | 161| FULL_COLOR | 1 | 表示全色模式。 | 162| SINGLE_COLOR | 2 | 表示单色模式。 | 163 164## OverflowRequest<sup>20+</sup> 165 166互动卡片动效请求信息。 167 168**系统能力：** SystemCapability.Ability.Form 169 170**系统接口：** 此接口为系统接口。 171 172| 名称 | 类型 | 只读 | 可选 | 说明 | 173|-----|-----|----|----|-----| 174| formId | string | 是 | 否 | 卡片id。| 175| isOverflow | boolean | 是 | 否 | 动效请求类型标记，true 表示互动卡片请求触发动效，false 表示互动卡片请求取消动效。| 176| overflowInfo | [formInfo.OverflowInfo](js-apis-app-form-formInfo.md#overflowinfo20) | 是 | 是 | 动效请求参数信息，包括动效时长（单位：ms）和动效区域（动效区域范围以卡片左上角为原点，单位为vp），默认值为空。 | 177 178## ChangeSceneAnimationStateRequest<sup>20+</sup> 179 180互动卡片状态切换请求信息。互动卡片状态分为激活态和非激活态，非激活态下，互动卡片同普通卡片一致；激活态下，互动卡片支持拉起卡片提供方所开发的LiveFormExtensionAbility进程，实现互动卡片动效。 181 182**系统能力：** SystemCapability.Ability.Form 183 184**系统接口：** 此接口为系统接口。 185 186| 名称 | 类型 | 只读 | 可选 | 说明 | 187|-----|-----|-----|-----|----------------------------------------| 188| formId | string | 是 | 否 | 卡片id。 | 189| state | number | 是 | 否 | 状态切换请求类型标记：1 表示请求切换为激活态，0 表示请求切换为非激活态。 | 190 191## FunInteractionParams<sup>20+</sup> 192 193趣味交互卡片配置参数。 194 195**系统能力：** SystemCapability.Ability.Form 196 197**系统接口：** 此接口为系统接口。 198 199| 名称 | 类型 | 只读 | 可选 | 说明 | 200|-----|-----|----|-----|--------------------------------------------------------------------------------------------------------------------------------------| 201| abilityName | string | 是 | 是 | 趣味交互场景 extensionAbility 名称，默认为空。 | 202| targetBundleName | string | 是 | 否 | 趣味交互场景[主包包名](https://developer.huawei.com/consumer/cn/doc/quickApp-Guides/quickgame-independent-subpackage-0000002076341729)。 | 203| subBundleName | string | 是 | 否 | 趣味交互场景趣味交互场景[独立分包名](https://developer.huawei.com/consumer/cn/doc/quickApp-Guides/quickgame-independent-subpackage-0000002076341729)。 | 204| keepStateDuration | number | 是 | 是 | 趣味交互场景无交互时，激活态保持时长。默认值为10000，单位ms。取值为[0,10000]的整数，超过取值范围则取默认值10000。 | 205 206## SceneAnimationParams<sup>20+</sup> 207 208场景动效卡片配置参数。 209 210**系统能力：** SystemCapability.Ability.Form 211 212**系统接口：** 此接口为系统接口。 213 214| 名称 | 类型 | 只读 | 可选 | 说明 | 215|-----|-----|------|----|-------------------------------------------------------------------------------------------------------------------------------------------------| 216| abilityName | string | 是 | 否 | 场景动效 extensionAbility 名称，如卡片提供方LiveFormExtensionAbility名称。 | 217| disabledDesktopBehaviors | string | 是 | 是 | 支持的取值包括SWIPE_DESKTOP（滑动桌面）、PULL_DOWN_SEARCH（下拉全搜）、LONG_CLICK（长按）、DRAG（拖动）。可以取值一个或多个，不同行为通过 \| 拼接，例如SWIPE_DESKTOP\|PULL_DOWN_SEARCH。缺省表示不禁用任何行为。 | 218 219## GetFormRectInfoCallback<sup>20+</sup> 220 221### (formId: string) 222 223(formId: string): Promise<formInfo.Rect> 224 225卡片位置、尺寸查询回调。使用Promise异步回调。 226 227**系统能力：** SystemCapability.Ability.Form 228 229**系统接口：** 此接口为系统接口。 230 231**参数：** 232 233| 参数名 | 类型 | 必填 | 说明 | 234|-----|-----|------|------------------| 235| formId | string | 是 | 卡片Id。| 236 237**返回值：** 238 239| 类型 | 说明 | 240| -------- | -------- | 241| Promise<[formInfo.Rect](js-apis-app-form-formInfo.md#rect20)> | Promise对象，返回卡片相对屏幕左上角的的位置信息和卡片尺寸信息，单位vp。 | 242 243**错误码：** 244 245以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 246 247| 错误码ID | 错误信息 | 248|-------|-----------------------------------------------------------------------------------------------------------| 249| 202 | The application is not a system application. | 250 251**示例：** 252 253```ts 254import { formInfo } from '@kit.FormKit'; 255 256// 卡片使用方需要对查询请求进行处理，计算并返回卡片尺寸、位置信息 257let getFormRectInfoCallback: formInfo.GetFormRectInfoCallback = 258 (formId: string): Promise<formInfo.Rect> => { 259 return new Promise<formInfo.Rect>((resolve: Function) => { 260 console.log(`formId is ${formId}`); 261 let formRect: formInfo.Rect = {left: 0, top: 0, width: 0, height: 0}; 262 resolve(formRect); 263 }) 264 }; 265``` 266