1# @ohos.app.form.formProvider (formProvider) (System API)
2
3The **FormProvider** module provides APIs related to the widget provider. You can use the APIs to update a widget, set the next refresh time for a widget, obtain widget information, and request a widget release.
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.formProvider (formProvider)](./js-apis-app-form-formProvider.md).
9
10## Modules to Import
11
12```ts
13import { formProvider } from '@kit.FormKit';
14```
15
16
17## requestPublishForm
18
19requestPublishForm(want: Want, formBindingData: formBindingData.FormBindingData, callback: AsyncCallback\<string>): void
20
21Requests to publish a widget carrying data to the widget host (usually the home screen). This API uses an asynchronous callback to return the result.
22
23**System capability**: SystemCapability.Ability.Form
24
25**System API**: This is a system API.
26
27**Parameters**
28
29| Name| Type                                                                   | Mandatory| Description            |
30| ------ | ---------------------------------------------------------------------- | ---- | ---------------- |
31| want | [Want](../apis-ability-kit/js-apis-app-ability-want.md)                           | Yes  | Publish request, which must contain the following fields:<br>Information about the target widget.<br>**abilityName**: ability of the target widget.<br>**parameters**:<br>'ohos.extra.param.key.form_dimension'<br>'ohos.extra.param.key.form_name'<br>'ohos.extra.param.key.module_name' |
32| formBindingData | [formBindingData.FormBindingData](js-apis-app-form-formBindingData.md#formbindingdata) | Yes  | Data used for creating the widget.|
33| callback | AsyncCallback&lt;string&gt; | Yes| Callback used to return the widget ID.|
34
35**Error codes**
36
37| Error Code ID| Error Message|
38| -------- | -------- |
39| 202 | The application is not a system application. |
40| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. |
41| 16500050 | IPC connection error. |
42| 16500100 | Failed to obtain the configuration information. |
43| 16501000 | An internal functional error occurred. |
44
45For details about the error codes, see [Form Error Codes](errorcode-form.md).
46
47**Example**
48
49```ts
50import { formBindingData, formProvider } from '@kit.FormKit';
51import { Want } from '@kit.AbilityKit';
52import { BusinessError } from '@kit.BasicServicesKit';
53
54let want: Want = {
55  abilityName: 'FormAbility',
56  parameters: {
57    'ohos.extra.param.key.form_dimension': 2,
58    'ohos.extra.param.key.form_name': 'widget',
59    'ohos.extra.param.key.module_name': 'entry'
60  }
61};
62try {
63  let param: Record<string, string> = {
64    'temperature': '22c',
65    'time': '22:00'
66  }
67  let obj: formBindingData.FormBindingData = formBindingData.createFormBindingData(param);
68  formProvider.requestPublishForm(want, obj, (error: BusinessError, data: string) => {
69    if (error) {
70      console.error(`callback error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`);
71      return;
72    }
73    console.log(`formProvider requestPublishForm, form ID is: ${JSON.stringify(data)}`);
74  });
75} catch (error) {
76  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`);
77}
78```
79
80## requestPublishForm
81
82requestPublishForm(want: Want, callback: AsyncCallback&lt;string&gt;): void
83
84Requests to publish a widget to the widget host (usually the home screen). This API uses an asynchronous callback to return the result.
85
86**System capability**: SystemCapability.Ability.Form
87
88**System API**: This is a system API.
89
90**Parameters**
91
92| Name  | Type                               | Mandatory| Description                                                        |
93| -------- | ----------------------------------- | ---- | ------------------------------------------------------------ |
94| want     | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes  | Publish request, which must contain the following fields:<br>Information about the target widget.<br>**abilityName**: ability of the target widget.<br>**parameters**:<br>'ohos.extra.param.key.form_dimension'<br>'ohos.extra.param.key.form_name'<br>'ohos.extra.param.key.module_name' |
95| callback | AsyncCallback&lt;string&gt;         | Yes  |  Callback used to return the widget ID.|
96
97**Error codes**
98
99| Error Code ID| Error Message|
100| -------- | -------- |
101| 202 | The application is not a system application. |
102| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. |
103| 16500050 | IPC connection error. |
104| 16500100 | Failed to obtain the configuration information. |
105| 16501000 | An internal functional error occurred. |
106
107For details about the error codes, see [Form Error Codes](errorcode-form.md).
108
109**Example**
110
111```ts
112import { formProvider } from '@kit.FormKit';
113import { Want } from '@kit.AbilityKit';
114import { BusinessError } from '@kit.BasicServicesKit';
115
116let want: Want = {
117  abilityName: 'FormAbility',
118  parameters: {
119    'ohos.extra.param.key.form_dimension': 2,
120    'ohos.extra.param.key.form_name': 'widget',
121    'ohos.extra.param.key.module_name': 'entry'
122  }
123};
124try {
125  formProvider.requestPublishForm(want, (error: BusinessError, data: string) => {
126    if (error) {
127      console.error(`callback error, code: ${error.code}, message: ${error.message})`);
128      return;
129    }
130    console.log(`formProvider requestPublishForm, form ID is: ${JSON.stringify(data)}`);
131  });
132} catch (error) {
133  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`);
134}
135```
136
137## requestPublishForm
138
139requestPublishForm(want: Want, formBindingData?: formBindingData.FormBindingData): Promise&lt;string&gt;
140
141Requests to publish a widget to the widget host (usually the home screen). This API uses a promise to return the result.
142
143**System capability**: SystemCapability.Ability.Form
144
145**System API**: This is a system API.
146
147**Parameters**
148
149| Name         | Type                                                        | Mandatory| Description                                                        |
150| --------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
151| want            | [Want](../apis-ability-kit/js-apis-app-ability-want.md)                          | Yes  | Publish request, which must contain the following fields:<br>Information about the target widget.<br>**abilityName**: ability of the target widget.<br>**parameters**:<br>'ohos.extra.param.key.form_dimension'<br>'ohos.extra.param.key.form_name'<br>'ohos.extra.param.key.module_name' |
152| formBindingData | [formBindingData.FormBindingData](js-apis-app-form-formBindingData.md#formbindingdata) | No  | Data used for creating the widget. By default, no value is passed, indicating that no data is provided.                                     |
153
154**Return value**
155
156| Type         | Description                               |
157| :------------ | :---------------------------------- |
158| Promise&lt;string&gt; | Promise used to return the widget ID.|
159
160**Error codes**
161
162| Error Code ID| Error Message|
163| -------- | -------- |
164| 202 | The application is not a system application. |
165| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. |
166| 16500050 | IPC connection error. |
167| 16500100 | Failed to obtain the configuration information. |
168| 16501000 | An internal functional error occurred. |
169
170For details about the error codes, see [Form Error Codes](errorcode-form.md).
171
172**Example**
173
174```ts
175import { formProvider } from '@kit.FormKit';
176import { Want } from '@kit.AbilityKit';
177import { BusinessError } from '@kit.BasicServicesKit';
178
179let want: Want = {
180  abilityName: 'FormAbility',
181  parameters: {
182    'ohos.extra.param.key.form_dimension': 2,
183    'ohos.extra.param.key.form_name': 'widget',
184    'ohos.extra.param.key.module_name': 'entry'
185  }
186};
187try {
188  formProvider.requestPublishForm(want).then((data: string) => {
189    console.log(`formProvider requestPublishForm success, form ID is : ${JSON.stringify(data)}`);
190  }).catch((error: BusinessError) => {
191    console.error(`promise error, code: ${error.code}, message: ${error.message})`);
192  });
193} catch (error) {
194  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`);
195}
196```
197
198## isRequestPublishFormSupported
199
200isRequestPublishFormSupported(callback: AsyncCallback&lt;boolean&gt;): void
201
202Checks whether a widget can be published to the widget host. This API uses an asynchronous callback to return the result.
203
204**System API**: This is a system API.
205
206**System capability**: SystemCapability.Ability.Form
207
208**Parameters**
209
210| Name| Type   | Mandatory| Description   |
211| ------ | ------ | ---- | ------- |
212| callback | AsyncCallback&lt;boolean&gt; | Yes| Callback used to return whether the widget can be published to the widget host.|
213
214**Error codes**
215
216| Error Code ID| Error Message|
217| -------- | -------- |
218| 202 | The application is not a system application. |
219| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. |
220| 16500050 | IPC connection error. |
221| 16501000 | An internal functional error occurred. |
222
223For details about the error codes, see [Form Error Codes](errorcode-form.md).
224
225**Example**
226
227```ts
228import { formProvider } from '@kit.FormKit';
229import { Want } from '@kit.AbilityKit';
230import { BusinessError } from '@kit.BasicServicesKit';
231
232try {
233  formProvider.isRequestPublishFormSupported((error: BusinessError, isSupported: boolean) => {
234    if (error) {
235      console.error(`callback error, code: ${error.code}, message: ${error.message})`);
236    } else {
237      if (isSupported) {
238        let want: Want = {
239          abilityName: 'FormAbility',
240          parameters: {
241            'ohos.extra.param.key.form_dimension': 2,
242            'ohos.extra.param.key.form_name': 'widget',
243            'ohos.extra.param.key.module_name': 'entry'
244          }
245        };
246        try {
247          formProvider.requestPublishForm(want, (error: BusinessError, data: string) => {
248            if (error) {
249              console.error(`callback error, code: ${error.code}, message: ${error.message})`);
250              return;
251            }
252            console.log(`formProvider requestPublishForm, form ID is: ${JSON.stringify(data)}`);
253          });
254        } catch (error) {
255          console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`);
256        }
257      }
258    }
259  });
260} catch (error) {
261  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`);
262}
263```
264
265## isRequestPublishFormSupported
266
267isRequestPublishFormSupported(): Promise&lt;boolean&gt;
268
269Checks whether a widget can be published to the widget host. This API uses a promise to return the result.
270
271**System API**: This is a system API.
272
273**System capability**: SystemCapability.Ability.Form
274
275**Return value**
276
277| Type         | Description                               |
278| :------------ | :---------------------------------- |
279| Promise&lt;boolean&gt; | Promise used to return whether the widget can be published to the widget host.|
280
281**Error codes**
282
283| Error Code ID| Error Message|
284| -------- | -------- |
285| 202 | The application is not a system application. |
286| 16500050 | IPC connection error. |
287| 16501000 | An internal functional error occurred. |
288
289For details about the error codes, see [Form Error Codes](errorcode-form.md).
290
291**Example**
292
293```ts
294import { formProvider } from '@kit.FormKit';
295import { Want } from '@kit.AbilityKit';
296import { BusinessError } from '@kit.BasicServicesKit';
297
298try {
299  formProvider.isRequestPublishFormSupported().then((isSupported: boolean) => {
300    if (isSupported) {
301      let want: Want = {
302        abilityName: 'FormAbility',
303        parameters: {
304          'ohos.extra.param.key.form_dimension': 2,
305          'ohos.extra.param.key.form_name': 'widget',
306          'ohos.extra.param.key.module_name': 'entry'
307        }
308      };
309      try {
310        formProvider.requestPublishForm(want).then((data: string) => {
311          console.log(`formProvider requestPublishForm success, form ID is : ${JSON.stringify(data)}`);
312        }).catch((error: BusinessError) => {
313          console.error(`promise error, code: ${error.code}, message: ${error.message})`);
314        });
315      } catch (error) {
316        console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`);
317      }
318    }
319  }).catch((error: BusinessError) => {
320    console.error(`promise error, code: ${error.code}, message: ${error.message})`);
321  });
322} catch (error) {
323  console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`);
324}
325```
326