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 15## 导入模块 16 17```ts 18import { formInfo } from '@kit.FormKit'; 19``` 20 21## FormInfo 22 23卡片配置信息。 24 25**系统能力：** SystemCapability.Ability.Form 26 27| 名称 | 类型 | 可读 | 可写 | 说明 | 28| ----------- | -------- | -------- | -------------------- | ------------------------------------------------------------ | 29| bundleName | string | 是 | 否 | 卡片所属包的Bundle名称。 <br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 30| moduleName | string | 是 | 否 | 卡片所属模块的模块名称。 <br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 31| abilityName | string | 是 | 否 | 卡片所属的Ability名称。 <br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 32| name | string | 是 | 否 | 卡片名称。 <br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 33| displayName<sup>11+</sup> | string | 是 | 否 | 卡片展示名称。 <br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 34| displayNameId<sup>11+</sup> | number | 是 | 否 | 卡片预览时标识卡片名称的ID。 <br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 35| description | string | 是 | 否 | 卡片描述。 <br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 36| descriptionId<sup>10+</sup> | number | 是 | 否 | 卡片描述id。 <br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 37| type | [FormType](#formtype) | 是 | 否 | 卡片类型。当前支持JS卡片、ArkTS卡片。 <br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 38| jsComponentName | string | 是 | 否 | js卡片的组件名。 <br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 39| colorMode<sup>(deprecated)</sup> | [ColorMode](#colormodedeprecated) | 是 | 否 | 卡片颜色模式。 <br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 40| isDefault | boolean | 是 | 否 | 卡片是否是默认卡片。 <br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 41| updateEnabled | boolean | 是 | 否 | 卡片是否使能更新。 <br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 42| formVisibleNotify | boolean | 是 | 否 | 卡片是否使能可见通知。 <br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 43| scheduledUpdateTime | string | 是 | 否 | 卡片更新时间。 <br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 44| formConfigAbility | string | 是 | 否 | 卡片配置ability。指定长按卡片弹出的选择框内，编辑选项所对应的ability。 <br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 45| updateDuration | number | 是 | 否 | 卡片更新周期。 <br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 46| defaultDimension | number | 是 | 否 | 卡片规格 <br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 47| supportDimensions | Array<number> | 是 | 否 | 卡片支持的规格。具体可选规格参考[FormDimension](#formdimension) <br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 48| customizeData | Record\<string, string> | 是 | 否 | 卡片用户数据。 <br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 49| isDynamic<sup>10+</sup> | boolean | 是 | 否 | 卡片是否为动态卡片。<br/>仅ArkTS卡片区分动静态卡片，JS卡片均为动态卡片。 <br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 50| transparencyEnabled<sup>11+</sup> | boolean | 是 | 否 | 卡片是否支持设置背景透明度。<br/>ArkTS卡片由用户配置决定是否支持，JS卡片均不支持。 <br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 51| supportedShapes<sup>12+</sup> | Array<number> | 是 | 否 | 卡片支持的形状。具体可选形状参考[FormShape<sup>12+</sup>](#formshape12) <br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 52 53## FormType 54 55支持的卡片类型枚举。 56 57**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 58 59**系统能力：** SystemCapability.Ability.Form 60 61| 名称 | 值 | 说明 | 62| ----------- | ---- | ------------ | 63| JS | 1 | 卡片类型为JS。 | 64| eTS | 2 | 卡片类型为ArkTS。 | 65 66## ColorMode<sup>(deprecated)</sup> 67 68从API version 11开始支持，从API version 20开始废弃，卡片主题样式统一跟随系统的颜色模式。 69 70卡片支持的颜色模式枚举。 71 72**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 73 74**系统能力：** SystemCapability.Ability.Form 75 76| 名称 | 值 | 说明 | 77| ----------- | ---- | ------------ | 78| MODE_AUTO | -1 | 表示自动模式。 | 79| MODE_DARK | 0 | 表示暗色。 | 80| MODE_LIGHT | 1 | 表示亮色。 | 81 82## FormStateInfo 83 84卡片状态信息。 85 86**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 87 88**系统能力：** SystemCapability.Ability.Form 89 90| 名称 | 类型 | 可读 | 可写 | 说明 | 91| ----------- | -------- | -------- | -------------------- | ------------------------------------------------------------ | 92| formState | [FormState](#formstate) | 是 | 否 | 卡片状态。 | 93| want | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | 是 | 否 | Want文本内容。 | 94 95## FormState 96 97卡片状态枚举。 98 99**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 100 101**系统能力：** SystemCapability.Ability.Form 102 103| 名称 | 值 | 说明 | 104| ----------- | ---- | ------------ | 105| UNKNOWN | -1 | 表示未知状态。 | 106| DEFAULT | 0 | 表示默认状态。 | 107| READY | 1 | 表示就绪状态。 | 108 109## FormParam 110 111卡片参数枚举。 112 113**系统能力：** SystemCapability.Ability.Form 114 115| 名称 | 值 | 说明 | 116| ----------- | ---- | ------------ | 117| IDENTITY_KEY | 'ohos.extra.param.key.form_identity' | 卡片标识。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 118| DIMENSION_KEY | 'ohos.extra.param.key.form_dimension' | 卡片规格，规格尺寸参考[FormDimension](#formdimension)。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 119| NAME_KEY | 'ohos.extra.param.key.form_name' | 卡片名称。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 120| MODULE_NAME_KEY | 'ohos.extra.param.key.module_name' | 卡片所属模块名称。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 121| WIDTH_KEY | 'ohos.extra.param.key.form_width' | 卡片宽度。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 122| HEIGHT_KEY | 'ohos.extra.param.key.form_height' | 卡片高度。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 123| TEMPORARY_KEY | 'ohos.extra.param.key.form_temporary' | 临时卡片。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 124| ABILITY_NAME_KEY | 'ohos.extra.param.key.ability_name' | ability名称。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 125| BUNDLE_NAME_KEY | 'ohos.extra.param.key.bundle_name' | Bundle名称。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 126| LAUNCH_REASON_KEY<sup>10+</sup> | 'ohos.extra.param.key.form_launch_reason' | 卡片创建原因。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 127| PARAM_FORM_CUSTOMIZE_KEY<sup>10+</sup> | 'ohos.extra.param.key.form_customize' | 自定义数据。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 128| FORM_RENDERING_MODE_KEY<sup>11+</sup> | 'ohos.extra.param.key.form_rendering_mode' | 卡片渲染模式。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 129| HOST_BG_INVERSE_COLOR_KEY<sup>12+</sup> | 'ohos.extra.param.key.host_bg_inverse_color' | 卡片使用方的背景反色颜色值。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 130| FORM_LOCATION_KEY<sup>12+</sup> | 'ohos.extra.param.key.form_location' | 卡片位置。 <br>OTHER -1 （其他位置） <br>DESKTOP 0 （桌面） <br>FORM_CENTER 1 （桌面的卡片中心） <br>FORM_MANAGER 2 （桌面的卡片管理器） <br>NEGATIVE_SCREEN 3 （负一屏） <br>FORM_CENTER_NEGATIVE_SCREEN 4 （负一屏的服务中心） <br>FORM_MANAGER_NEGATIVE_SCREEN 5 （负一屏的卡片管理器） <br>SCREEN_LOCK 6 （锁屏） <br>AI_SUGGESTION 7 （小艺建议推荐区）| 131| FORM_PERMISSION_NAME_KEY<sup>12+</sup> | 'ohos.extra.param.key.permission_name' | 用户授权权限名称。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 132| FORM_PERMISSION_GRANTED_KEY<sup>12+</sup> | 'ohos.extra.param.key.permission_granted' | 用户是否授权。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 133| ORIGINAL_FORM_KEY<sup>20+</sup> | 'ohos.extra.param.key.original_form_id' | 用groupId关联的一组卡片，在调整大小时，会先创建新尺寸的卡片，再删除旧尺寸的卡片。新尺寸卡片创建时want参数会通过该key传递旧尺寸卡片的卡片id。<br/>**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 | 134 135## FormDimension 136 137定义卡片尺寸枚举。 138 139**系统能力：** SystemCapability.Ability.Form 140 141| 名称 | 值 | 说明 | 142| ----------- | ---- | ------------ | 143| Dimension_1_2 | 1 | 1 x 2 form。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 144| Dimension_2_2 | 2 | 2 x 2 form。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 145| Dimension_2_4 | 3 | 2 x 4 form。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 146| Dimension_4_4 | 4 | 4 x 4 form。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 147| Dimension_2_1<sup>(deprecated)</sup> | 5 | 2 x 1 form。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。<br>**说明：** 该字段从API version 9开始支持，从API version 20开始废弃。| 148| DIMENSION_1_1<sup>11+<sup> | 6 | 1 x 1 form。<br>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。<br>**说明：** 该尺寸仅在锁屏卡片上生效。| 149| DIMENSION_6_4<sup>12+<sup> | 7 | 6 x 4 form。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 150| DIMENSION_2_3<sup>18+<sup> | 8 | 2 x 3 form。<br>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。<br>**设备行为差异：** 该字段仅在Wearable上生效，在其他设备类型中无效果。| 151| DIMENSION_3_3<sup>18+<sup> | 9 | 3 x 3 form。<br>**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。<br>**设备行为差异：** 该字段仅在Wearable上生效，在其他设备类型中无效果。| 152 153## FormShape<sup>12+</sup> 154 155定义卡片形状枚举。 156 157**系统能力：** SystemCapability.Ability.Form 158 159| 名称 | 值 | 说明 | 160| ----------- | ---- | ------------ | 161| RECT | 1 | 方形 form。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 162| CIRCLE | 2 | 圆形 form。<br>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 163 164## FormInfoFilter 165 166卡片信息过滤器，仅将符合过滤器内要求的卡片信息返回。 167 168**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 169 170**系统能力：** SystemCapability.Ability.Form 171 172| 名称 | 类型 | 必填 |说明 | 173| ----------- | ---- | ------------ |------------ | 174| moduleName | string |否 | 选填，仅保留含moduleName与提供值相符的卡片信息，<br>未填写时则不通过moduleName进行过滤。 | 175 176 177 178## VisibilityType 179 180卡片当前可见类型枚举。 181 182**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 183 184**系统能力：** SystemCapability.Ability.Form 185 186| 名称 | 值 | 说明 | 187| ----------- | ---- | ------------ | 188| UNKNOWN<sup>10+</sup> | 0 | 表示卡片为未知。 | 189| FORM_VISIBLE | 1 | 表示卡片为可见。 | 190| FORM_INVISIBLE | 2 | 表示卡片为不可见。 | 191 192 193## LaunchReason<sup>10+</sup> 194 195卡片创建原因枚举。 196 197**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 198 199**系统能力：** SystemCapability.Ability.Form 200 201| 名称 | 值 | 说明 | 202| ----------- | ---- | ------------ | 203| FORM_DEFAULT | 1 | 表示卡片创建原因为默认创建。 | 204| FORM_SHARE | 2 | 表示卡片创建原因为共享创建。 | 205| FORM_SIZE_CHANGE<sup>20+<sup> | 3 | 表示卡片创建原因为尺寸变化。<br>**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 | 206 207## OverflowInfo<sup>20+</sup> 208 209互动卡片动效信息。 210 211**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 212 213**系统能力：** SystemCapability.Ability.Form 214 215| 名称 | 类型 | 只读 | 可选 | 说明 | 216|-----|-----|------|-----|---------------------------------| 217| area | [Rect](#rect20) | 否 | 否 | 描述互动卡片动效区域范围，以卡片左上角为原点，单位为vp。 | 218| duration | number | 否 | 否 | 互动卡片动效持续时长。取值为大于0、小于等于3500的整数，单位ms。 | 219| useDefaultAnimation | boolean | 否 | 是 | 互动卡片状态切换时是否启动系统提供的默认动效，默认为true。取值为false表示系统不提供切换动效，画面直接切换，适合切换时非激活态和激活态UI完全一致的场景。 | 220 221## Rect<sup>20+</sup> 222 223通用矩形区域信息。可用于描述卡片位置、互动卡片动效区域等信息。 224 225**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 226 227**系统能力：** SystemCapability.Ability.Form 228 229| 名称 | 类型 | 只读 | 可选 | 说明 | 230|-----|-----|------|-----|-------| 231| left | number | 否 | 否 | 描述矩形的左上角顶点的 x 坐标，单位：vp。| 232| top | number | 否 | 否 | 描述矩形的左上角顶点的 y 坐标，单位：vp。| 233| width | number | 否 | 否 | 描述矩形的宽度，单位：vp。| 234| height | number | 否 | 否 | 描述矩形的高度，单位：vp。| 235## FormLocation<sup>20+</sup> 236 237卡片当前位置枚举。 238 239**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 240 241**系统能力**：SystemCapability.Ability.Form 242 243| 名称 | 值 | 说明 | 244| ---------------------------- | ---- | -------------------------------- | 245| DESKTOP | 0 | 表示卡片位于桌面。 | 246| FORM_CENTER | 1 | 表示卡片位于桌面的卡片中心。 | 247| FORM_MANAGER | 2 | 表示卡片位于桌面的卡片管理器。 | 248<!--RP1--><!--RP1End--> 249 250## RunningFormInfo<sup>20+</sup> 251 252已经添加到桌面的卡片信息。 253 254**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 255 256**系统能力：** SystemCapability.Ability.Form 257 258| 名称 | 类型 | 可读 | 可写 | 说明 | 259| ----------- | -------- | -------- | -------------------- | ------------------------------------------------------------ | 260| formId | string | 是 | 否 | 卡片标识。 | 261| bundleName | string | 是 | 否 | 卡片提供方所属包的Bundle名称。 | 262| moduleName | string | 是 | 否 | 卡片所属模块的名称。 | 263| abilityName | string | 是 | 否 | 卡片所属的Ability名称。 | 264| formName | string | 是 | 否 | 卡片名称。 | 265| dimension | number | 是 | 否 | 卡片尺寸，取值及其对应含义请参考[FormDimension](#formdimension)。 | 266| formLocation | [FormLocation](#formlocation20)| 是 | 否 | 卡片位置信息。 |