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 9The **formInfo** module provides types and enums related to the widget information and state. 10 11> **NOTE** 12> 13> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. 14 15## Modules to Import 16 17```ts 18import { formInfo } from '@kit.FormKit'; 19``` 20 21## FormInfo 22 23Defines the widget information. 24 25**System capability**: SystemCapability.Ability.Form 26 27| Name | Type | Readable | Writable | Description | 28| ----------- | -------- | -------- | -------------------- | ------------------------------------------------------------ | 29| bundleName | string | Yes | No | Name of the bundle to which the widget belongs.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 30| moduleName | string | Yes | No | Name of the module to which the widget belongs.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 31| abilityName | string | Yes | No | Name of the ability to which the widget belongs.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 32| name | string | Yes | No | Widget name.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 33| displayName<sup>11+</sup> | string | Yes | No | Widget display name.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 34| displayNameId<sup>11+</sup> | number | Yes | No | ID of the widget name displayed during widget preview.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 35| description | string | Yes | No | Description of the widget.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 36| descriptionId<sup>10+</sup> | number | Yes | No | ID of the widget description.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 37| type | [FormType](#formtype) | Yes | No | Type of the widget. Currently, JS and ArkTS widgets are supported.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 38| jsComponentName | string | Yes | No | Name of the component used in the JS widget.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 39| colorMode<sup>(deprecated)</sup> | [ColorMode](#colormodedeprecated) | Yes | No | Color mode of the widget.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 40| isDefault | boolean | Yes | No | Whether the widget is the default one.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 41| updateEnabled | boolean | Yes | No | Whether the widget is updatable.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 42| formVisibleNotify | boolean | Yes | No | Whether to send a notification when the widget is visible.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 43| scheduledUpdateTime | string | Yes | No | Time when the widget was updated.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 44| formConfigAbility | string | Yes | No | Configuration ability of the widget, that is, the ability corresponding to the option in the selection box displayed when the widget is long pressed.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 45| updateDuration | number | Yes | No | Update period of the widget.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 46| defaultDimension | number | Yes | No | Widget specifications.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 47| supportDimensions | Array<number> | Yes | No | Dimensions supported by the widget. For details, see [FormDimension](#formdimension).<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 48| customizeData | Record\<string, string> | Yes | No | Custom data of the widget.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 49| isDynamic<sup>10+</sup> | boolean | Yes | No | Whether the widget is a dynamic widget.<br>ArkTS widgets are classified into dynamic and static widgets. JS widgets are all dynamic widgets.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 50| transparencyEnabled<sup>11+</sup> | boolean | Yes | No | Whether the widget supports the setting of the background transparency.<br>For ArkTS widgets, the support for the background transparency setting depends on user configurations. For JS widgets, the background transparency setting is not supported.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 51| supportedShapes<sup>12+</sup> | Array<number> | Yes | No | Shapes supported by the widget. For details about the available shapes, see [FormShape<sup>12+</sup>](#formshape12).<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 52 53## FormType 54 55Enumerates the widget types. 56 57**Atomic service API**: This API can be used in atomic services since API version 11. 58 59**System capability**: SystemCapability.Ability.Form 60 61| Name | Value | Description | 62| ----------- | ---- | ------------ | 63| JS | 1 | JS widget. | 64| eTS | 2 | ArkTS widget.| 65 66## ColorMode<sup>(deprecated)</sup> 67 68This API is supported since API version 11 and deprecated since API version 20. The color mode follows the system color mode. 69 70Enumerates the color modes supported by the widget. 71 72**Atomic service API**: This API can be used in atomic services since API version 11. 73 74**System capability**: SystemCapability.Ability.Form 75 76| Name | Value | Description | 77| ----------- | ---- | ------------ | 78| MODE_AUTO | -1 | Auto mode. | 79| MODE_DARK | 0 | Dark mode. | 80| MODE_LIGHT | 1 | Light mode. | 81 82## FormStateInfo 83 84Describes the widget state information. 85 86**Atomic service API**: This API can be used in atomic services since API version 11. 87 88**System capability**: SystemCapability.Ability.Form 89 90| Name | Type | Readable | Writable | Description | 91| ----------- | -------- | -------- | -------------------- | ------------------------------------------------------------ | 92| formState | [FormState](#formstate) | Yes | No | Widget state. | 93| want | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes | No | Want text. | 94 95## FormState 96 97Enumerates the widget states. 98 99**Atomic service API**: This API can be used in atomic services since API version 11. 100 101**System capability**: SystemCapability.Ability.Form 102 103| Name | Value | Description | 104| ----------- | ---- | ------------ | 105| UNKNOWN | -1 | Unknown state. | 106| DEFAULT | 0 | Default state. | 107| READY | 1 | Ready state. | 108 109## FormParam 110 111Enumerates the widget parameters. 112 113**System capability**: SystemCapability.Ability.Form 114 115| Name | Value | Description | 116| ----------- | ---- | ------------ | 117| IDENTITY_KEY | 'ohos.extra.param.key.form_identity' | Widget ID.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 118| DIMENSION_KEY | 'ohos.extra.param.key.form_dimension' | Widget dimension. For details, see [FormDimension](#formdimension).<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 119| NAME_KEY | 'ohos.extra.param.key.form_name' | Widget name.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 120| MODULE_NAME_KEY | 'ohos.extra.param.key.module_name' | Name of the module to which the widget belongs.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 121| WIDTH_KEY | 'ohos.extra.param.key.form_width' | Widget width.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 122| HEIGHT_KEY | 'ohos.extra.param.key.form_height' | Widget height.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 123| TEMPORARY_KEY | 'ohos.extra.param.key.form_temporary' | Temporary widget.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 124| ABILITY_NAME_KEY | 'ohos.extra.param.key.ability_name' | Ability name.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 125| BUNDLE_NAME_KEY | 'ohos.extra.param.key.bundle_name' | Bundle name.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 126| LAUNCH_REASON_KEY<sup>10+</sup> | 'ohos.extra.param.key.form_launch_reason' | Reason for creating the widget.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 127| PARAM_FORM_CUSTOMIZE_KEY<sup>10+</sup> | 'ohos.extra.param.key.form_customize' | Custom data.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 128| FORM_RENDERING_MODE_KEY<sup>11+</sup> | 'ohos.extra.param.key.form_rendering_mode' | Widget rendering mode.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 129| HOST_BG_INVERSE_COLOR_KEY<sup>12+</sup> | 'ohos.extra.param.key.host_bg_inverse_color' | Inverse background color of the widget client.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 130| FORM_LOCATION_KEY<sup>12+</sup> | 'ohos.extra.param.key.form_location' | Widget location.<br>OTHER -1 (Other locations)<br>DESKTOP 0 (Home screen)<br>FORM_CENTER 1 (Widget center of the home screen)<br>FORM_MANAGER 2 (Widget Manager of the home screen)<br>NEGATIVE_SCREEN 3 (Minus-one screen)<br>FORM_CENTER_NEGATIVE_SCREEN 4 (Widget center of the minus-one screen)<br>FORM_MANAGER_NEGATIVE_SCREEN 5 (Widget Manager of the minus-one screen)<br>SCREEN_LOCK 6 (Screen lock)<br>AI_SUGGESTION 7 (Celia suggestions area)| 131| FORM_PERMISSION_NAME_KEY<sup>12+</sup> | 'ohos.extra.param.key.permission_name' | Name of the permission.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 132| FORM_PERMISSION_GRANTED_KEY<sup>12+</sup> | 'ohos.extra.param.key.permission_granted' | Whether the permission is granted.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 133| ORIGINAL_FORM_KEY<sup>20+</sup> | 'ohos.extra.param.key.original_form_id' | Original widget ID. When a group of widgets associated by **groupId** is resized, new-sized widgets are created before old-sized widgets are deleted. When a new-sized widget is created, the old-sized widget ID is passed through this key in the **want** parameter.<br>**Atomic service API**: This API can be used in atomic services since API version 20.| 134 135## FormDimension 136 137Enumerates the widget dimensions. 138 139**System capability**: SystemCapability.Ability.Form 140 141| Name | Value | Description | 142| ----------- | ---- | ------------ | 143| Dimension_1_2 | 1 | 1 x 2.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 144| Dimension_2_2 | 2 | 2 x 2.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 145| Dimension_2_4 | 3 | 2 x 4.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 146| Dimension_4_4 | 4 | 4 x 4.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 147| Dimension_2_1<sup>(deprecated)</sup> | 5 | 2 x 1.<br>**Atomic service API**: This API can be used in atomic services since API version 11.<br>**Note**: This field is supported since API version 9 and deprecated since API version 20.| 148| DIMENSION_1_1<sup>11+<sup> | 6 | 1 x 1.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 149| DIMENSION_6_4<sup>12+<sup> | 7 | 6 x 4.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 150| DIMENSION_2_3<sup>18+<sup> | 8 | 2 x 3.<br>**Atomic service API**: This API can be used for wearable devices in atomic services since API version 18.| 151| DIMENSION_3_3<sup>18+<sup> | 9 | 3 x 3.<br>**Atomic service API**: This API can be used for wearable devices in atomic services since API version 18.| 152 153## FormShape<sup>12+</sup> 154 155Enumerates the widget shapes. 156 157**System capability**: SystemCapability.Ability.Form 158 159| Name | Value | Description | 160| ----------- | ---- | ------------ | 161| RECT | 1 | Rectangle.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 162| CIRCLE | 2 | Circle.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 163 164## FormInfoFilter 165 166Defines the widget information filter. Only the widget information that meets the filter is returned. 167 168**Atomic service API**: This API can be used in atomic services since API version 11. 169 170**System capability**: SystemCapability.Ability.Form 171 172| Name | Type | Mandatory |Description | 173| ----------- | ---- | ------------ |------------ | 174| moduleName | string |No | Only the information about the widget whose **moduleName** is the same as the provided value is returned.<br>If this parameter is not set, **moduleName** is not used for filtering. | 175 176 177 178## VisibilityType 179 180Enumerates the visibility types of the widget. 181 182**Atomic service API**: This API can be used in atomic services since API version 11. 183 184**System capability**: SystemCapability.Ability.Form 185 186| Name | Value | Description | 187| ----------- | ---- | ------------ | 188| UNKNOWN<sup>10+</sup> | 0 | The visibility type of the widget is unknown.| 189| FORM_VISIBLE | 1 | The widget is visible.| 190| FORM_INVISIBLE | 2 | The widget is invisible.| 191 192 193## LaunchReason<sup>10+</sup> 194 195Enumerates the reasons for creating a widget. 196 197**Atomic service API**: This API can be used in atomic services since API version 11. 198 199**System capability**: SystemCapability.Ability.Form 200 201| Name | Value | Description | 202| ----------- | ---- | ------------ | 203| FORM_DEFAULT | 1 | The widget is created by default.| 204| FORM_SHARE | 2 | The widget is created for sharing.| 205| FORM_SIZE_CHANGE<sup>20+<sup> | 3 | The widget is created due to dimension changes.<br>**Atomic service API**: This API can be used in atomic services since API version 20.| 206 207## OverflowInfo<sup>20+</sup> 208 209Describes the widget animation information. 210 211**Atomic service API**: This API can be used in atomic services since API version 20. 212 213**System capability**: SystemCapability.Ability.Form 214 215| Name| Type| Read-Only| Optional | Description | 216|-----|-----|------|-----|---------------------------------| 217| area | [Rect](#rect20) | No| No | Overflow animation area. The upper left corner of the widget is used as the origin, in vp. | 218| duration | number | No| No | Animation duration. The value is an integer greater than 0 and less than or equal to 3,500, in milliseconds.| 219| useDefaultAnimation | boolean | No| Yes | Whether to enable the default animation provided by the system when the interactive widget state is switched. The default value is **true**. The value **false** indicates the image is directly switched without animation, with the widget UI in the inactive state matching that in the active state during the switch.| 220 221## Rect<sup>20+</sup> 222 223Defines the common rectangular area information, including the widget position and animation area. 224 225**Atomic service API**: This API can be used in atomic services since API version 20. 226 227**System capability**: SystemCapability.Ability.Form 228 229| Name| Type| Read-Only| Optional | Description| 230|-----|-----|------|-----|-------| 231| left | number | No| No | X coordinate of the upper left vertex of the rectangle, in vp.| 232| top | number | No| No | Y coordinate of the upper left vertex of the rectangle, in vp.| 233| width | number | No| No | Width of the rectangle, in vp.| 234| height | number | No| No | Height of the rectangle, in vp.| 235## FormLocation<sup>20+</sup> 236 237Enumerates the widget locations. 238 239**System capability**: SystemCapability.Ability.Form 240 241| Name | Value | Description | 242| ---------------------------- | ---- | -------------------------------- | 243| DESKTOP | 0 | The widget is located on the home screen. | 244| FORM_CENTER | 1 | The widget is located in the widget center of the home screen. | 245| FORM_MANAGER | 2 | The widget is located in the Widget Manager of the home screen. | 246<!--RP1--><!--RP1End--> 247 248## RunningFormInfo<sup>20+</sup> 249 250Information about the widget that has been added to the home screen. 251 252**Atomic service API**: This API can be used in atomic services since API version 20. 253 254**System capability**: SystemCapability.Ability.Form 255 256| Name | Type | Readable | Writable | Description | 257| ----------- | -------- | -------- | -------------------- | ------------------------------------------------------------ | 258| formId | string | Yes | No | Widget ID. | 259| bundleName | string | Yes | No | Name of the bundle to which the widget provider belongs. | 260| moduleName | string | Yes | No | Name of the module to which the widget belongs. | 261| abilityName | string | Yes | No | Name of the ability to which the widget belongs. | 262| formName | string | Yes | No | Widget name. | 263| dimension | number | Yes | No | Widget dimension. For details about the values and meanings, see [FormDimension](#formdimension). | 264| formLocation | [FormLocation](#formlocation20)| Yes | No | Location of the widget. | 265