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