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## 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 for the next refresh. The value must be greater than or equal to 5, in minutes. | 31| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 32 33**Error codes** 34 35| Error Code ID | Error Message | 36| -------- | -------- | 37| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 38| 16500050 | IPC connection error. | 39| 16500060 | Service connection error. | 40| 16500100 | Failed to obtain the configuration information. | 41| 16501000 | An internal functional error occurred. | 42| 16501001 | The ID of the form to be operated does not exist. | 43| 16501002 | The number of forms exceeds the maximum allowed. | 44| 16501003 | The form cannot be operated by the current application. | 45 46For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 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## 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 for the next refresh. The value must be 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 93| Error Code ID | Error Message | 94| -------- | -------- | 95| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 96| 16500050 | IPC connection error. | 97| 16500060 | Service connection error. | 98| 16500100 | Failed to obtain the configuration information. | 99| 16501000 | An internal functional error occurred. | 100| 16501001 | The ID of the form to be operated does not exist. | 101| 16501002 | The number of forms exceeds the maximum allowed. | 102| 16501003 | The form cannot be operated by the current application. | 103 104For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 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## 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 144| Error Code ID | Error Message | 145| -------- | -------- | 146| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 147| 16500050 | IPC connection error. | 148| 16500060 | Service connection error. | 149| 16500100 | Failed to obtain the configuration information. | 150| 16501000 | An internal functional error occurred. | 151| 16501001 | The ID of the form to be operated does not exist. | 152| 16501003 | The form cannot be operated by the current application. | 153 154For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 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## 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 206| Error Code ID | Error Message | 207| -------- | -------- | 208| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 209| 16500050 | IPC connection error. | 210| 16500060 | Service connection error. | 211| 16500100 | Failed to obtain the configuration information. | 212| 16501000 | An internal functional error occurred. | 213| 16501001 | The ID of the form to be operated does not exist. | 214| 16501003 | The form cannot be operated by the current application. | 215 216For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 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## 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| Error Code ID | Error Message | 259| -------- | -------- | 260| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 261| 16500050 | IPC connection error. | 262| 16500100 | Failed to obtain the configuration information. | 263| 16501000 | An internal functional error occurred. | 264 265For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 266 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## 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 305| Error Code ID | Error Message | 306| -------- | -------- | 307| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 308| 16500050 | IPC connection error. | 309| 16500100 | Failed to obtain the configuration information. | 310| 16501000 | An internal functional error occurred. | 311 312For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 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## 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 361| Error Code ID | Error Message | 362| -------- | -------- | 363| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 364| 16500050 | IPC connection error. | 365| 16500100 | Failed to obtain the configuration information. | 366| 16501000 | An internal functional error occurred. | 367 368For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 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