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