1# @ohos.app.form.formProvider (FormProvider) 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> 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. 7 8## Modules to Import 9 10```ts 11import formProvider from '@ohos.app.form.formProvider'; 12``` 13 14## setFormNextRefreshTime 15 16setFormNextRefreshTime(formId: string, minute: number, callback: AsyncCallback<void>): void 17 18Sets the next refresh time for a widget. This API uses an asynchronous callback to return the result. 19 20**System capability**: SystemCapability.Ability.Form 21 22**Parameters** 23 24| Name| Type | Mandatory| Description | 25| ------ | ------ | ---- | ------------------------------------- | 26| formId | string | Yes | Widget ID. | 27| minute | number | Yes | Refresh interval, in minutes. The value must be greater than or equal to 5. | 28| callback | AsyncCallback<void> | Yes| Callback used to return the result.| 29 30**Error codes** 31 32| Error Code ID| Error Message| 33| -------- | -------- | 34| 401 | If the input parameter is not valid parameter. | 35| 16500050 | An IPC connection error happened. | 36| 16500060 | A service connection error happened, please try again later. | 37| 16500100 | Failed to obtain the configuration information. | 38| 16501000 | An internal functional error occurred. | 39| 16501001 | The ID of the form to be operated does not exist. | 40| 16501002 | The number of forms exceeds upper bound. | 41| 16501003 | The form can not be operated by the current application. | 42 43For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). 44 45**Example** 46 47```ts 48var formId = '12400633174999288'; 49try { 50 formProvider.setFormNextRefreshTime(formId, 5, (error) => { 51 if (error) { 52 console.log('formProvider setFormNextRefreshTime, error:' + JSON.stringify(error)); 53 return; 54 } 55 console.log(`formProvider setFormNextRefreshTime success`); 56 }); 57} catch (error) { 58 console.log('error' + JSON.stringify(error)) 59} 60``` 61 62## setFormNextRefreshTime 63 64setFormNextRefreshTime(formId: string, minute: number): Promise<void> 65 66Sets the next refresh time for a widget. This API uses a promise to return the result. 67 68**System capability**: SystemCapability.Ability.Form 69 70**Parameters** 71 72| Name| Type | Mandatory| Description | 73| ------ | ------ | ---- | ------------------------------------- | 74| formId | string | Yes | Widget ID. | 75| minute | number | Yes | Refresh interval, in minutes. The value must be greater than or equal to 5. | 76 77**Return value** 78 79| Type | Description | 80| ------------- | ---------------------------------- | 81| Promise\<void> | Promise that returns no value. | 82 83**Error codes** 84 85| Error Code ID| Error Message| 86| -------- | -------- | 87| 401 | If the input parameter is not valid parameter. | 88| 16500050 | An IPC connection error happened. | 89| 16500060 | A service connection error happened, please try again later. | 90| 16500100 | Failed to obtain the configuration information. | 91| 16501000 | An internal functional error occurred. | 92| 16501001 | The ID of the form to be operated does not exist. | 93| 16501002 | The number of forms exceeds upper bound. | 94| 16501003 | The form can not be operated by the current application. | 95 96For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). 97 98**Example** 99 100```ts 101var formId = '12400633174999288'; 102try { 103 formProvider.setFormNextRefreshTime(formId, 5).then(() => { 104 console.log('formProvider setFormNextRefreshTime success'); 105 }).catch((error) => { 106 console.log('formProvider setFormNextRefreshTime, error:' + JSON.stringify(error)); 107 }); 108} catch (error) { 109 console.log(`catch err->${JSON.stringify(error)}`); 110} 111``` 112 113## updateForm 114 115updateForm(formId: string, formBindingData: formBindingData.FormBindingData,callback: AsyncCallback<void>): void 116 117Updates a widget. This API uses an asynchronous callback to return the result. 118 119**System capability**: SystemCapability.Ability.Form 120 121**Parameters** 122 123| Name| Type | Mandatory| Description | 124| ------ | ---------------------------------------------------------------------- | ---- | ---------------- | 125| formId | string | Yes | ID of the widget to update.| 126| formBindingData.FormBindingData | [FormBindingData](js-apis-app-form-formBindingData.md#formbindingdata) | Yes | Data to be used for the update. | 127| callback | AsyncCallback<void> | Yes| Callback used to return the result.| 128 129**Error codes** 130 131| Error Code ID| Error Message| 132| -------- | -------- | 133| 401 | If the input parameter is not valid parameter. | 134| 16500050 | An IPC connection error happened. | 135| 16500060 | A service connection error happened, please try again later. | 136| 16500100 | Failed to obtain the configuration information. | 137| 16501000 | An internal functional error occurred. | 138| 16501001 | The ID of the form to be operated does not exist. | 139| 16501003 | The form can not be operated by the current application. | 140 141For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). 142 143**Example** 144 145```ts 146import formBindingData from '@ohos.app.form.formBindingData'; 147 148var formId = '12400633174999288'; 149try { 150 let obj = formBindingData.createFormBindingData({temperature:'22c', time:'22:00'}); 151 formProvider.updateForm(formId, obj, (error) => { 152 if (error) { 153 console.log('formProvider updateForm, error:' + JSON.stringify(error)); 154 return; 155 } 156 console.log(`formProvider updateForm success`); 157 }); 158} catch (error) { 159 console.log(`catch err->${JSON.stringify(error)}`); 160} 161``` 162 163## updateForm 164 165updateForm(formId: string, formBindingData: formBindingData.FormBindingData): Promise<void> 166 167Updates a widget. This API uses a promise to return the result. 168 169**System capability**: SystemCapability.Ability.Form 170 171**Parameters** 172 173| Name| Type | Mandatory| Description | 174| ------ | ---------------------------------------------------------------------- | ---- | ---------------- | 175| formId | string | Yes | ID of the widget to update.| 176| formBindingData.FormBindingData | [FormBindingData](js-apis-app-form-formBindingData.md#formbindingdata) | Yes | Data to be used for the update. | 177 178**Return value** 179 180| Type | Description | 181| -------------- | ----------------------------------- | 182| Promise\<void> | Promise that returns no value.| 183 184**Error codes** 185 186| Error Code ID| Error Message| 187| -------- | -------- | 188| 401 | If the input parameter is not valid parameter. | 189| 16500050 | An IPC connection error happened. | 190| 16500060 | A service connection error happened, please try again later. | 191| 16500100 | Failed to obtain the configuration information. | 192| 16501000 | An internal functional error occurred. | 193| 16501001 | The ID of the form to be operated does not exist. | 194| 16501003 | The form can not be operated by the current application. | 195 196For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). 197 198**Example** 199 200```ts 201import formBindingData from '@ohos.app.form.formBindingData'; 202 203let formId = '12400633174999288'; 204let obj = formBindingData.createFormBindingData({ temperature: '22c', time: '22:00' }); 205try { 206 formProvider.updateForm(formId, obj).then(() => { 207 console.log('formProvider updateForm success'); 208 }).catch((error) => { 209 console.log('formProvider updateForm, error:' + JSON.stringify(error)); 210 }); 211} catch (error) { 212 console.log(`catch err->${JSON.stringify(error)}`); 213} 214``` 215 216## getFormsInfo 217 218getFormsInfo(callback: AsyncCallback<Array<formInfo.FormInfo>>): void 219 220Obtains the application's widget information on the device. This API uses an asynchronous callback to return the result. 221 222**System capability**: SystemCapability.Ability.Form 223 224**Parameters** 225 226| Name| Type | Mandatory| Description | 227| ------ | ------ | ---- | ------- | 228| callback | AsyncCallback<Array<[FormInfo](js-apis-app-form-formInfo.md)>> | Yes| Callback used to return the information obtained.| 229 230**Error codes** 231| Error Code ID| Error Message| 232| -------- | -------- | 233| 401 | If the input parameter is not valid parameter. | 234| 16500050 | An IPC connection error happened. | 235| 16500100 | Failed to obtain the configuration information. | 236| 16501000 | An internal functional error occurred. | 237 238For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). 239 240 241**Example** 242 243```ts 244try { 245 formProvider.getFormsInfo((error, data) => { 246 if (error) { 247 console.log('formProvider getFormsInfo, error:' + JSON.stringify(error)); 248 return; 249 } 250 console.log('formProvider getFormsInfo, data:' + JSON.stringify(data)); 251 }); 252} catch (error) { 253 console.log(`catch err->${JSON.stringify(error)}`); 254} 255``` 256## getFormsInfo 257 258getFormsInfo(filter: formInfo.FormInfoFilter, callback: AsyncCallback<Array<formInfo.FormInfo>>): void 259 260Obtains the application's widget information that meets a filter criterion on the device. This API uses an asynchronous callback to return the result. 261 262**System capability**: SystemCapability.Ability.Form 263 264**Parameters** 265 266| Name| Type | Mandatory| Description | 267| ------ | ------ | ---- | ------- | 268| filter | [formInfo.FormInfoFilter](js-apis-app-form-formInfo.md#forminfofilter) | Yes| Filter criterion.| 269| callback | AsyncCallback<Array<[FormInfo](js-apis-app-form-formInfo.md)>> | Yes| Callback used to return the information obtained.| 270 271**Error codes** 272 273| Error Code ID| Error Message| 274| -------- | -------- | 275| 401 | If the input parameter is not valid parameter. | 276| 16500050 | An IPC connection error happened. | 277| 16500100 | Failed to obtain the configuration information. | 278| 16501000 | An internal functional error occurred. | 279 280For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). 281 282**Example** 283 284```ts 285import formInfo from '@ohos.app.form.formInfo'; 286 287const filter : formInfo.FormInfoFilter = { 288 // get info of forms belong to module entry. 289 moduleName : 'entry' 290}; 291try { 292 formProvider.getFormsInfo(filter, (error, data) => { 293 if (error) { 294 console.log('formProvider getFormsInfo, error:' + JSON.stringify(error)); 295 return; 296 } 297 console.log('formProvider getFormsInfo, data:' + JSON.stringify(data)); 298 }); 299} catch(error) { 300 console.log(`catch err->${JSON.stringify(error)}`); 301} 302``` 303 304## getFormsInfo 305 306getFormsInfo(filter?: formInfo.FormInfoFilter): Promise<Array<formInfo.FormInfo>> 307 308Obtains the application's widget information on the device. This API uses a promise to return the result. 309 310**System capability**: SystemCapability.Ability.Form 311 312**Parameters** 313 314| Name| Type | Mandatory| Description | 315| ------ | ------ | ---- | ------- | 316| filter | [formInfo.FormInfoFilter](js-apis-app-form-formInfo.md#forminfofilter) | No| Filter criterion.| 317 318**Return value** 319 320| Type | Description | 321| :------------ | :---------------------------------- | 322| Promise<Array<[FormInfo](js-apis-app-form-formInfo.md)>> | Promise used to return the information obtained.| 323 324**Error codes** 325 326| Error Code ID| Error Message| 327| -------- | -------- | 328| 401 | If the input parameter is not valid parameter. | 329| 16500050 | An IPC connection error happened. | 330| 16500100 | Failed to obtain the configuration information. | 331| 16501000 | An internal functional error occurred. | 332 333For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). 334 335**Example** 336 337```ts 338import formInfo from '@ohos.app.form.formInfo'; 339 340const filter : formInfo.FormInfoFilter = { 341 // get info of forms belong to module entry. 342 moduleName : 'entry' 343}; 344try { 345 formProvider.getFormsInfo(filter).then((data) => { 346 console.log('formProvider getFormsInfo, data:' + JSON.stringify(data)); 347 }).catch((error) => { 348 console.log('formProvider getFormsInfo, error:' + JSON.stringify(error)); 349 }); 350} catch (error) { 351 console.log(`catch err->${JSON.stringify(error)}`); 352} 353``` 354 355## requestPublishForm 356 357requestPublishForm(want: Want, formBindingData: formBindingData.FormBindingData, callback: AsyncCallback\<string>): void 358 359Requests to publish a widget carrying data to the widget host. This API uses an asynchronous callback to return the result. This API is usually called by the home screen. 360 361**System capability**: SystemCapability.Ability.Form 362 363**System API**: This is a system API. 364 365**Parameters** 366 367| Name| Type | Mandatory| Description | 368| ------ | ---------------------------------------------------------------------- | ---- | ---------------- | 369| want | [Want](js-apis-application-want.md) | Yes | Request used for publishing. The following fields must be included:<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' | 370| formBindingData.FormBindingData | [FormBindingData](js-apis-app-form-formBindingData.md#formbindingdata) | Yes | Data used for creating the widget.| 371| callback | AsyncCallback<string> | Yes| Callback used to return the widget ID.| 372 373**Error codes** 374 375| Error Code ID| Error Message| 376| -------- | -------- | 377| 202 | The application is not a system application. | 378| 401 | If the input parameter is not valid parameter. | 379| 16500050 | An IPC connection error happened. | 380| 16500100 | Failed to obtain the configuration information. | 381| 16501000 | An internal functional error occurred. | 382 383For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). 384 385**Example** 386 387```ts 388import formBindingData from '@ohos.app.form.formBindingData'; 389 390let want = { 391 abilityName: 'FormAbility', 392 parameters: { 393 'ohos.extra.param.key.form_dimension': 2, 394 'ohos.extra.param.key.form_name': 'widget', 395 'ohos.extra.param.key.module_name': 'entry' 396 } 397}; 398try { 399 let obj = formBindingData.createFormBindingData({temperature:'22c', time:'22:00'}); 400 formProvider.requestPublishForm(want, obj, (error, data) => { 401 if (error) { 402 console.log('formProvider requestPublishForm, error: ' + JSON.stringify(error)); 403 return; 404 } 405 console.log('formProvider requestPublishForm, form ID is: ' + JSON.stringify(data)); 406 }); 407} catch (error) { 408 console.log(`catch err->${JSON.stringify(error)}`); 409} 410``` 411 412## requestPublishForm 413 414requestPublishForm(want: Want, callback: AsyncCallback<string>): void 415 416Requests to publish a widget to the widget host. This API uses an asynchronous callback to return the result. This API is usually called by the home screen. 417 418**System capability**: SystemCapability.Ability.Form 419 420**System API**: This is a system API. 421 422**Parameters** 423 424| Name | Type | Mandatory| Description | 425| -------- | ----------------------------------- | ---- | ------------------------------------------------------------ | 426| want | [Want](js-apis-application-want.md) | Yes | Request used for publishing. The following fields must be included:<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' | 427| callback | AsyncCallback<string> | Yes | Callback used to return the widget ID.| 428 429**Error codes** 430 431| Error Code ID| Error Message| 432| -------- | -------- | 433| 202 | The application is not a system application. | 434| 401 | If the input parameter is not valid parameter. | 435| 16500050 | An IPC connection error happened. | 436| 16500100 | Failed to obtain the configuration information. | 437| 16501000 | An internal functional error occurred. | 438 439For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). 440 441**Example** 442 443```ts 444let want = { 445 abilityName: 'FormAbility', 446 parameters: { 447 'ohos.extra.param.key.form_dimension': 2, 448 'ohos.extra.param.key.form_name': 'widget', 449 'ohos.extra.param.key.module_name': 'entry' 450 } 451}; 452try { 453 formProvider.requestPublishForm(want, (error, data) => { 454 if (error) { 455 console.log('formProvider requestPublishForm, error: ' + JSON.stringify(error)); 456 return; 457 } 458 console.log('formProvider requestPublishForm, form ID is: ' + JSON.stringify(data)); 459 }); 460} catch (error) { 461 console.log(`catch err->${JSON.stringify(error)}`); 462} 463 464``` 465 466## requestPublishForm 467 468requestPublishForm(want: Want, formBindingData?: formBindingData.FormBindingData): Promise<string> 469 470Requests to publish a widget to the widget host. This API uses a promise to return the result. This API is usually called by the home screen. 471 472**System capability**: SystemCapability.Ability.Form 473 474**System API**: This is a system API. 475 476**Parameters** 477 478| Name | Type | Mandatory| Description | 479| --------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 480| want | [Want](js-apis-application-want.md) | Yes | Request used for publishing. The following fields must be included:<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' | 481| formBindingData.FormBindingData | [FormBindingData](js-apis-app-form-formBindingData.md#formbindingdata) | No | Data used for creating the widget. | 482 483**Return value** 484 485| Type | Description | 486| :------------ | :---------------------------------- | 487| Promise<string> | Promise used to return the widget ID.| 488 489**Error codes** 490 491| Error Code ID| Error Message| 492| -------- | -------- | 493| 202 | The application is not a system application. | 494| 401 | If the input parameter is not valid parameter. | 495| 16500050 | An IPC connection error happened. | 496| 16500100 | Failed to obtain the configuration information. | 497| 16501000 | An internal functional error occurred. | 498 499For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). 500 501**Example** 502 503```ts 504let want = { 505 abilityName: 'FormAbility', 506 parameters: { 507 'ohos.extra.param.key.form_dimension': 2, 508 'ohos.extra.param.key.form_name': 'widget', 509 'ohos.extra.param.key.module_name': 'entry' 510 } 511}; 512try { 513 formProvider.requestPublishForm(want).then((data) => { 514 console.log('formProvider requestPublishForm success, form ID is :' + JSON.stringify(data)); 515 }).catch((error) => { 516 console.log('formProvider requestPublishForm, error: ' + JSON.stringify(error)); 517 }); 518} catch (error) { 519 console.log(`catch err->${JSON.stringify(error)}`); 520} 521``` 522 523## isRequestPublishFormSupported 524 525isRequestPublishFormSupported(callback: AsyncCallback<boolean>): void 526 527Checks whether a widget can be published to the widget host. This API uses an asynchronous callback to return the result. 528 529**System API**: This is a system API. 530 531**System capability**: SystemCapability.Ability.Form 532 533**Parameters** 534 535| Name| Type | Mandatory| Description | 536| ------ | ------ | ---- | ------- | 537| callback | AsyncCallback<boolean> | Yes| Callback used to return whether the widget can be published to the widget host.| 538 539**Error codes** 540 541| Error Code ID| Error Message| 542| -------- | -------- | 543| 202 | The application is not a system application. | 544| 401 | If the input parameter is not valid parameter. | 545| 16500050 | An IPC connection error happened. | 546| 16501000 | An internal functional error occurred. | 547 548For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). 549 550**Example** 551 552```ts 553try { 554 formProvider.isRequestPublishFormSupported((error, isSupported) => { 555 if (error) { 556 console.log('formProvider isRequestPublishFormSupported, error:' + JSON.stringify(error)); 557 } else { 558 if (isSupported) { 559 var want = { 560 abilityName: 'FormAbility', 561 parameters: { 562 'ohos.extra.param.key.form_dimension': 2, 563 'ohos.extra.param.key.form_name': 'widget', 564 'ohos.extra.param.key.module_name': 'entry' 565 } 566 }; 567 try { 568 formProvider.requestPublishForm(want, (error, data) => { 569 if (error) { 570 console.log('formProvider requestPublishForm, error: ' + JSON.stringify(error)); 571 } else { 572 console.log('formProvider requestPublishForm, form ID is: ' + JSON.stringify(data)); 573 } 574 }); 575 } catch (error) { 576 console.log(`catch err->${JSON.stringify(error)}`); 577 } 578 579 } 580 } 581}); 582} catch (error) { 583 console.log(`catch err->${JSON.stringify(error)}`); 584} 585``` 586 587## isRequestPublishFormSupported 588 589isRequestPublishFormSupported(): Promise<boolean> 590 591Checks whether a widget can be published to the widget host. This API uses a promise to return the result. 592 593**System API**: This is a system API. 594 595**System capability**: SystemCapability.Ability.Form 596 597**Return value** 598 599| Type | Description | 600| :------------ | :---------------------------------- | 601| Promise<boolean> | Promise used to return whether the widget can be published to the widget host.| 602 603**Error codes** 604 605| Error Code ID| Error Message| 606| -------- | -------- | 607| 202 | The application is not a system application. | 608| 16500050 | An IPC connection error happened. | 609| 16501000 | An internal functional error occurred. | 610 611For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). 612 613**Example** 614 615```ts 616try { 617 formProvider.isRequestPublishFormSupported().then((isSupported) => { 618 if (isSupported) { 619 var want = { 620 abilityName: 'FormAbility', 621 parameters: { 622 'ohos.extra.param.key.form_dimension': 2, 623 'ohos.extra.param.key.form_name': 'widget', 624 'ohos.extra.param.key.module_name': 'entry' 625 } 626 }; 627 try { 628 formProvider.requestPublishForm(want).then((data) => { 629 console.log('formProvider requestPublishForm success, form ID is :' + JSON.stringify(data)); 630 }).catch((error) => { 631 console.log('formProvider requestPublishForm, error: ' + JSON.stringify(error)); 632 }); 633 } catch (error) { 634 console.log(`catch err->${JSON.stringify(error)}`); 635 } 636 637 } 638 }).catch((error) => { 639 console.log('formProvider isRequestPublishFormSupported, error:' + JSON.stringify(error)); 640 }); 641} catch (error) { 642 console.log(`catch err->${JSON.stringify(error)}`); 643} 644``` 645