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以上错误码的详细介绍请参见[卡片错误码](../errorcodes/errorcode-form.md)。 36 37**示例：** 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 58设置指定卡片的下一次更新时间，使用Promise异步回调。 59 60**系统能力：** SystemCapability.Ability.Form 61 62**参数：** 63 64| 参数名 | 类型 | 必填 | 说明 | 65| ------ | ------ | ---- | ------------------------------------- | 66| formId | string | 是 | 卡片标识。 | 67| minute | number | 是 | 指定多久之后更新，单位分钟，大于等于5。 | 68 69**返回值：** 70 71| 类型 | 说明 | 72| ------------- | ---------------------------------- | 73| Promise\<void> | 无返回结果的Promise对象。 | 74 75**错误码：** 76 77| 错误码ID | 错误信息 | 78| -------- | -------- | 79| 401 | If the input parameter is not valid parameter. | 80以上错误码的详细介绍请参见[卡片错误码](../errorcodes/errorcode-form.md)。 81 82**示例：** 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 101更新指定的卡片，使用callback异步回调。 102 103**系统能力：** SystemCapability.Ability.Form 104 105**参数：** 106 107| 参数名 | 类型 | 必填 | 说明 | 108| ------ | ---------------------------------------------------------------------- | ---- | ---------------- | 109| formId | string | 是 | 请求更新的卡片标识。 | 110| formBindingData.FormBindingData | [FormBindingData](js-apis-app-form-formBindingData.md#formbindingdata) | 是 | 用于更新的数据。 | 111| callback | AsyncCallback<void> | 是 | 回调函数。 | 112 113**错误码：** 114 115| 错误码ID | 错误信息 | 116| -------- | -------- | 117| 401 | If the input parameter is not valid parameter. | 118以上错误码的详细介绍请参见[卡片错误码](../errorcodes/errorcode-form.md)。 119 120**示例：** 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 143更新指定的卡片，使用Promise异步回调。 144 145**系统能力：** SystemCapability.Ability.Form 146 147**参数：** 148 149| 参数名 | 类型 | 必填 | 说明 | 150| ------ | ---------------------------------------------------------------------- | ---- | ---------------- | 151| formId | string | 是 | 请求更新的卡片标识。 | 152| formBindingData.FormBindingData | [FormBindingData](js-apis-app-form-formBindingData.md#formbindingdata) | 是 | 用于更新的数据。 | 153 154**返回值：** 155 156| 类型 | 说明 | 157| -------------- | ----------------------------------- | 158| Promise\<void> | 无返回结果的Promise对象。 | 159 160**错误码：** 161 162| 错误码ID | 错误信息 | 163| -------- | -------- | 164| 401 | If the input parameter is not valid parameter. | 165以上错误码的详细介绍请参见[卡片错误码](../errorcodes/errorcode-form.md)。 166 167**示例：** 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 188获取设备上当前应用程序的卡片信息，使用callback异步回调。 189 190**系统能力：** SystemCapability.Ability.Form 191 192**参数：** 193 194| 参数名 | 类型 | 必填 | 说明 | 195| ------ | ------ | ---- | ------- | 196| callback | AsyncCallback<Array<[FormInfo](js-apis-app-form-formInfo.md)>> | 是 | 回调函数。返回查询到的卡片信息。 | 197 198**错误码：** 199 200| 错误码ID | 错误信息 | 201| -------- | -------- | 202| 401 | If the input parameter is not valid parameter. | 203以上错误码的详细介绍请参见[卡片错误码](../errorcodes/errorcode-form.md)。 204 205 206**示例：** 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 225获取设备上当前应用程序的卡片信息，并筛选符合条件的信息，使用callback异步回调。 226 227**系统能力：** SystemCapability.Ability.Form 228 229**参数：** 230 231| 参数名 | 类型 | 必填 | 说明 | 232| ------ | ------ | ---- | ------- | 233| filter | [formInfo.FormInfoFilter](js-apis-app-form-formInfo.md#forminfofilter) | 是 | 卡片信息过滤器。 | 234| callback | AsyncCallback<Array<[FormInfo](js-apis-app-form-formInfo.md)>> | 是 | 回调函数。返回查询到符合条件的卡片信息。 | 235 236**错误码：** 237 238| 错误码ID | 错误信息 | 239| -------- | -------- | 240| 401 | If the input parameter is not valid parameter. | 241以上错误码的详细介绍请参见[卡片错误码](../errorcodes/errorcode-form.md)。 242 243**示例：** 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 269获取设备上当前应用程序的卡片信息，使用Promise异步回调。 270 271**系统能力：** SystemCapability.Ability.Form 272 273**参数：** 274 275| 参数名 | 类型 | 必填 | 说明 | 276| ------ | ------ | ---- | ------- | 277| filter | [formInfo.FormInfoFilter](js-apis-app-form-formInfo.md#forminfofilter) | 否 | 卡片信息过滤器。 | 278 279**返回值：** 280 281| 类型 | 说明 | 282| :------------ | :---------------------------------- | 283| Promise<Array<[FormInfo](js-apis-app-form-formInfo.md)>> | Promise对象。返回查询到符合条件的卡片信息。 | 284 285**错误码：** 286 287| 错误码ID | 错误信息 | 288| -------- | -------- | 289| 401 | If the input parameter is not valid parameter. | 290以上错误码的详细介绍请参见[卡片错误码](../errorcodes/errorcode-form.md)。 291 292**示例：** 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 316请求发布一张卡片到使用方。使用方通常为桌面。 317 318**系统能力：** SystemCapability.Ability.Form 319 320**系统接口**: 此接口为系统接口。 321 322**参数：** 323 324| 参数名 | 类型 | 必填 | 说明 | 325| ------ | ---------------------------------------------------------------------- | ---- | ---------------- | 326| 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' | 327| formBindingData.FormBindingData | [FormBindingData](js-apis-app-form-formBindingData.md#formbindingdata) | 是 | 创建卡片的数据。 | 328| callback | AsyncCallback<string> | 是 | 回调函数。返回卡片标识。 | 329 330**错误码：** 331 332| 错误码ID | 错误信息 | 333| -------- | -------- | 334| 401 | If the input parameter is not valid parameter. | 335以上错误码的详细介绍请参见[卡片错误码](../errorcodes/errorcode-form.md)。 336 337**示例：** 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 367请求发布一张卡片到使用方。使用方通常为桌面。 368 369**系统能力：** SystemCapability.Ability.Form 370 371**系统接口**: 此接口为系统接口。 372 373**参数：** 374 375| 参数名 | 类型 | 必填 | 说明 | 376| -------- | ----------------------------------- | ---- | ------------------------------------------------------------ | 377| 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' | 378| callback | AsyncCallback<string> | 是 | 回调函数。返回卡片标识。 | 379 380**错误码：** 381 382| 错误码ID | 错误信息 | 383| -------- | -------- | 384| 401 | If the input parameter is not valid parameter. | 385以上错误码的详细介绍请参见[卡片错误码](../errorcodes/errorcode-form.md)。 386 387**示例：** 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 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| formBindingData.FormBindingData | [FormBindingData](js-apis-app-form-formBindingData.md#formbindingdata) | 否 | 创建卡片的数据。 | 428 429**返回值：** 430 431| 类型 | 说明 | 432| :------------ | :---------------------------------- | 433| Promise<string> | Promise对象。返回卡片标识。 | 434 435**错误码：** 436 437| 错误码ID | 错误信息 | 438| -------- | -------- | 439| 401 | If the input parameter is not valid parameter. | 440以上错误码的详细介绍请参见[卡片错误码](../errorcodes/errorcode-form.md)。 441 442**示例：** 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 468查询是否支持发布一张卡片到使用方。 469 470**系统接口**: 此接口为系统接口。 471 472**系统能力：** SystemCapability.Ability.Form 473 474**参数：** 475 476| 参数名 | 类型 | 必填 | 说明 | 477| ------ | ------ | ---- | ------- | 478| callback | AsyncCallback<boolean> | 是 | 回调函数。返回是否支持发布一张卡片到使用方。| 479 480**示例：** 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 521查询是否支持发布一张卡片到使用方。 522 523**系统接口**: 此接口为系统接口。 524 525**系统能力：** SystemCapability.Ability.Form 526 527**返回值：** 528 529| 类型 | 说明 | 530| :------------ | :---------------------------------- | 531| Promise<boolean> | Promise对象。返回是否支持发布一张卡片到使用方。 | 532 533**示例：** 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```