1# @ohos.app.form.formInfo (formInfo) (System API) 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> This topic describes only system APIs provided by the module. For details about its public APIs, see [@ohos.app.form.formInfo (formInfo)](./js-apis-app-form-formInfo.md). 15 16## Modules to Import 17 18```ts 19import { formInfo } from '@kit.FormKit'; 20``` 21 22## FormInfo 23 24Defines the widget information. 25 26**System capability**: SystemCapability.Ability.Form 27 28| Name | Type | Readable | Writable | Description | 29| ----------- | -------- | -------- | -------------------- | ------------------------------------------------------------ | 30| previewImages<sup>18+</sup> | Array<number> | Yes| No| Resource IDs of the preview images of the widget.<br>**Atomic service API**: This API can be used in atomic services since API version 18.| 31| enableBlurBackground<sup>18+</sup> | boolean | Yes | No | Whether the widget uses a blur background.| 32| renderingMode<sup>18+</sup>|[RenderingMode](./js-apis-app-form-formInfo-sys.md#renderingmode18)|Yes|No|Widget rendering mode.| 33| resizable<sup>20+</sup> | boolean | Yes | No | Whether the widget can be resized by dragging. The value must be in the **supportDimensions** configuration list of the widget or the widget with the same **groupId**.<br>**Atomic service API**: This API can be used in atomic services since API version 20.| 34| groupId<sup>20+</sup> | string | Yes | No | Common ID of a group of widgets. If the values of **groupId** of multiple widgets are the same and the value of **resizable** is **true**, the **supportDimensions** configuration of multiple widgets is shared. For example, if the **groupId** values of widgets A and B are the same and the **resizable** values are **true**, widget A can be adjusted to any size specified by **supportDimensions**.<br>It is recommended that this field be set when multiple widgets with the same functionality need to be resized.<br>**Atomic service API**: This API can be used in atomic services since API version 20.| 35 36 37## FormParam 38 39Enumerates the widget parameters. 40 41**System capability**: SystemCapability.Ability.Form 42 43| Name | Value | Description | 44| ----------- | ---- | ------------ | 45| DEVICE_ID_KEY | 'ohos.extra.param.key.device_id' | Device ID.<br>**System API**: This is a system API. | 46 47## FormUsageState 48 49Enumerates the usage statuses of widgets. 50 51**System capability**: SystemCapability.Ability.Form 52 53**System API**: This is a system API. 54 55| Name | Value | Description | 56| ----------- | ---- | ------------ | 57| USED<sup>11+</sup> | 0 | The widget is in use.| 58| UNUSED<sup>11+</sup> | 1 | The widget is not in use.| 59 60## RunningFormInfo<sup>10+</sup> 61 62Defines the information about an added widget, which can be either in use or not. 63 64**System capability**: SystemCapability.Ability.Form 65 66**System API**: This is a system API. 67 68| Name | Type | Readable | Writable | Description | 69| ----------- | -------- | -------- | -------------------- | ------------------------------------------------------------ | 70| hostBundleName | string | Yes | No | Name of the bundle to which the widget host belongs. | 71| visibilityType | [VisibilityType](js-apis-app-form-formInfo.md#visibilitytype) | Yes | No | Visibility types of the widget. | 72| formUsageState<sup>11+</sup> | [FormUsageState](#formusagestate) | Yes | No | Usage status of the widget. | 73| formDescription<sup>11+</sup> | string | Yes | No | Description in the widget configuration file of the provider. | 74 75## formProviderFilter<sup>10+</sup> 76 77Defines the information about the widget provider. 78 79**Model restriction**: This API can be used only in the stage model. 80 81**System capability**: SystemCapability.Ability.Form 82 83**System API**: This is a system API. 84 85| Name | Type | Readable | Writable | Description | 86| ----------- | -------- | -------- | -------------------- | ------------------------------------------------------------ | 87| bundleName | string | Yes | Yes | Name of the bundle to which the widget provider belongs. | 88| formName | string | Yes | Yes | Widget name. | 89| moduleName | string | Yes | Yes | Name of the module to which the widget belongs. | 90| abilityName | string | Yes | Yes | Name of the ability to which the widget belongs. | 91| isUnusedIncluded<sup>11+</sup> | boolean | Yes | Yes | Whether an unused widget is included.<br>- **true**: An unused widget is included.<br>- **false** (default): There is no unused widget.<br> | 92 93 94## FormInfoFilter 95 96Defines the widget information filter. Only the widget information that meets the filter is returned. 97 98**Atomic service API**: This API can be used in atomic services since API version 11. 99 100**System capability**: SystemCapability.Ability.Form 101 102| Name | Type | Mandatory |Description | 103| ----------- | ---- | ------------ |------------ | 104| bundleName | string |No | Only the widget information in which **bundleName** is the same as the provided value is returned. If this parameter is left unspecified, the widget information is not filtered by **bundleName**.<br>**System API**: This is a system API. | 105| supportedDimensions | Array\<number\> |No | Only the widget information in which **supportedDimensions** is the same as the provided value is returned. If this parameter is left unspecified, the widget information is not filtered by **supportedDimensions**.<br>**System API**: This is a system API. | 106| supportedShapes<sup>12+</sup> | Array\<number\> |No | Only the widget information in which **supportedShapes** is the same as the provided value is returned. If this parameter is left unspecified, the widget information is not filtered by **supportedShapes**.<br>**System API**: This is a system API. | 107 108## FormLocation<sup>12+</sup> 109 110Enumerates the widget locations. 111 112**System capability**: SystemCapability.Ability.Form 113 114| Name | Value | Description | 115| ---------------------------- | ---- | -------------------------------- | 116| OTHER | -1 | The widget is not located in any of the following defined positions. | 117| DESKTOP | 0 | The widget is located on the home screen. | 118| FORM_CENTER | 1 | The widget is located in the widget center of the home screen. | 119| FORM_MANAGER | 2 | The widget is located in the widget manager of the home screen. | 120| NEGATIVE_SCREEN | 3 | The widget is located on the minus 1 screen. | 121| FORM_CENTER_NEGATIVE_SCREEN | 4 | The widget is located in the service panel of the minus 1 screen. | 122| FORM_MANAGER_NEGATIVE_SCREEN | 5 | The widget is located in the widget manager of the minus 1 screen.| 123| SCREEN_LOCK | 6 | The widget is located on the locked screen. | 124| AI_SUGGESTION | 7 | The widget is located in the area of Celia Suggestions. | 125 126## PublishFormResult<sup>12+</sup> 127 128Describes the result for the operation of adding a widget to the home screen. 129 130**System capability**: SystemCapability.Ability.Form 131 132| Name | Type | Readable| Writable| Description | 133| ------- | --------------------------------------------- | ---- | ---- | -------------------------- | 134| code | [PublishFormErrorCode](#publishformerrorcode12) | Yes | No | Result code of the operation. | 135| message | string | Yes | No | Message returned for the operation.| 136 137## PublishFormErrorCode<sup>12+</sup> 138 139Enumerates the result codes that may be used for the operation of adding a widget to the home screen. 140 141**System capability**: SystemCapability.Ability.Form 142 143| Name | Value | Description | 144| -------------- | ---- | -------------------------------- | 145| SUCCESS | 0 | The widget is added to the home screen. | 146| NO_SPACE | 1 | There is no space for adding widgets. | 147| PARAM_ERROR | 2 | Parameter check fails. | 148| INTERNAL_ERROR | 3 | An internal error occurs during widget processing.| 149 150## RenderingMode<sup>18+</sup> 151 152Enumerates the rendering modes supported by the widget. 153 154**Atomic service API**: This API can be used in atomic services since API version 18. 155 156**System capability**: SystemCapability.Ability.Form 157 158| Name | Value | Description | 159| ----------- | ---- | ------------ | 160| AUTO_COLOR | 0 | Auto mode. | 161| FULL_COLOR | 1 | Full-color mode. | 162| SINGLE_COLOR | 2 | Single-color mode. | 163 164## OverflowRequest<sup>20+</sup> 165 166Defines the request for interactive widget animations. 167 168**System capability**: SystemCapability.Ability.Form 169 170**System API**: This is a system API. 171 172| Name| Type| Read-Only| Optional| Description| 173|-----|-----|----|----|-----| 174| formId | string | Yes | No | Widget ID.| 175| isOverflow | boolean | Yes | No | Animation request type. The value **true** indicates the interactive widget requests to trigger the animation; the value **false** indicates the interactive widget requests to cancel the animation.| 176| overflowInfo | [formInfo.OverflowInfo](js-apis-app-form-formInfo.md#overflowinfo20) | Yes| Yes| Animation request parameters, including the animation duration (unit: ms) and animation area (the upper left corner of the widget is used as the origin of the animation area, in vp). The default value is empty.| 177 178## ChangeSceneAnimationStateRequest<sup>20+</sup> 179 180Defines the request for switching the status of an interactive widget. An interactive widget can be in the active or inactive state. In the inactive state, the interactive widget is the same as a common widget. In the active state, the interactive widget can start the **LiveFormExtensionAbility** process developed by the widget host to implement interactive widget animations. 181 182**System capability**: SystemCapability.Ability.Form 183 184**System API**: This is a system API. 185 186| Name| Type| Read-Only| Optional| Description| 187|-----|-----|-----|-----|----------------------------------------| 188| formId | string | Yes| No| Widget ID. | 189| state | number | Yes| No| Status switching request type. The value **1** indicates that the switching request is activated, and the value **0** indicates that the switching request is deactivated.| 190 191## FunInteractionParams<sup>20+</sup> 192 193Defines the parameters for a fun-based widget. 194 195**System capability**: SystemCapability.Ability.Form 196 197**System API**: This is a system API. 198 199| Name| Type| Read-Only| Optional| Description | 200|-----|-----|----|-----|--------------------------------------------------------------------------------------------------------------------------------------| 201| abilityName | string | Yes | Yes | ExtensionAbility name of the interaction scenario. This parameter is left empty by default.| 202| targetBundleName | string | Yes | No | Bundle name. | 203| subBundleName | string | Yes | No | Sub-bundle name.| 204| keepStateDuration | number | Yes | Yes | Duration of the activated state when there is no interaction. The default value is **10000**, in ms. The value should be an integer within the range [0, 10000]. If the value exceeds this range, it defaults to 10000 milliseconds.| 205 206## SceneAnimationParams<sup>20+</sup> 207 208Defines the parameters for a scene-based widget. 209 210**System capability**: SystemCapability.Ability.Form 211 212**System API**: This is a system API. 213 214| Name| Type| Read-Only| Optional| Description | 215|-----|-----|------|----|-------------------------------------------------------------------------------------------------------------------------------------------------| 216| abilityName | string | Yes| No | ExtensionAbility name, for example, LiveFormExtensionAbility name of the widget provider. | 217| disabledDesktopBehaviors | string | Yes| Yes | The options are **SWIPE_DESKTOP**, **PULL_DOWN_SEARCH**, **LONG_CLICK**, and **DRAG**. You can select one or more options. Use a vertical bar (\|) in between| to concatenate two different operations, for example, SWIPE_DESKTOP\|PULL_DOWN_SEARCH| By default, no operation is disabled.| 218 219## GetFormRectInfoCallback<sup>20+</sup> 220 221### (formId: string) 222 223(formId: string): Promise<formInfo.Rect> 224 225Callback for querying the widget position and dimension. It uses a promise to return the result. 226 227**System capability**: SystemCapability.Ability.Form 228 229**System API**: This is a system API. 230 231**Parameters** 232 233| Name| Type| Mandatory| Description| 234|-----|-----|------|------------------| 235| formId | string | Yes| Widget ID.| 236 237**Returns** 238 239| Type| Description| 240| -------- | -------- | 241| Promise<[formInfo.Rect](js-apis-app-form-formInfo.md#rect20)> | Promise used to return the position and dimension of the widget relative to the upper left corner of the screen, in vp.| 242 243**Error codes** 244 245For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 246 247| ID| Error Message | 248|-------|-----------------------------------------------------------------------------------------------------------| 249| 202 | The application is not a system application. | 250 251**Example** 252 253```ts 254import { formInfo } from '@kit.FormKit'; 255 256// The widget host needs to process the request, and calculate and return the widget dimension and position information. 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