1# @ohos.app.form.formProvider (formProvider) 2<!--Kit: Form Kit--> 3<!--Subsystem: Ability--> 4<!--Owner: @cx983299475--> 5<!--Designer: @xueyulong--> 6<!--Tester: @chenmingze--> 7<!--Adviser: @Brilliantry_Rui--> 8 9formProvider模块提供了获取卡片信息、更新卡片、设置卡片更新时间等能力。 10 11> **说明：** 12> 13> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 14 15## 导入模块 16 17```ts 18import { formProvider } from '@kit.FormKit'; 19``` 20 21## formProvider.setFormNextRefreshTime 22 23setFormNextRefreshTime(formId: string, minute: number, callback: AsyncCallback<void>): void 24 25设置指定卡片的下一次更新时间，使用callback异步回调。 26 27**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 28 29**系统能力：** SystemCapability.Ability.Form 30 31**参数：** 32 33| 参数名 | 类型 | 必填 | 说明 | 34| ------ | ------ | ---- | ------------------------------------- | 35| formId | string | 是 | 卡片标识。 | 36| minute | number | 是 | 指定卡片多久之后更新，取值范围：大于等于5，单位：min。 | 37| callback | AsyncCallback<void> | 是 | 回调函数。 | 38 39**错误码：** 40 41以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[卡片错误码](errorcode-form.md)。 42 43| 错误码ID | 错误信息 | 44| -------- | -------- | 45| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 46| 16500050 | IPC connection error. | 47| 16500060 | Service connection error. | 48| 16500100 | Failed to obtain the configuration information. | 49| 16501000 | An internal functional error occurred. | 50| 16501001 | The ID of the form to be operated does not exist. | 51| 16501002 | The number of forms exceeds the maximum allowed. | 52| 16501003 | The form cannot be operated by the current application. | 53 54**示例：** 55 56```ts 57import { formProvider } from '@kit.FormKit'; 58import { BusinessError } from '@kit.BasicServicesKit'; 59 60let formId: string = '12400633174999288'; 61try { 62 formProvider.setFormNextRefreshTime(formId, 5, (error: BusinessError) => { 63 if (error) { 64 console.error(`callback error, code: ${error.code}, message: ${error.message})`); 65 return; 66 } 67 console.log(`formProvider setFormNextRefreshTime success`); 68 }); 69} catch (error) { 70 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`); 71} 72``` 73 74## formProvider.setFormNextRefreshTime 75 76setFormNextRefreshTime(formId: string, minute: number): Promise<void> 77 78设置指定卡片的下一次更新时间，使用Promise异步回调。 79 80**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 81 82**系统能力：** SystemCapability.Ability.Form 83 84**参数：** 85 86| 参数名 | 类型 | 必填 | 说明 | 87| ------ | ------ | ---- | ------------------------------------- | 88| formId | string | 是 | 卡片标识。 | 89| minute | number | 是 | 指定卡片多久之后更新，取值范围：大于等于5，单位：min。 | 90 91**返回值：** 92 93| 类型 | 说明 | 94| ------------- | ---------------------------------- | 95| Promise\<void> | 无返回结果的Promise对象。 | 96 97**错误码：** 98 99以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[卡片错误码](errorcode-form.md)。 100 101| 错误码ID | 错误信息 | 102| -------- | -------- | 103| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 104| 16500050 | IPC connection error. | 105| 16500060 | Service connection error. | 106| 16500100 | Failed to obtain the configuration information. | 107| 16501000 | An internal functional error occurred. | 108| 16501001 | The ID of the form to be operated does not exist. | 109| 16501002 | The number of forms exceeds the maximum allowed. | 110| 16501003 | The form cannot be operated by the current application. | 111 112**示例：** 113 114```ts 115import { formProvider } from '@kit.FormKit'; 116import { BusinessError } from '@kit.BasicServicesKit'; 117 118let formId: string = '12400633174999288'; 119try { 120 formProvider.setFormNextRefreshTime(formId, 5).then(() => { 121 console.log(`formProvider setFormNextRefreshTime success`); 122 }).catch((error: BusinessError) => { 123 console.error(`promise error, code: ${error.code}, message: ${error.message})`); 124 }); 125} catch (error) { 126 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`); 127} 128``` 129 130## formProvider.updateForm 131 132updateForm(formId: string, formBindingData: formBindingData.FormBindingData,callback: AsyncCallback<void>): void 133 134更新指定的卡片，使用callback异步回调。 135 136**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 137 138**系统能力：** SystemCapability.Ability.Form 139 140**参数：** 141 142| 参数名 | 类型 | 必填 | 说明 | 143| ------ | ---------------------------------------------------------------------- | ---- | ---------------- | 144| formId | string | 是 | 请求更新的卡片标识。 | 145| formBindingData | [formBindingData.FormBindingData](js-apis-app-form-formBindingData.md#formbindingdata) | 是 | 用于更新的数据。 | 146| callback | AsyncCallback<void> | 是 | 回调函数。 | 147 148**错误码：** 149 150以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[卡片错误码](errorcode-form.md)。 151 152| 错误码ID | 错误信息 | 153| -------- | -------- | 154| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 155| 16500050 | IPC connection error. | 156| 16500060 | Service connection error. | 157| 16500100 | Failed to obtain the configuration information. | 158| 16501000 | An internal functional error occurred. | 159| 16501001 | The ID of the form to be operated does not exist. | 160| 16501003 | The form cannot be operated by the current application. | 161 162**示例：** 163 164```ts 165import { formBindingData, formProvider } from '@kit.FormKit'; 166import { BusinessError } from '@kit.BasicServicesKit'; 167 168let formId: string = '12400633174999288'; 169try { 170 let param: Record<string, string> = { 171 'temperature': '22c', 172 'time': '22:00' 173 } 174 let obj: formBindingData.FormBindingData = formBindingData.createFormBindingData(param); 175 formProvider.updateForm(formId, obj, (error: BusinessError) => { 176 if (error) { 177 console.error(`callback error, code: ${error.code}, message: ${error.message})`); 178 return; 179 } 180 console.log(`formProvider updateForm success`); 181 }); 182} catch (error) { 183 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`); 184} 185``` 186 187## formProvider.updateForm 188 189updateForm(formId: string, formBindingData: formBindingData.FormBindingData): Promise<void> 190 191更新指定的卡片，使用Promise异步回调。 192 193**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 194 195**系统能力：** SystemCapability.Ability.Form 196 197**参数：** 198 199| 参数名 | 类型 | 必填 | 说明 | 200| ------ | ---------------------------------------------------------------------- | ---- | ---------------- | 201| formId | string | 是 | 请求更新的卡片标识。 | 202| formBindingData | [formBindingData.FormBindingData](js-apis-app-form-formBindingData.md#formbindingdata) | 是 | 用于更新的数据。 | 203 204**返回值：** 205 206| 类型 | 说明 | 207| -------------- | ----------------------------------- | 208| Promise\<void> | 无返回结果的Promise对象。 | 209 210**错误码：** 211 212以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[卡片错误码](errorcode-form.md)。 213 214| 错误码ID | 错误信息 | 215| -------- | -------- | 216| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 217| 16500050 | IPC connection error. | 218| 16500060 | Service connection error. | 219| 16500100 | Failed to obtain the configuration information. | 220| 16501000 | An internal functional error occurred. | 221| 16501001 | The ID of the form to be operated does not exist. | 222| 16501003 | The form cannot be operated by the current application. | 223 224**示例：** 225 226```ts 227import { formBindingData, formProvider } from '@kit.FormKit'; 228import { BusinessError } from '@kit.BasicServicesKit'; 229 230let formId: string = '12400633174999288'; 231let param: Record<string, string> = { 232 'temperature': '22c', 233 'time': '22:00' 234} 235let obj: formBindingData.FormBindingData = formBindingData.createFormBindingData(param); 236try { 237 formProvider.updateForm(formId, obj).then(() => { 238 console.log(`formProvider updateForm success`); 239 }).catch((error: BusinessError) => { 240 console.error(`promise error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`); 241 }); 242} catch (error) { 243 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`); 244} 245``` 246 247## formProvider.getFormsInfo 248 249getFormsInfo(callback: AsyncCallback<Array<formInfo.FormInfo>>): void 250 251获取设备上当前应用程序的卡片信息，使用callback异步回调。 252 253**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 254 255**系统能力：** SystemCapability.Ability.Form 256 257**参数：** 258 259| 参数名 | 类型 | 必填 | 说明 | 260| ------ | ------ | ---- | ------- | 261| callback | AsyncCallback<Array<[formInfo.FormInfo](js-apis-app-form-formInfo.md)>> | 是 | 回调函数。返回查询到的卡片信息。 | 262 263**错误码：** 264 265以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[卡片错误码](errorcode-form.md)。 266 267| 错误码ID | 错误信息 | 268| -------- | -------- | 269| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 270| 16500050 | IPC connection error. | 271| 16500100 | Failed to obtain the configuration information. | 272| 16501000 | An internal functional error occurred. | 273 274**示例：** 275 276```ts 277import { formProvider } from '@kit.FormKit'; 278import { BusinessError } from '@kit.BasicServicesKit'; 279 280try { 281 formProvider.getFormsInfo((error, data) => { 282 if (error) { 283 console.error(`callback error, code: ${error.code}, message: ${error.message})`); 284 return; 285 } 286 console.log(`formProvider getFormsInfo, data: ${JSON.stringify(data)}`); 287 }); 288} catch (error) { 289 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`); 290} 291``` 292## formProvider.getFormsInfo 293 294getFormsInfo(filter: formInfo.FormInfoFilter, callback: AsyncCallback<Array<formInfo.FormInfo>>): void 295 296获取设备上当前应用程序的卡片信息，并筛选符合条件的信息，使用callback异步回调。 297 298**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 299 300**系统能力：** SystemCapability.Ability.Form 301 302**参数：** 303 304| 参数名 | 类型 | 必填 | 说明 | 305| ------ | ------ | ---- | ------- | 306| filter | [formInfo.FormInfoFilter](js-apis-app-form-formInfo.md#forminfofilter) | 是 | 卡片信息过滤器。 | 307| callback | AsyncCallback<Array<[formInfo.FormInfo](js-apis-app-form-formInfo.md)>> | 是 | 回调函数。返回查询到符合条件的卡片信息。 | 308 309**错误码：** 310 311以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[卡片错误码](errorcode-form.md)。 312 313| 错误码ID | 错误信息 | 314| -------- | -------- | 315| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 316| 16500050 | IPC connection error. | 317| 16500100 | Failed to obtain the configuration information. | 318| 16501000 | An internal functional error occurred. | 319 320**示例：** 321 322```ts 323import { formInfo, formProvider } from '@kit.FormKit'; 324import { BusinessError } from '@kit.BasicServicesKit'; 325 326const filter: formInfo.FormInfoFilter = { 327 // get info of forms belong to module entry. 328 moduleName: 'entry' 329}; 330try { 331 formProvider.getFormsInfo(filter, (error, data) => { 332 if (error) { 333 console.error(`callback error, code: ${error.code}, message: ${error.message})`); 334 return; 335 } 336 console.log(`formProvider getFormsInfo, data: ${JSON.stringify(data)}`); 337 }); 338} catch (error) { 339 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`); 340} 341``` 342 343## formProvider.getFormsInfo 344 345getFormsInfo(filter?: formInfo.FormInfoFilter): Promise<Array<formInfo.FormInfo>> 346 347获取设备上当前应用程序的卡片信息，使用Promise异步回调。 348 349**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 350 351**系统能力：** SystemCapability.Ability.Form 352 353**参数：** 354 355| 参数名 | 类型 | 必填 | 说明 | 356| ------ | ------ | ---- | ------- | 357| filter | [formInfo.FormInfoFilter](js-apis-app-form-formInfo.md#forminfofilter) | 否 | 卡片信息过滤器, 默认为空，不进行过滤。 | 358 359**返回值：** 360 361| 类型 | 说明 | 362| :------------ | :---------------------------------- | 363| Promise<Array<[formInfo.FormInfo](js-apis-app-form-formInfo.md)>> | Promise对象。返回查询到符合条件的卡片信息。 | 364 365**错误码：** 366 367以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[卡片错误码](errorcode-form.md)。 368 369| 错误码ID | 错误信息 | 370| -------- | -------- | 371| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 372| 16500050 | IPC connection error. | 373| 16500100 | Failed to obtain the configuration information. | 374| 16501000 | An internal functional error occurred. | 375 376**示例：** 377 378```ts 379import { formInfo, formProvider } from '@kit.FormKit'; 380import { BusinessError } from '@kit.BasicServicesKit'; 381 382const filter: formInfo.FormInfoFilter = { 383 // get info of forms belong to module entry. 384 moduleName: 'entry' 385}; 386try { 387 formProvider.getFormsInfo(filter).then((data: formInfo.FormInfo[]) => { 388 console.log(`formProvider getFormsInfo, data: ${JSON.stringify(data)}`); 389 }).catch((error: BusinessError) => { 390 console.error(`promise error, code: ${error.code}, message: ${error.message})`); 391 }); 392} catch (error) { 393 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`); 394} 395``` 396 397## formProvider.openFormEditAbility<sup>18+</sup> 398 399openFormEditAbility(abilityName: string, formId: string, isMainPage?: boolean): void 400 401打开卡片编辑页。 402 403**系统能力：** SystemCapability.Ability.Form 404 405**参数：** 406 407| 参数名 | 类型 | 必填 | 说明 | 408| ------ | ------ |----|----------------------------------------------------| 409| abilityName | string | 是 | 编辑页的ability名称。 | 410| formId | string | 是 | 卡片标识。 | 411| isMainPage | boolean | 否 | 是否为主编辑页，true表示是主编辑页，false表示不是主编辑页。<br/>默认值：true。 | 412 413**错误码：** 414 415以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[卡片错误码](errorcode-form.md)。 416 417| 错误码ID | 错误信息 | 418|----------| -------- | 419| 801 | Capability not supported.function openFormEditAbility can not work correctly due to limited device capabilities. | 420| 16500050 | IPC connection error. | 421| 16500100 | Failed to obtain the configuration information. | 422| 16501000 | An internal functional error occurred. | 423| 16501003 | The form cannot be operated by the current application. | 424| 16501007 | Form is not trust. | 425 426**示例：** 427 428```ts 429import { router } from '@kit.ArkUI'; 430 431const TAG: string = 'FormEditDemo-Page] -->'; 432 433@Entry 434@Component 435struct Page { 436 @State message: string = 'Hello World'; 437 438 aboutToAppear(): void { 439 console.log(`${TAG} aboutToAppear.....`); 440 } 441 442 build() { 443 RelativeContainer() { 444 Text(this.message) 445 .id('PageHelloWorld') 446 .fontSize(50) 447 .fontWeight(FontWeight.Bold) 448 .alignRules({ 449 center: { anchor: '__container__', align: VerticalAlign.Top }, 450 middle: { anchor: '__container__', align: HorizontalAlign.Center } 451 }) 452 .onClick(() => { 453 console.log(`${TAG} onClick.....`); 454 formProvider.openFormEditAbility('ability://EntryFormEditAbility', '1386529921'); 455 }) 456 } 457 .height('100%') 458 .width('100%') 459 } 460} 461``` 462 463## formProvider.openFormManager<sup>18+</sup> 464 465openFormManager(want: Want): void 466 467打开卡片管理页面。 468 469**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 470 471**系统能力：** SystemCapability.Ability.Form 472 473**参数：** 474 475| 参数名 | 类型 | 必填 | 说明 | 476|------| ------ | ---- |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 477| 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#formdimension)。<br>- ohos.extra.param.key.form_name: 卡片名称。<br>- ohos.extra.param.key.module_name: 卡片所属的模块名称。 | 478 479**错误码：** 480 481以下错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 482 483| 错误码ID | 错误信息 | 484| -------- | -------- | 485| 16500050 | IPC connection error. | 486| 16500100 | Failed to obtain the configuration information. | 487| 16501000 | An internal functional error occurred. | 488 489**示例：** 490 491```ts 492import { formProvider } from '@kit.FormKit'; 493import { BusinessError } from '@kit.BasicServicesKit'; 494import { Want } from '@kit.AbilityKit'; 495 496const want: Want = { 497 bundleName: 'com.example.formbutton', 498 abilityName: 'EntryFormAbility', 499 parameters: { 500 'ohos.extra.param.key.form_dimension': 2, 501 'ohos.extra.param.key.form_name': 'widget', 502 'ohos.extra.param.key.module_name': 'entry' 503 }, 504}; 505try { 506 formProvider.openFormManager(want); 507} catch (error) { 508 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`); 509} 510``` 511 512## formProvider.getPublishedFormInfoById<sup>(deprecated)</sup> 513 514getPublishedFormInfoById(formId: string): Promise<formInfo.FormInfo> 515 516获取设备上当前应用程序已经加桌的指定卡片信息，使用Promise异步回调。 517 518**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 519 520> **说明：** 521> 522> 该字段从API version 18开始支持，从API version 20开始废弃，建议使用[getPublishedRunningFormInfoById](#formprovidergetpublishedrunningforminfobyid20)替代。 523 524**系统能力：** SystemCapability.Ability.Form 525 526**参数：** 527 528| 参数名 | 类型 | 必填 | 说明 | 529| ------ | ------ |----| ------- | 530| formId | string | 是 | 卡片标识。 | 531 532**返回值：** 533 534| 类型 | 说明 | 535|-------------------------------------------------------------------| ---------------------------------- | 536| Promise<[formInfo.FormInfo](js-apis-app-form-formInfo.md#forminfo)> | Promise对象。返回查询到符合条件的卡片信息。 | 537 538**错误码：** 539 540以下错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 541 542| 错误码ID | 错误信息 | 543| -------- | -------- | 544| 16500050 | IPC connection error. | 545| 16500100 | Failed to obtain the configuration information. | 546| 16501000 | An internal functional error occurred. | 547 548**示例：** 549 550```ts 551import { formInfo, formProvider } from '@kit.FormKit'; 552import { BusinessError } from '@kit.BasicServicesKit'; 553 554const formId: string = '388344236'; 555try { 556 formProvider.getPublishedFormInfoById(formId).then((data: formInfo.FormInfo) => { 557 console.log(`formProvider getPublishedFormInfoById, data: ${JSON.stringify(data)}`); 558 }).catch((error: BusinessError) => { 559 console.error(`promise error, code: ${error.code}, message: ${error.message})`); 560 }); 561} catch (error) { 562 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`); 563} 564``` 565 566## formProvider.getPublishedFormInfos<sup>(deprecated)</sup> 567 568getPublishedFormInfos(): Promise<Array<formInfo.FormInfo>> 569 570获取设备上当前应用程序所有已经加桌的卡片信息，使用Promise异步回调。 571 572**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 573 574> **说明：** 575> 576> 该字段从API version 18开始支持，从API version 20开始废弃，建议使用[getPublishedRunningFormInfos](#formprovidergetpublishedrunningforminfos20)替代。 577 578**系统能力：** SystemCapability.Ability.Form 579 580**返回值：** 581 582| 类型 | 说明 | 583| ------------ | ---------------------------------- | 584| Promise<Array<[formInfo.FormInfo](js-apis-app-form-formInfo.md)>> | Promise对象。返回查询到符合条件的卡片信息。 | 585 586**错误码：** 587 588以下错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 589 590| 错误码ID | 错误信息 | 591| -------- | -------- | 592| 16500050 | IPC connection error. | 593| 16500100 | Failed to obtain the configuration information. | 594| 16501000 | An internal functional error occurred. | 595 596**示例：** 597 598```ts 599import { formInfo, formProvider } from '@kit.FormKit'; 600import { BusinessError } from '@kit.BasicServicesKit'; 601 602try { 603 formProvider.getPublishedFormInfos().then((data: formInfo.FormInfo[]) => { 604 console.log(`formProvider getPublishedFormInfos, data: ${JSON.stringify(data)}`); 605 }).catch((error: BusinessError) => { 606 console.error(`promise error, code: ${error.code}, message: ${error.message})`); 607 }); 608} catch (error) { 609 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`); 610} 611``` 612 613## formProvider.requestOverflow<sup>20+</sup> 614 615requestOverflow(formId: string, overflowInfo: formInfo.OverflowInfo): Promise<void> 616 617卡片提供方发起互动卡片动效请求，只针对[场景动效类型互动卡片](../../form/arkts-ui-widget-configuration.md#sceneanimationparams标签)生效，使用Promise异步回调。 618 619**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 620 621**系统能力：** SystemCapability.Ability.Form 622 623**参数：** 624 625| 参数名 | 类型 | 必填 | 说明 | 626| ------ |--------------------------------------------------------------------| ---- |-----------| 627| formId | string | 是 | 卡片id标识。| 628| overflowInfo | [formInfo.OverflowInfo](js-apis-app-form-formInfo.md#overflowinfo20) | 是 | 动效请求参数信息。| 629 630**返回值：** 631 632| 类型 | 说明 | 633| -------- | -------- | 634| Promise<void> | 无返回结果的Promise对象。 | 635 636**错误码：** 637 638以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[卡片错误码](errorcode-form.md)。 639 640| 错误码ID | 错误信息 | 641| -------- | -------- | 642| 801 | Capability not supported.function requestOverflow can not work correctly due to limited device capabilities. | 643| 16500050 | IPC connection error. | 644| 16500060 | Service connection error. | 645| 16500100 | Failed to obtain the configuration information. | 646| 16501000 | An internal functional error occurred. | 647| 16501001 | The ID of the form to be operated does not exist. | 648| 16501003 | The form cannot be operated by the current application. | 649| 16501011 | The form can not support this operation. | 650 651**示例：** 652 653```ts 654import { formInfo, formProvider } from '@kit.FormKit'; 655import { BusinessError } from '@kit.BasicServicesKit'; 656 657let formId: string = '12400633174999288'; 658let overflowInfo: formInfo.OverflowInfo = { 659 area: { 660 left: -10, 661 top: -10, 662 width: 180, 663 height: 180 664 }, 665 duration: 1000, 666 useDefaultAnimation: false, 667}; 668 669try { 670 formProvider.requestOverflow(formId, overflowInfo).then(() => { 671 console.info('requestOverflow succeed.'); 672 }).catch((error: BusinessError) => { 673 console.error(`promise error, code: ${error.code}, message: ${error.message})`); 674 }); 675} catch (error) { 676 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`); 677} 678``` 679 680## formProvider.cancelOverflow<sup>20+</sup> 681 682cancelOverflow(formId: string): Promise<void> 683 684卡片提供方发起取消互动卡片动效请求，只针对[场景动效类型互动卡片](../../form/arkts-ui-widget-configuration.md#sceneanimationparams标签)生效，使用Promise异步回调。 685 686**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 687 688**系统能力：** SystemCapability.Ability.Form 689 690**参数：** 691 692| 参数名 | 类型 | 必填 | 说明 | 693| ------ | ------ | ---- |-------| 694| formId | string | 是 | 卡片id。| 695 696**返回值：** 697 698| 类型 | 说明 | 699| -------- | -------- | 700| Promise<void> | 无返回结果的Promise对象。 | 701 702**错误码：** 703 704以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[卡片错误码](errorcode-form.md)。 705 706| 错误码ID | 错误信息 | 707| -------- | -------- | 708| 801 | Capability not supported.function cancelOverflow can not work correctly due to limited device capabilities. | 709| 16500050 | IPC connection error. | 710| 16500060 | Service connection error. | 711| 16500100 | Failed to obtain the configuration information. | 712| 16501000 | An internal functional error occurred. | 713| 16501001 | The ID of the form to be operated does not exist. | 714| 16501003 | The form cannot be operated by the current application. | 715| 16501011 | The form can not support this operation. | 716 717**示例：** 718 719```ts 720import { formProvider } from '@kit.FormKit'; 721import { BusinessError } from '@kit.BasicServicesKit'; 722 723let formId: string = '12400633174999288'; 724 725try { 726 formProvider.cancelOverflow(formId).then(() => { 727 console.info('cancelOverflow succeed.'); 728 }).catch((error: BusinessError) => { 729 console.error(`promise error, code: ${error.code}, message: ${error.message})`); 730 }); 731} catch (error) { 732 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`); 733} 734``` 735 736## formProvider.getFormRect<sup>20+</sup> 737 738getFormRect(formId: string): Promise<formInfo.Rect> 739 740查询卡片位置、尺寸，使用Promise异步回调。 741 742**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 743 744**系统能力：** SystemCapability.Ability.Form 745 746**参数：** 747 748| 参数名 | 类型 | 必填 | 说明 | 749| ------ |-------------| ---- |-----------| 750| formId | string | 是 | 卡片id标识。| 751 752**返回值：** 753 754| 类型 | 说明 | 755| -------- | -------- | 756| Promise<[formInfo.Rect](js-apis-app-form-formInfo.md#rect20)> | Promise对象，返回卡片相对屏幕左上角的的位置信息和卡片尺寸信息，单位vp。 | 757 758**错误码：** 759 760以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[卡片错误码](errorcode-form.md)。 761 762| 错误码ID | 错误信息 | 763| -------- | -------- | 764| 801 | Capability not supported.function getFormRect can not work correctly due to limited device capabilities. | 765| 16500050 | IPC connection error. | 766| 16500060 | Service connection error. | 767| 16500100 | Failed to obtain the configuration information. | 768| 16501000 | An internal functional error occurred. | 769| 16501001 | The ID of the form to be operated does not exist. | 770| 16501003 | The form cannot be operated by the current application. | 771 772**示例：** 773 774```ts 775import { formInfo, formProvider } from '@kit.FormKit'; 776import { BusinessError } from '@kit.BasicServicesKit'; 777 778let formId: string = '12400633174999288'; 779 780try { 781 formProvider.getFormRect(formId).then((data: formInfo.Rect) => { 782 console.info(`getFormRect succeed, data: ${JSON.stringify(data)}`); 783 }); 784} catch (error) { 785 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`); 786} 787``` 788 789## formProvider.getPublishedRunningFormInfoById<sup>20+</sup> 790 791getPublishedRunningFormInfoById(formId: string): Promise<formInfo.RunningFormInfo> 792 793获取当前应用已加桌卡片中指定的卡片信息，使用Promise异步回调。 794 795**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 796 797**系统能力：** SystemCapability.Ability.Form 798 799**参数：** 800 801| 参数名 | 类型 | 必填 | 说明 | 802| ------ | ------ |----| ------- | 803| formId | string | 是 | 卡片标识。 | 804 805**返回值：** 806 807| 类型 | 说明 | 808|-------------------------------------------------------------------| ---------------------------------- | 809| Promise<[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md#runningforminfo20)> | Promise对象。返回符合条件的卡片信息，包括卡片名称、尺寸等。 | 810 811**错误码：** 812 813以下错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 814 815| 错误码ID | 错误信息 | 816| -------- | -------- | 817| 16500050 | IPC connection error. | 818| 16500100 | Failed to obtain the configuration information. | 819| 16501000 | An internal functional error occurred. | 820| 16501001 | The ID of the form to be operated does not exist. | 821| 16501003 | The form cannot be operated by the current application. | 822 823 824**示例：** 825 826```ts 827import { formInfo, formProvider } from '@kit.FormKit'; 828import { BusinessError } from '@kit.BasicServicesKit'; 829 830const formId: string = '388344236'; 831 832try { 833 formProvider.getPublishedRunningFormInfoById(formId).then((data: formInfo.RunningFormInfo) => { 834 console.info(`formProvider getPublishedRunningFormInfoById, data: ${JSON.stringify(data)}`); 835 }).catch((error: BusinessError) => { 836 console.error(`promise error, code: ${error.code}, message: ${error.message}`); 837 }); 838} catch (error) { 839 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 840} 841``` 842 843## formProvider.getPublishedRunningFormInfos<sup>20+</sup> 844 845getPublishedRunningFormInfos(): Promise<Array<formInfo.RunningFormInfo>> 846 847获取所有已加桌的卡片信息，使用Promise异步回调。 848 849**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 850 851**系统能力：** SystemCapability.Ability.Form 852 853**返回值：** 854 855| 类型 | 说明 | 856| ------------ | ---------------------------------- | 857| Promise<Array<[formInfo.RunningFormInfo](js-apis-app-form-formInfo.md#runningforminfo20)>> | Promise对象。返回符合条件的卡片信息。 | 858 859**错误码：** 860 861以下错误码的详细介绍请参见[卡片错误码](errorcode-form.md)： 862 863| 错误码ID | 错误信息 | 864| -------- | -------- | 865| 16500050 | IPC connection error. | 866| 16500100 | Failed to obtain the configuration information. | 867| 16501000 | An internal functional error occurred. | 868 869**示例：** 870 871```ts 872import { formInfo, formProvider } from '@kit.FormKit'; 873import { BusinessError } from '@kit.BasicServicesKit'; 874 875try { 876 formProvider.getPublishedRunningFormInfos().then((data: formInfo.RunningFormInfo[]) => { 877 console.info(`formProvider getPublishedRunningFormInfos, data: ${JSON.stringify(data)}`); 878 }).catch((error: BusinessError) => { 879 console.error(`promise error, code: ${error.code}, message: ${error.message})`); 880 }); 881} catch (error) { 882 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`); 883} 884``` 885