1# @ohos.app.form.formInfo (formInfo) (System API)
2
3The **formInfo** module provides types and enums related to the widget information and state.
4
5> **NOTE**
6>
7> 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.
8> 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).
9
10## Modules to Import
11
12```ts
13import { formInfo } from '@kit.FormKit';
14```
15
16
17##  FormParam
18
19Enumerates the widget parameters.
20
21**System capability**: SystemCapability.Ability.Form
22
23| Name       | Value  | Description        |
24| ----------- | ---- | ------------ |
25| DEVICE_ID_KEY    | 'ohos.extra.param.key.device_id'   | Device ID.<br>**System API**: This is a system API. |
26
27## FormUsageState
28
29Enumerates the usage statuses of widgets.
30
31**System capability**: SystemCapability.Ability.Form
32
33**System API**: This is a system API.
34
35| Name       |  Value  | Description        |
36| ----------- | ---- | ------------ |
37| USED<sup>11+</sup> | 0   | The widget is in use. |
38| UNUSED<sup>11+</sup> | 1   | The widget is not in use. |
39
40## RunningFormInfo<sup>10+</sup>
41
42Defines the information about an added widget, which can be either in use or not.
43
44**System capability**: SystemCapability.Ability.Form
45
46**System API**: This is a system API.
47
48| Name       | Type                | Readable   | Writable   | Description                                                        |
49| ----------- | -------- | -------- | -------------------- | ------------------------------------------------------------ |
50| formId  | string               | Yes   | No    | Widget ID.                  |
51| bundleName<sup>10+</sup>  | string               | Yes   | No    | Name of the bundle to which the widget provider belongs.                  |
52| hostBundleName  | string               | Yes   | No    | Name of the bundle to which the widget host belongs.                  |
53| visibilityType  | [VisibilityType](js-apis-app-form-formInfo.md#visibilitytype)               | Yes   | No    | Visibility types of the widget.                  |
54| moduleName<sup>10+</sup>  | string               | Yes   | No    | Name of the module to which the widget belongs.                     |
55| abilityName<sup>10+</sup> | string               | Yes   | No    | Name of the ability to which the widget belongs.                      |
56| formName<sup>10+</sup>        | string               | Yes   | No    | Widget name.                                |
57| dimension | number               | Yes   | No    | Widget specifications.  |
58| formUsageState<sup>11+</sup> | [FormUsageState](#formusagestate)         | Yes   | No    | Usage status of the widget.  |
59| formDescription<sup>11+</sup> | string         | Yes   | No    | Description in the widget configuration file of the provider.  |
60| formLocation<sup>12+</sup> | [FormLocation](#formlocation12)| Yes   | No    | Location of the widget.  |
61
62## formProviderFilter<sup>10+</sup>
63
64Defines the information about the widget provider.
65
66**Model restriction**: This API can be used only in the stage model.
67
68**System capability**: SystemCapability.Ability.Form
69
70**System API**: This is a system API.
71
72| Name       | Type                | Readable   | Writable   | Description                                                        |
73| ----------- | -------- | -------- | -------------------- | ------------------------------------------------------------ |
74| bundleName  | string               | Yes   | No    | Name of the bundle to which the widget provider belongs. |
75| formName    | string               | Yes   | No    | Widget name.                    |
76| moduleName  | string               | Yes   | No    | Name of the module to which the widget belongs.       |
77| abilityName | string               | Yes   | No    | Name of the ability to which the widget belongs.       |
78| isUnusedIncluded<sup>11+</sup> | boolean               | Yes   | No    | Whether an unused widget is included.       |
79
80## FormInfoFilter
81
82Defines the widget information filter. Only the widget information that meets the filter is returned.
83
84**Atomic service API**: This API can be used in atomic services since API version 11.
85
86**System capability**: SystemCapability.Ability.Form
87
88| Name       | Type  | Mandatory        |Description        |
89| ----------- | ---- | ------------ |------------ |
90| 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. |
91| 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. |
92| 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.  |
93
94## FormLocation<sup>12+</sup>
95
96Enumerates the widget locations.
97
98**System capability**: SystemCapability.Ability.Form
99
100| Name                        | Value  | Description                            |
101| ---------------------------- | ---- | -------------------------------- |
102| OTHER                        | -1   | The widget is not located in any of the following defined positions.          |
103| DESKTOP                      | 0    | The widget is located on the home screen.              |
104| FORM_CENTER                  | 1    | The widget is located in the widget center of the home screen.    |
105| FORM_MANAGER                 | 2    | The widget is located in the widget manager of the home screen.  |
106| NEGATIVE_SCREEN              | 3    | The widget is located on the minus 1 screen.            |
107| FORM_CENTER_NEGATIVE_SCREEN  | 4    | The widget is located in the service panel of the minus 1 screen.  |
108| FORM_MANAGER_NEGATIVE_SCREEN | 5    | The widget is located in the widget manager of the minus 1 screen. |
109| SCREEN_LOCK                  | 6    | The widget is located on the locked screen.              |
110| AI_SUGGESTION                | 7    | The widget is located in the area of Celia Suggestions.    |
111
112## PublishFormResult
113
114Describes the result for the operation of adding a widget to the home screen.
115
116**System capability**: SystemCapability.Ability.Form
117
118| Name   | Type                                         | Readable | Writable | Description                      |
119| ------- | --------------------------------------------- | ---- | ---- | -------------------------- |
120| code    | [PublishFormErrorCode](#publishformerrorcode) | Yes  | No  | Result code of the operation.      |
121| message | string                                        | Yes  | No  | Message returned for the operation. |
122
123## PublishFormErrorCode
124
125Enumerates the result codes that may be used for the operation of adding a widget to the home screen.
126
127**System capability**: SystemCapability.Ability.Form
128
129| Name          | Value  | Description                            |
130| -------------- | ---- | -------------------------------- |
131| SUCCESS        | 0    | The widget is added to the home screen.              |
132| NO_SPACE       | 1    | There is no space for adding widgets.          |
133| PARAM_ERROR    | 2    | Parameter check fails.              |
134| INTERNAL_ERROR | 3    | An internal error occurs during widget processing. |
135