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> 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 9## Modules to Import 10 11```ts 12import { formProvider } from '@kit.FormKit'; 13``` 14 15## formProvider.setFormNextRefreshTime 16 17setFormNextRefreshTime(formId: string, minute: number, callback: AsyncCallback<void>): void 18 19Sets the next refresh time for a widget. This API uses an asynchronous callback to return the result. 20 21**Atomic service API**: This API can be used in atomic services since API version 11. 22 23**System capability**: SystemCapability.Ability.Form 24 25**Parameters** 26 27| Name| Type | Mandatory| Description | 28| ------ | ------ | ---- | ------------------------------------- | 29| formId | string | Yes | Widget ID. | 30| minute | number | Yes | Time after which a widget is updated. The value is greater than or equal to 5, in minutes. | 31| callback | AsyncCallback<void> | Yes| Callback used to return the result.| 32 33**Error codes** 34 35For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 36 37| Error Code ID| Error Message| 38| -------- | -------- | 39| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 40| 16500050 | IPC connection error. | 41| 16500060 | Service connection error. | 42| 16500100 | Failed to obtain the configuration information. | 43| 16501000 | An internal functional error occurred. | 44| 16501001 | The ID of the form to be operated does not exist. | 45| 16501002 | The number of forms exceeds the maximum allowed. | 46| 16501003 | The form cannot be operated by the current application. | 47 48**Example** 49 50```ts 51import { formProvider } from '@kit.FormKit'; 52import { BusinessError } from '@kit.BasicServicesKit'; 53 54let formId: string = '12400633174999288'; 55try { 56 formProvider.setFormNextRefreshTime(formId, 5, (error: BusinessError) => { 57 if (error) { 58 console.error(`callback error, code: ${error.code}, message: ${error.message})`); 59 return; 60 } 61 console.log(`formProvider setFormNextRefreshTime success`); 62 }); 63} catch (error) { 64 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`); 65} 66``` 67 68## formProvider.setFormNextRefreshTime 69 70setFormNextRefreshTime(formId: string, minute: number): Promise<void> 71 72Sets the next refresh time for a widget. This API uses a promise to return the result. 73 74**Atomic service API**: This API can be used in atomic services since API version 11. 75 76**System capability**: SystemCapability.Ability.Form 77 78**Parameters** 79 80| Name| Type | Mandatory| Description | 81| ------ | ------ | ---- | ------------------------------------- | 82| formId | string | Yes | Widget ID. | 83| minute | number | Yes | Time after which a widget is updated. The value is greater than or equal to 5, in minutes. | 84 85**Return value** 86 87| Type | Description | 88| ------------- | ---------------------------------- | 89| Promise\<void> | Promise that returns no value. | 90 91**Error codes** 92 93For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 94 95| Error Code ID| Error Message| 96| -------- | -------- | 97| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 98| 16500050 | IPC connection error. | 99| 16500060 | Service connection error. | 100| 16500100 | Failed to obtain the configuration information. | 101| 16501000 | An internal functional error occurred. | 102| 16501001 | The ID of the form to be operated does not exist. | 103| 16501002 | The number of forms exceeds the maximum allowed. | 104| 16501003 | The form cannot be operated by the current application. | 105 106**Example** 107 108```ts 109import { formProvider } from '@kit.FormKit'; 110import { BusinessError } from '@kit.BasicServicesKit'; 111 112let formId: string = '12400633174999288'; 113try { 114 formProvider.setFormNextRefreshTime(formId, 5).then(() => { 115 console.log(`formProvider setFormNextRefreshTime success`); 116 }).catch((error: BusinessError) => { 117 console.error(`promise error, code: ${error.code}, message: ${error.message})`); 118 }); 119} catch (error) { 120 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`); 121} 122``` 123 124## formProvider.updateForm 125 126updateForm(formId: string, formBindingData: formBindingData.FormBindingData,callback: AsyncCallback<void>): void 127 128Updates a widget. This API uses an asynchronous callback to return the result. 129 130**Atomic service API**: This API can be used in atomic services since API version 11. 131 132**System capability**: SystemCapability.Ability.Form 133 134**Parameters** 135 136| Name| Type | Mandatory| Description | 137| ------ | ---------------------------------------------------------------------- | ---- | ---------------- | 138| formId | string | Yes | ID of the widget to update.| 139| formBindingData | [formBindingData.FormBindingData](js-apis-app-form-formBindingData.md#formbindingdata) | Yes | Data to be used for the update. | 140| callback | AsyncCallback<void> | Yes| Callback used to return the result.| 141 142**Error codes** 143 144For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 145 146| Error Code ID| Error Message| 147| -------- | -------- | 148| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 149| 16500050 | IPC connection error. | 150| 16500060 | Service connection error. | 151| 16500100 | Failed to obtain the configuration information. | 152| 16501000 | An internal functional error occurred. | 153| 16501001 | The ID of the form to be operated does not exist. | 154| 16501003 | The form cannot be operated by the current application. | 155 156**Example** 157 158```ts 159import { formBindingData, formProvider } from '@kit.FormKit'; 160import { BusinessError } from '@kit.BasicServicesKit'; 161 162let formId: string = '12400633174999288'; 163try { 164 let param: Record<string, string> = { 165 'temperature': '22c', 166 'time': '22:00' 167 } 168 let obj: formBindingData.FormBindingData = formBindingData.createFormBindingData(param); 169 formProvider.updateForm(formId, obj, (error: BusinessError) => { 170 if (error) { 171 console.error(`callback error, code: ${error.code}, message: ${error.message})`); 172 return; 173 } 174 console.log(`formProvider updateForm success`); 175 }); 176} catch (error) { 177 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`); 178} 179``` 180 181## formProvider.updateForm 182 183updateForm(formId: string, formBindingData: formBindingData.FormBindingData): Promise<void> 184 185Updates a widget. This API uses a promise to return the result. 186 187**Atomic service API**: This API can be used in atomic services since API version 11. 188 189**System capability**: SystemCapability.Ability.Form 190 191**Parameters** 192 193| Name| Type | Mandatory| Description | 194| ------ | ---------------------------------------------------------------------- | ---- | ---------------- | 195| formId | string | Yes | ID of the widget to update.| 196| formBindingData | [formBindingData.FormBindingData](js-apis-app-form-formBindingData.md#formbindingdata) | Yes | Data to be used for the update. | 197 198**Return value** 199 200| Type | Description | 201| -------------- | ----------------------------------- | 202| Promise\<void> | Promise that returns no value.| 203 204**Error codes** 205 206For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 207 208| Error Code ID| Error Message| 209| -------- | -------- | 210| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 211| 16500050 | IPC connection error. | 212| 16500060 | Service connection error. | 213| 16500100 | Failed to obtain the configuration information. | 214| 16501000 | An internal functional error occurred. | 215| 16501001 | The ID of the form to be operated does not exist. | 216| 16501003 | The form cannot be operated by the current application. | 217 218**Example** 219 220```ts 221import { formBindingData, formProvider } from '@kit.FormKit'; 222import { BusinessError } from '@kit.BasicServicesKit'; 223 224let formId: string = '12400633174999288'; 225let param: Record<string, string> = { 226 'temperature': '22c', 227 'time': '22:00' 228} 229let obj: formBindingData.FormBindingData = formBindingData.createFormBindingData(param); 230try { 231 formProvider.updateForm(formId, obj).then(() => { 232 console.log(`formProvider updateForm success`); 233 }).catch((error: BusinessError) => { 234 console.error(`promise error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`); 235 }); 236} catch (error) { 237 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`); 238} 239``` 240 241## formProvider.getFormsInfo 242 243getFormsInfo(callback: AsyncCallback<Array<formInfo.FormInfo>>): void 244 245Obtains the application's widget information on the device. This API uses an asynchronous callback to return the result. 246 247**Atomic service API**: This API can be used in atomic services since API version 11. 248 249**System capability**: SystemCapability.Ability.Form 250 251**Parameters** 252 253| Name| Type | Mandatory| Description | 254| ------ | ------ | ---- | ------- | 255| callback | AsyncCallback<Array<[formInfo.FormInfo](js-apis-app-form-formInfo.md)>> | Yes| Callback used to return the information obtained.| 256 257**Error codes** 258 259For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 260 261| Error Code ID| Error Message| 262| -------- | -------- | 263| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 264| 16500050 | IPC connection error. | 265| 16500100 | Failed to obtain the configuration information. | 266| 16501000 | An internal functional error occurred. | 267 268**Example** 269 270```ts 271import { formProvider } from '@kit.FormKit'; 272import { BusinessError } from '@kit.BasicServicesKit'; 273 274try { 275 formProvider.getFormsInfo((error, data) => { 276 if (error) { 277 console.error(`callback error, code: ${error.code}, message: ${error.message})`); 278 return; 279 } 280 console.log(`formProvider getFormsInfo, data: ${JSON.stringify(data)}`); 281 }); 282} catch (error) { 283 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`); 284} 285``` 286## formProvider.getFormsInfo 287 288getFormsInfo(filter: formInfo.FormInfoFilter, callback: AsyncCallback<Array<formInfo.FormInfo>>): void 289 290Obtains the application's widget information that meets a filter criterion on the device. This API uses an asynchronous callback to return the result. 291 292**Atomic service API**: This API can be used in atomic services since API version 11. 293 294**System capability**: SystemCapability.Ability.Form 295 296**Parameters** 297 298| Name| Type | Mandatory| Description | 299| ------ | ------ | ---- | ------- | 300| filter | [formInfo.FormInfoFilter](js-apis-app-form-formInfo.md#forminfofilter) | Yes| Filter criterion.| 301| callback | AsyncCallback<Array<[formInfo.FormInfo](js-apis-app-form-formInfo.md)>> | Yes| Callback used to return the information obtained.| 302 303**Error codes** 304 305For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 306 307| Error Code ID| Error Message| 308| -------- | -------- | 309| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 310| 16500050 | IPC connection error. | 311| 16500100 | Failed to obtain the configuration information. | 312| 16501000 | An internal functional error occurred. | 313 314**Example** 315 316```ts 317import { formInfo, formProvider } from '@kit.FormKit'; 318import { BusinessError } from '@kit.BasicServicesKit'; 319 320const filter: formInfo.FormInfoFilter = { 321 // get info of forms belong to module entry. 322 moduleName: 'entry' 323}; 324try { 325 formProvider.getFormsInfo(filter, (error, data) => { 326 if (error) { 327 console.error(`callback error, code: ${error.code}, message: ${error.message})`); 328 return; 329 } 330 console.log(`formProvider getFormsInfo, data: ${JSON.stringify(data)}`); 331 }); 332} catch (error) { 333 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`); 334} 335``` 336 337## formProvider.getFormsInfo 338 339getFormsInfo(filter?: formInfo.FormInfoFilter): Promise<Array<formInfo.FormInfo>> 340 341Obtains the application's widget information on the device. This API uses a promise to return the result. 342 343**Atomic service API**: This API can be used in atomic services since API version 11. 344 345**System capability**: SystemCapability.Ability.Form 346 347**Parameters** 348 349| Name| Type | Mandatory| Description | 350| ------ | ------ | ---- | ------- | 351| filter | [formInfo.FormInfoFilter](js-apis-app-form-formInfo.md#forminfofilter) | No| Filter criterion. By default, no value is passed, indicating that no filtering is performed.| 352 353**Return value** 354 355| Type | Description | 356| :------------ | :---------------------------------- | 357| Promise<Array<[formInfo.FormInfo](js-apis-app-form-formInfo.md)>> | Promise used to return the information obtained.| 358 359**Error codes** 360 361For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 362 363| Error Code ID| Error Message| 364| -------- | -------- | 365| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 366| 16500050 | IPC connection error. | 367| 16500100 | Failed to obtain the configuration information. | 368| 16501000 | An internal functional error occurred. | 369 370**Example** 371 372```ts 373import { formInfo, formProvider } from '@kit.FormKit'; 374import { BusinessError } from '@kit.BasicServicesKit'; 375 376const filter: formInfo.FormInfoFilter = { 377 // get info of forms belong to module entry. 378 moduleName: 'entry' 379}; 380try { 381 formProvider.getFormsInfo(filter).then((data: formInfo.FormInfo[]) => { 382 console.log(`formProvider getFormsInfo, data: ${JSON.stringify(data)}`); 383 }).catch((error: BusinessError) => { 384 console.error(`promise error, code: ${error.code}, message: ${error.message})`); 385 }); 386} catch (error) { 387 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`); 388} 389``` 390