1# @ohos.app.form.formProvider (FormProvider) 2 3FormProvider模块提供了卡片提供方相关接口的能力，开发者在开发卡片时，可通过该模块提供接口实现更新卡片，设置卡片更新时间，获取卡片信息，请求发布卡片等。 4 5> **说明：** 6> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 7 8## 导入模块 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 18设置指定卡片的下一次更新时间，使用callback异步回调。 19 20**系统能力：** SystemCapability.Ability.Form 21 22**参数：** 23 24| 参数名 | 类型 | 必填 | 说明 | 25| ------ | ------ | ---- | ------------------------------------- | 26| formId | string | 是 | 卡片标识。 | 27| minute | number | 是 | 指定多久之后更新，单位分钟，大于等于5。 | 28| callback | AsyncCallback<void> | 是 | 回调函数。 | 29 30**错误码：** 31 32| 错误码ID | 错误信息 | 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 43以上错误码的详细介绍请参见[卡片错误码](../errorcodes/errorcode-form.md)。 44 45**示例：** 46 47```ts 48var formId = '12400633174999288'; 49try { 50 formProvider.setFormNextRefreshTime(formId, 5, (error) => { 51 if (error) { 52 console.log('formProvider setFormNextRefreshTime, error:' + JSON.stringify(error)); 53 return; 54 } 55 console.log(`formProvider setFormNextRefreshTime success`); 56 }); 57} catch (error) { 58 console.log('error' + JSON.stringify(error)) 59} 60``` 61 62## setFormNextRefreshTime 63 64setFormNextRefreshTime(formId: string, minute: number): Promise<void> 65 66设置指定卡片的下一次更新时间，使用Promise异步回调。 67 68**系统能力：** SystemCapability.Ability.Form 69 70**参数：** 71 72| 参数名 | 类型 | 必填 | 说明 | 73| ------ | ------ | ---- | ------------------------------------- | 74| formId | string | 是 | 卡片标识。 | 75| minute | number | 是 | 指定多久之后更新，单位分钟，大于等于5。 | 76 77**返回值：** 78 79| 类型 | 说明 | 80| ------------- | ---------------------------------- | 81| Promise\<void> | 无返回结果的Promise对象。 | 82 83**错误码：** 84 85| 错误码ID | 错误信息 | 86| -------- | -------- | 87| 401 | If the input parameter is not valid parameter. | 88| 16500050 | An IPC connection error happened. | 89| 16500060 | A service connection error happened, please try again later. | 90| 16500100 | Failed to obtain the configuration information. | 91| 16501000 | An internal functional error occurred. | 92| 16501001 | The ID of the form to be operated does not exist. | 93| 16501002 | The number of forms exceeds upper bound. | 94| 16501003 | The form can not be operated by the current application. | 95 96以上错误码的详细介绍请参见[卡片错误码](../errorcodes/errorcode-form.md)。 97 98**示例：** 99 100```ts 101var formId = '12400633174999288'; 102try { 103 formProvider.setFormNextRefreshTime(formId, 5).then(() => { 104 console.log('formProvider setFormNextRefreshTime success'); 105 }).catch((error) => { 106 console.log('formProvider setFormNextRefreshTime, error:' + JSON.stringify(error)); 107 }); 108} catch (error) { 109 console.log(`catch err->${JSON.stringify(error)}`); 110} 111``` 112 113## updateForm 114 115updateForm(formId: string, formBindingData: formBindingData.FormBindingData,callback: AsyncCallback<void>): void 116 117更新指定的卡片，使用callback异步回调。 118 119**系统能力：** SystemCapability.Ability.Form 120 121**参数：** 122 123| 参数名 | 类型 | 必填 | 说明 | 124| ------ | ---------------------------------------------------------------------- | ---- | ---------------- | 125| formId | string | 是 | 请求更新的卡片标识。 | 126| formBindingData.FormBindingData | [FormBindingData](js-apis-app-form-formBindingData.md#formbindingdata) | 是 | 用于更新的数据。 | 127| callback | AsyncCallback<void> | 是 | 回调函数。 | 128 129**错误码：** 130 131| 错误码ID | 错误信息 | 132| -------- | -------- | 133| 401 | If the input parameter is not valid parameter. | 134| 16500050 | An IPC connection error happened. | 135| 16500060 | A service connection error happened, please try again later. | 136| 16500100 | Failed to obtain the configuration information. | 137| 16501000 | An internal functional error occurred. | 138| 16501001 | The ID of the form to be operated does not exist. | 139| 16501003 | The form can not be operated by the current application. | 140 141以上错误码的详细介绍请参见[卡片错误码](../errorcodes/errorcode-form.md)。 142 143**示例：** 144 145```ts 146import formBindingData from '@ohos.app.form.formBindingData'; 147 148var formId = '12400633174999288'; 149try { 150 let obj = formBindingData.createFormBindingData({temperature:'22c', time:'22:00'}); 151 formProvider.updateForm(formId, obj, (error) => { 152 if (error) { 153 console.log('formProvider updateForm, error:' + JSON.stringify(error)); 154 return; 155 } 156 console.log(`formProvider updateForm success`); 157 }); 158} catch (error) { 159 console.log(`catch err->${JSON.stringify(error)}`); 160} 161``` 162 163## updateForm 164 165updateForm(formId: string, formBindingData: formBindingData.FormBindingData): Promise<void> 166 167更新指定的卡片，使用Promise异步回调。 168 169**系统能力：** SystemCapability.Ability.Form 170 171**参数：** 172 173| 参数名 | 类型 | 必填 | 说明 | 174| ------ | ---------------------------------------------------------------------- | ---- | ---------------- | 175| formId | string | 是 | 请求更新的卡片标识。 | 176| formBindingData.FormBindingData | [FormBindingData](js-apis-app-form-formBindingData.md#formbindingdata) | 是 | 用于更新的数据。 | 177 178**返回值：** 179 180| 类型 | 说明 | 181| -------------- | ----------------------------------- | 182| Promise\<void> | 无返回结果的Promise对象。 | 183 184**错误码：** 185 186| 错误码ID | 错误信息 | 187| -------- | -------- | 188| 401 | If the input parameter is not valid parameter. | 189| 16500050 | An IPC connection error happened. | 190| 16500060 | A service connection error happened, please try again later. | 191| 16500100 | Failed to obtain the configuration information. | 192| 16501000 | An internal functional error occurred. | 193| 16501001 | The ID of the form to be operated does not exist. | 194| 16501003 | The form can not be operated by the current application. | 195 196以上错误码的详细介绍请参见[卡片错误码](../errorcodes/errorcode-form.md)。 197 198**示例：** 199 200```ts 201import formBindingData from '@ohos.app.form.formBindingData'; 202 203let formId = '12400633174999288'; 204let obj = formBindingData.createFormBindingData({ temperature: '22c', time: '22:00' }); 205try { 206 formProvider.updateForm(formId, obj).then(() => { 207 console.log('formProvider updateForm success'); 208 }).catch((error) => { 209 console.log('formProvider updateForm, error:' + JSON.stringify(error)); 210 }); 211} catch (error) { 212 console.log(`catch err->${JSON.stringify(error)}`); 213} 214``` 215 216## getFormsInfo 217 218getFormsInfo(callback: AsyncCallback<Array<formInfo.FormInfo>>): void 219 220获取设备上当前应用程序的卡片信息，使用callback异步回调。 221 222**系统能力：** SystemCapability.Ability.Form 223 224**参数：** 225 226| 参数名 | 类型 | 必填 | 说明 | 227| ------ | ------ | ---- | ------- | 228| callback | AsyncCallback<Array<[FormInfo](js-apis-app-form-formInfo.md)>> | 是 | 回调函数。返回查询到的卡片信息。 | 229 230**错误码：** 231| 错误码ID | 错误信息 | 232| -------- | -------- | 233| 401 | If the input parameter is not valid parameter. | 234| 16500050 | An IPC connection error happened. | 235| 16500100 | Failed to obtain the configuration information. | 236| 16501000 | An internal functional error occurred. | 237 238以上错误码的详细介绍请参见[卡片错误码](../errorcodes/errorcode-form.md)。 239 240 241**示例：** 242 243```ts 244try { 245 formProvider.getFormsInfo((error, data) => { 246 if (error) { 247 console.log('formProvider getFormsInfo, error:' + JSON.stringify(error)); 248 return; 249 } 250 console.log('formProvider getFormsInfo, data:' + JSON.stringify(data)); 251 }); 252} catch (error) { 253 console.log(`catch err->${JSON.stringify(error)}`); 254} 255``` 256## getFormsInfo 257 258getFormsInfo(filter: formInfo.FormInfoFilter, callback: AsyncCallback<Array<formInfo.FormInfo>>): void 259 260获取设备上当前应用程序的卡片信息，并筛选符合条件的信息，使用callback异步回调。 261 262**系统能力：** SystemCapability.Ability.Form 263 264**参数：** 265 266| 参数名 | 类型 | 必填 | 说明 | 267| ------ | ------ | ---- | ------- | 268| filter | [formInfo.FormInfoFilter](js-apis-app-form-formInfo.md#forminfofilter) | 是 | 卡片信息过滤器。 | 269| callback | AsyncCallback<Array<[FormInfo](js-apis-app-form-formInfo.md)>> | 是 | 回调函数。返回查询到符合条件的卡片信息。 | 270 271**错误码：** 272 273| 错误码ID | 错误信息 | 274| -------- | -------- | 275| 401 | If the input parameter is not valid parameter. | 276| 16500050 | An IPC connection error happened. | 277| 16500100 | Failed to obtain the configuration information. | 278| 16501000 | An internal functional error occurred. | 279 280以上错误码的详细介绍请参见[卡片错误码](../errorcodes/errorcode-form.md)。 281 282**示例：** 283 284```ts 285import formInfo from '@ohos.app.form.formInfo'; 286 287const filter : formInfo.FormInfoFilter = { 288 // get info of forms belong to module entry. 289 moduleName : 'entry' 290}; 291try { 292 formProvider.getFormsInfo(filter, (error, data) => { 293 if (error) { 294 console.log('formProvider getFormsInfo, error:' + JSON.stringify(error)); 295 return; 296 } 297 console.log('formProvider getFormsInfo, data:' + JSON.stringify(data)); 298 }); 299} catch(error) { 300 console.log(`catch err->${JSON.stringify(error)}`); 301} 302``` 303 304## getFormsInfo 305 306getFormsInfo(filter?: formInfo.FormInfoFilter): Promise<Array<formInfo.FormInfo>> 307 308获取设备上当前应用程序的卡片信息，使用Promise异步回调。 309 310**系统能力：** SystemCapability.Ability.Form 311 312**参数：** 313 314| 参数名 | 类型 | 必填 | 说明 | 315| ------ | ------ | ---- | ------- | 316| filter | [formInfo.FormInfoFilter](js-apis-app-form-formInfo.md#forminfofilter) | 否 | 卡片信息过滤器。 | 317 318**返回值：** 319 320| 类型 | 说明 | 321| :------------ | :---------------------------------- | 322| Promise<Array<[FormInfo](js-apis-app-form-formInfo.md)>> | Promise对象。返回查询到符合条件的卡片信息。 | 323 324**错误码：** 325 326| 错误码ID | 错误信息 | 327| -------- | -------- | 328| 401 | If the input parameter is not valid parameter. | 329| 16500050 | An IPC connection error happened. | 330| 16500100 | Failed to obtain the configuration information. | 331| 16501000 | An internal functional error occurred. | 332 333以上错误码的详细介绍请参见[卡片错误码](../errorcodes/errorcode-form.md)。 334 335**示例：** 336 337```ts 338import formInfo from '@ohos.app.form.formInfo'; 339 340const filter : formInfo.FormInfoFilter = { 341 // get info of forms belong to module entry. 342 moduleName : 'entry' 343}; 344try { 345 formProvider.getFormsInfo(filter).then((data) => { 346 console.log('formProvider getFormsInfo, data:' + JSON.stringify(data)); 347 }).catch((error) => { 348 console.log('formProvider getFormsInfo, error:' + JSON.stringify(error)); 349 }); 350} catch (error) { 351 console.log(`catch err->${JSON.stringify(error)}`); 352} 353``` 354 355## requestPublishForm 356 357requestPublishForm(want: Want, formBindingData: formBindingData.FormBindingData, callback: AsyncCallback\<string>): void 358 359请求发布一张卡片到使用方。使用方通常为桌面。 360 361**系统能力：** SystemCapability.Ability.Form 362 363**系统接口**: 此接口为系统接口。 364 365**参数：** 366 367| 参数名 | 类型 | 必填 | 说明 | 368| ------ | ---------------------------------------------------------------------- | ---- | ---------------- | 369| want | [Want](js-apis-application-want.md) | 是 | 发布请求。需包含以下字段。<br>abilityName: 目标卡片ability<br>parameters:<br>'ohos.extra.param.key.form_dimension'<br>'ohos.extra.param.key.form_name'<br>'ohos.extra.param.key.module_name' | 370| formBindingData.FormBindingData | [FormBindingData](js-apis-app-form-formBindingData.md#formbindingdata) | 是 | 创建卡片的数据。 | 371| callback | AsyncCallback<string> | 是 | 回调函数。返回卡片标识。 | 372 373**错误码：** 374 375| 错误码ID | 错误信息 | 376| -------- | -------- | 377| 202 | The application is not a system application. | 378| 401 | If the input parameter is not valid parameter. | 379| 16500050 | An IPC connection error happened. | 380| 16500100 | Failed to obtain the configuration information. | 381| 16501000 | An internal functional error occurred. | 382 383以上错误码的详细介绍请参见[卡片错误码](../errorcodes/errorcode-form.md)。 384 385**示例：** 386 387```ts 388import formBindingData from '@ohos.app.form.formBindingData'; 389 390let 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 let obj = formBindingData.createFormBindingData({temperature:'22c', time:'22:00'}); 400 formProvider.requestPublishForm(want, obj, (error, data) => { 401 if (error) { 402 console.log('formProvider requestPublishForm, error: ' + JSON.stringify(error)); 403 return; 404 } 405 console.log('formProvider requestPublishForm, form ID is: ' + JSON.stringify(data)); 406 }); 407} catch (error) { 408 console.log(`catch err->${JSON.stringify(error)}`); 409} 410``` 411 412## requestPublishForm 413 414requestPublishForm(want: Want, callback: AsyncCallback<string>): void 415 416请求发布一张卡片到使用方。使用方通常为桌面。 417 418**系统能力：** SystemCapability.Ability.Form 419 420**系统接口**: 此接口为系统接口。 421 422**参数：** 423 424| 参数名 | 类型 | 必填 | 说明 | 425| -------- | ----------------------------------- | ---- | ------------------------------------------------------------ | 426| want | [Want](js-apis-application-want.md) | 是 | 发布请求。需包含以下字段。<br>abilityName: 目标卡片ability<br>parameters:<br>'ohos.extra.param.key.form_dimension'<br>'ohos.extra.param.key.form_name'<br>'ohos.extra.param.key.module_name' | 427| callback | AsyncCallback<string> | 是 | 回调函数。返回卡片标识。 | 428 429**错误码：** 430 431| 错误码ID | 错误信息 | 432| -------- | -------- | 433| 202 | The application is not a system application. | 434| 401 | If the input parameter is not valid parameter. | 435| 16500050 | An IPC connection error happened. | 436| 16500100 | Failed to obtain the configuration information. | 437| 16501000 | An internal functional error occurred. | 438 439以上错误码的详细介绍请参见[卡片错误码](../errorcodes/errorcode-form.md)。 440 441**示例：** 442 443```ts 444let want = { 445 abilityName: 'FormAbility', 446 parameters: { 447 'ohos.extra.param.key.form_dimension': 2, 448 'ohos.extra.param.key.form_name': 'widget', 449 'ohos.extra.param.key.module_name': 'entry' 450 } 451}; 452try { 453 formProvider.requestPublishForm(want, (error, data) => { 454 if (error) { 455 console.log('formProvider requestPublishForm, error: ' + JSON.stringify(error)); 456 return; 457 } 458 console.log('formProvider requestPublishForm, form ID is: ' + JSON.stringify(data)); 459 }); 460} catch (error) { 461 console.log(`catch err->${JSON.stringify(error)}`); 462} 463 464``` 465 466## requestPublishForm 467 468requestPublishForm(want: Want, formBindingData?: formBindingData.FormBindingData): Promise<string> 469 470请求发布一张卡片到使用方。使用方通常为桌面。 471 472**系统能力：** SystemCapability.Ability.Form 473 474**系统接口**: 此接口为系统接口。 475 476**参数：** 477 478| 参数名 | 类型 | 必填 | 说明 | 479| --------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 480| want | [Want](js-apis-application-want.md) | 是 | 发布请求。需包含以下字段。<br>abilityName: 目标卡片ability<br>parameters:<br>'ohos.extra.param.key.form_dimension'<br>'ohos.extra.param.key.form_name'<br>'ohos.extra.param.key.module_name' | 481| formBindingData.FormBindingData | [FormBindingData](js-apis-app-form-formBindingData.md#formbindingdata) | 否 | 创建卡片的数据。 | 482 483**返回值：** 484 485| 类型 | 说明 | 486| :------------ | :---------------------------------- | 487| Promise<string> | Promise对象。返回卡片标识。 | 488 489**错误码：** 490 491| 错误码ID | 错误信息 | 492| -------- | -------- | 493| 202 | The application is not a system application. | 494| 401 | If the input parameter is not valid parameter. | 495| 16500050 | An IPC connection error happened. | 496| 16500100 | Failed to obtain the configuration information. | 497| 16501000 | An internal functional error occurred. | 498 499以上错误码的详细介绍请参见[卡片错误码](../errorcodes/errorcode-form.md)。 500 501**示例：** 502 503```ts 504let want = { 505 abilityName: 'FormAbility', 506 parameters: { 507 'ohos.extra.param.key.form_dimension': 2, 508 'ohos.extra.param.key.form_name': 'widget', 509 'ohos.extra.param.key.module_name': 'entry' 510 } 511}; 512try { 513 formProvider.requestPublishForm(want).then((data) => { 514 console.log('formProvider requestPublishForm success, form ID is :' + JSON.stringify(data)); 515 }).catch((error) => { 516 console.log('formProvider requestPublishForm, error: ' + JSON.stringify(error)); 517 }); 518} catch (error) { 519 console.log(`catch err->${JSON.stringify(error)}`); 520} 521``` 522 523## isRequestPublishFormSupported 524 525isRequestPublishFormSupported(callback: AsyncCallback<boolean>): void 526 527查询是否支持发布一张卡片到使用方。 528 529**系统接口**: 此接口为系统接口。 530 531**系统能力：** SystemCapability.Ability.Form 532 533**参数：** 534 535| 参数名 | 类型 | 必填 | 说明 | 536| ------ | ------ | ---- | ------- | 537| callback | AsyncCallback<boolean> | 是 | 回调函数。返回是否支持发布一张卡片到使用方。| 538 539**错误码：** 540 541| 错误码ID | 错误信息 | 542| -------- | -------- | 543| 202 | The application is not a system application. | 544| 401 | If the input parameter is not valid parameter. | 545| 16500050 | An IPC connection error happened. | 546| 16501000 | An internal functional error occurred. | 547 548以上错误码的详细介绍请参见[卡片错误码](../errorcodes/errorcode-form.md)。 549 550**示例：** 551 552```ts 553try { 554 formProvider.isRequestPublishFormSupported((error, isSupported) => { 555 if (error) { 556 console.log('formProvider isRequestPublishFormSupported, error:' + JSON.stringify(error)); 557 } else { 558 if (isSupported) { 559 var want = { 560 abilityName: 'FormAbility', 561 parameters: { 562 'ohos.extra.param.key.form_dimension': 2, 563 'ohos.extra.param.key.form_name': 'widget', 564 'ohos.extra.param.key.module_name': 'entry' 565 } 566 }; 567 try { 568 formProvider.requestPublishForm(want, (error, data) => { 569 if (error) { 570 console.log('formProvider requestPublishForm, error: ' + JSON.stringify(error)); 571 } else { 572 console.log('formProvider requestPublishForm, form ID is: ' + JSON.stringify(data)); 573 } 574 }); 575 } catch (error) { 576 console.log(`catch err->${JSON.stringify(error)}`); 577 } 578 579 } 580 } 581}); 582} catch (error) { 583 console.log(`catch err->${JSON.stringify(error)}`); 584} 585``` 586 587## isRequestPublishFormSupported 588 589isRequestPublishFormSupported(): Promise<boolean> 590 591查询是否支持发布一张卡片到使用方。 592 593**系统接口**: 此接口为系统接口。 594 595**系统能力：** SystemCapability.Ability.Form 596 597**返回值：** 598 599| 类型 | 说明 | 600| :------------ | :---------------------------------- | 601| Promise<boolean> | Promise对象。返回是否支持发布一张卡片到使用方。 | 602 603**错误码：** 604 605| 错误码ID | 错误信息 | 606| -------- | -------- | 607| 202 | The application is not a system application. | 608| 16500050 | An IPC connection error happened. | 609| 16501000 | An internal functional error occurred. | 610 611以上错误码的详细介绍请参见[卡片错误码](../errorcodes/errorcode-form.md)。 612 613**示例：** 614 615```ts 616try { 617 formProvider.isRequestPublishFormSupported().then((isSupported) => { 618 if (isSupported) { 619 var want = { 620 abilityName: 'FormAbility', 621 parameters: { 622 'ohos.extra.param.key.form_dimension': 2, 623 'ohos.extra.param.key.form_name': 'widget', 624 'ohos.extra.param.key.module_name': 'entry' 625 } 626 }; 627 try { 628 formProvider.requestPublishForm(want).then((data) => { 629 console.log('formProvider requestPublishForm success, form ID is :' + JSON.stringify(data)); 630 }).catch((error) => { 631 console.log('formProvider requestPublishForm, error: ' + JSON.stringify(error)); 632 }); 633 } catch (error) { 634 console.log(`catch err->${JSON.stringify(error)}`); 635 } 636 637 } 638 }).catch((error) => { 639 console.log('formProvider isRequestPublishFormSupported, error:' + JSON.stringify(error)); 640 }); 641} catch (error) { 642 console.log(`catch err->${JSON.stringify(error)}`); 643} 644```