1# @ohos.app.form.formProvider (formProvider) 2 3FormProvider模块提供了卡片提供方相关接口的能力，开发者在开发卡片时，可通过该模块提供接口实现更新卡片、设置卡片更新时间、获取卡片信息、请求发布卡片等。 4 5> **说明：** 6> 7> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8 9## 导入模块 10 11```ts 12import { formProvider } from '@kit.FormKit'; 13``` 14 15## formProvider.setFormNextRefreshTime 16 17setFormNextRefreshTime(formId: string, minute: number, callback: AsyncCallback<void>): void 18 19设置指定卡片的下一次更新时间，使用callback异步回调。 20 21**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 22 23**系统能力：** SystemCapability.Ability.Form 24 25**参数：** 26 27| 参数名 | 类型 | 必填 | 说明 | 28| ------ | ------ | ---- | ------------------------------------- | 29| formId | string | 是 | 卡片标识。 | 30| minute | number | 是 | 指定卡片多久之后更新，取值范围：大于等于5，单位：min。 | 31| callback | AsyncCallback<void> | 是 | 回调函数。 | 32 33**错误码：** 34 35以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[卡片错误码](errorcode-form.md)。 36 37| 错误码ID | 错误信息 | 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**示例：** 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 72设置指定卡片的下一次更新时间，使用Promise异步回调。 73 74**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 75 76**系统能力：** SystemCapability.Ability.Form 77 78**参数：** 79 80| 参数名 | 类型 | 必填 | 说明 | 81| ------ | ------ | ---- | ------------------------------------- | 82| formId | string | 是 | 卡片标识。 | 83| minute | number | 是 | 指定卡片多久之后更新，取值范围：大于等于5，单位：min。 | 84 85**返回值：** 86 87| 类型 | 说明 | 88| ------------- | ---------------------------------- | 89| Promise\<void> | 无返回结果的Promise对象。 | 90 91**错误码：** 92 93以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[卡片错误码](errorcode-form.md)。 94 95| 错误码ID | 错误信息 | 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**示例：** 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 128更新指定的卡片，使用callback异步回调。 129 130**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 131 132**系统能力：** SystemCapability.Ability.Form 133 134**参数：** 135 136| 参数名 | 类型 | 必填 | 说明 | 137| ------ | ---------------------------------------------------------------------- | ---- | ---------------- | 138| formId | string | 是 | 请求更新的卡片标识。 | 139| formBindingData | [formBindingData.FormBindingData](js-apis-app-form-formBindingData.md#formbindingdata) | 是 | 用于更新的数据。 | 140| callback | AsyncCallback<void> | 是 | 回调函数。 | 141 142**错误码：** 143 144以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[卡片错误码](errorcode-form.md)。 145 146| 错误码ID | 错误信息 | 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**示例：** 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 185更新指定的卡片，使用Promise异步回调。 186 187**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 188 189**系统能力：** SystemCapability.Ability.Form 190 191**参数：** 192 193| 参数名 | 类型 | 必填 | 说明 | 194| ------ | ---------------------------------------------------------------------- | ---- | ---------------- | 195| formId | string | 是 | 请求更新的卡片标识。 | 196| formBindingData | [formBindingData.FormBindingData](js-apis-app-form-formBindingData.md#formbindingdata) | 是 | 用于更新的数据。 | 197 198**返回值：** 199 200| 类型 | 说明 | 201| -------------- | ----------------------------------- | 202| Promise\<void> | 无返回结果的Promise对象。 | 203 204**错误码：** 205 206以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[卡片错误码](errorcode-form.md)。 207 208| 错误码ID | 错误信息 | 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**示例：** 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 245获取设备上当前应用程序的卡片信息，使用callback异步回调。 246 247**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 248 249**系统能力：** SystemCapability.Ability.Form 250 251**参数：** 252 253| 参数名 | 类型 | 必填 | 说明 | 254| ------ | ------ | ---- | ------- | 255| callback | AsyncCallback<Array<[formInfo.FormInfo](js-apis-app-form-formInfo.md)>> | 是 | 回调函数。返回查询到的卡片信息。 | 256 257**错误码：** 258 259以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[卡片错误码](errorcode-form.md)。 260 261| 错误码ID | 错误信息 | 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**示例：** 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 290获取设备上当前应用程序的卡片信息，并筛选符合条件的信息，使用callback异步回调。 291 292**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 293 294**系统能力：** SystemCapability.Ability.Form 295 296**参数：** 297 298| 参数名 | 类型 | 必填 | 说明 | 299| ------ | ------ | ---- | ------- | 300| filter | [formInfo.FormInfoFilter](js-apis-app-form-formInfo.md#forminfofilter) | 是 | 卡片信息过滤器。 | 301| callback | AsyncCallback<Array<[formInfo.FormInfo](js-apis-app-form-formInfo.md)>> | 是 | 回调函数。返回查询到符合条件的卡片信息。 | 302 303**错误码：** 304 305以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[卡片错误码](errorcode-form.md)。 306 307| 错误码ID | 错误信息 | 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**示例：** 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 341获取设备上当前应用程序的卡片信息，使用Promise异步回调。 342 343**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 344 345**系统能力：** SystemCapability.Ability.Form 346 347**参数：** 348 349| 参数名 | 类型 | 必填 | 说明 | 350| ------ | ------ | ---- | ------- | 351| filter | [formInfo.FormInfoFilter](js-apis-app-form-formInfo.md#forminfofilter) | 否 | 卡片信息过滤器, 默认为空，不进行过滤。 | 352 353**返回值：** 354 355| 类型 | 说明 | 356| :------------ | :---------------------------------- | 357| Promise<Array<[formInfo.FormInfo](js-apis-app-form-formInfo.md)>> | Promise对象。返回查询到符合条件的卡片信息。 | 358 359**错误码：** 360 361以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[卡片错误码](errorcode-form.md)。 362 363| 错误码ID | 错误信息 | 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**示例：** 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 391## formProvider.openFormEditAbility<sup>18+</sup> 392 393openFormEditAbility(abilityName: string, formId: string, isMainPage?: boolean): void 394 395打开卡片编辑页。 396 397**系统能力：** SystemCapability.Ability.Form 398 399**参数：** 400 401| 参数名 | 类型 | 必填 | 说明 | 402| ------ | ------ |----|----------------------------------------------------| 403| abilityName | string | 是 | 编辑页的ability名称。 | 404| formId | string | 是 | 卡片标识。 | 405| isMainPage | boolean | 否 | 是否为主编辑页，true表示是主编辑页，false表示不是主编辑页。<br/>默认值：true。 | 406 407**错误码：** 408 409以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[卡片错误码](errorcode-form.md)。 410 411| 错误码ID | 错误信息 | 412|----------| -------- | 413| 801 | Capability not supported.function openFormEditAbility can not work correctly due to limited device capabilities. | 414| 16500050 | IPC connection error. | 415| 16500100 | Failed to obtain the configuration information. | 416| 16501000 | An internal functional error occurred. | 417| 16501003 | The form cannot be operated by the current application. | 418| 16501007 | Form is not trust. | 419 420**示例：** 421 422```ts 423import { router } from '@kit.ArkUI'; 424 425const TAG: string = 'FormEditDemo-Page] -->'; 426 427@Entry 428@Component 429struct Page { 430 @State message: string = 'Hello World'; 431 432 aboutToAppear(): void { 433 console.log(`${TAG} aboutToAppear.....`); 434 } 435 436 build() { 437 RelativeContainer() { 438 Text(this.message) 439 .id('PageHelloWorld') 440 .fontSize(50) 441 .fontWeight(FontWeight.Bold) 442 .alignRules({ 443 center: { anchor: '__container__', align: VerticalAlign.Top }, 444 middle: { anchor: '__container__', align: HorizontalAlign.Center } 445 }) 446 .onClick(() => { 447 console.log(`${TAG} onClick.....`); 448 formProvider.openFormEditAbility('ability://EntryFormEditAbility', '1386529921'); 449 }) 450 } 451 .height('100%') 452 .width('100%') 453 } 454} 455``` 456 457## formProvider.openFormManager<sup>18+</sup> 458 459openFormManager(want: Want): void 460 461打开卡片管理页面。 462 463**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 464 465**系统能力：** SystemCapability.Ability.Form 466 467**参数：** 468 469| 参数名 | 类型 | 必填 | 说明 | 470|------| ------ | ---- |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 471| want | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | 是 | 打开卡片管理页面的请求中的want参数，需包含以下字段。<br>bundleName: 卡片所属应用的包名。<br>abilityName: 卡片所属的ability名称。<br>parameters:<br>- ohos.extra.param.key.form_dimension: [卡片尺寸](js-apis-app-form-formInfo.md#formInfoformdimension)。<br>- ohos.extra.param.key.form_name: 卡片名称。<br>- ohos.extra.param.key.module_name: 卡片所属的模块名称。 | 472 473**错误码：** 474 475以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[卡片错误码](errorcode-form.md)。 476 477| 错误码ID | 错误信息 | 478| -------- | -------- | 479| 16500050 | IPC connection error. | 480| 16500100 | Failed to obtain the configuration information. | 481| 16501000 | An internal functional error occurred. | 482 483**示例：** 484 485```ts 486import { formProvider } from '@kit.FormKit'; 487import { BusinessError } from '@kit.BasicServicesKit'; 488import { Want } from '@kit.AbilityKit'; 489 490const want: Want = { 491 bundleName: 'com.example.formbutton', 492 abilityName: 'EntryFormAbility', 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.openFormManager(want); 501} catch (error) { 502 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`); 503} 504``` 505 506## formProvider.getPublishedFormInfoById<sup>18+</sup> 507 508getPublishedFormInfoById(formId: string): Promise<formInfo.FormInfo> 509 510获取设备上当前应用程序已经加桌的指定卡片信息，使用Promise异步回调。 511 512**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 513 514**系统能力：** SystemCapability.Ability.Form 515 516**参数：** 517 518| 参数名 | 类型 | 必填 | 说明 | 519| ------ | ------ |----| ------- | 520| formId | string | 是 | 卡片标识。 | 521 522**返回值：** 523 524| 类型 | 说明 | 525|-------------------------------------------------------------------| ---------------------------------- | 526| Promise<[formInfo.FormInfo](js-apis-app-form-formInfo.md#forminfo)> | Promise对象。返回查询到符合条件的卡片信息。 | 527 528**错误码：** 529 530以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[卡片错误码](errorcode-form.md)。 531 532| 错误码ID | 错误信息 | 533| -------- | -------- | 534| 16500050 | IPC connection error. | 535| 16500100 | Failed to obtain the configuration information. | 536| 16501000 | An internal functional error occurred. | 537 538**示例：** 539 540```ts 541import { formInfo, formProvider } from '@kit.FormKit'; 542import { BusinessError } from '@kit.BasicServicesKit'; 543 544const formId: string = '388344236'; 545try { 546 formProvider.getPublishedFormInfoById(formId).then((data: formInfo.FormInfo) => { 547 console.log(`formProvider getPublishedFormInfoById, data: ${JSON.stringify(data)}`); 548 }).catch((error: BusinessError) => { 549 console.error(`promise error, code: ${error.code}, message: ${error.message})`); 550 }); 551} catch (error) { 552 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`); 553} 554``` 555 556## formProvider.getPublishedFormInfos<sup>18+</sup> 557 558getPublishedFormInfos(): Promise<Array<formInfo.FormInfo>> 559 560获取设备上当前应用程序所有已经加桌的卡片信息，使用Promise异步回调。 561 562**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 563 564**系统能力：** SystemCapability.Ability.Form 565 566**返回值：** 567 568| 类型 | 说明 | 569| ------------ | ---------------------------------- | 570| Promise<Array<[formInfo.FormInfo](js-apis-app-form-formInfo.md)>> | Promise对象。返回查询到符合条件的卡片信息。 | 571 572**错误码：** 573 574以下错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 575 576| 错误码ID | 错误信息 | 577| -------- | -------- | 578| 16500050 | IPC connection error. | 579| 16500100 | Failed to obtain the configuration information. | 580| 16501000 | An internal functional error occurred. | 581 582**示例：** 583 584```ts 585import { formInfo, formProvider } from '@kit.FormKit'; 586import { BusinessError } from '@kit.BasicServicesKit'; 587 588try { 589 formProvider.getPublishedFormInfos().then((data: formInfo.FormInfo[]) => { 590 console.log(`formProvider getPublishedFormInfos, data: ${JSON.stringify(data)}`); 591 }).catch((error: BusinessError) => { 592 console.error(`promise error, code: ${error.code}, message: ${error.message})`); 593 }); 594} catch (error) { 595 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`); 596} 597```