1# @ohos.app.form.formHost (formHost)(系统接口) 2 3formHost模块提供了卡片使用方相关接口的能力，包括对使用方同一用户下安装的卡片进行删除、释放、请求更新、获取卡片信息、状态等操作。 4 5> **说明：** 6> 7> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8> 本模块接口均为系统接口。 9 10## 导入模块 11 12```ts 13import { formHost } from '@kit.FormKit'; 14``` 15 16## deleteForm 17 18deleteForm(formId: string, callback: AsyncCallback<void>): void 19 20删除指定的卡片。调用此方法后，应用程序将无法使用该卡片，卡片管理器服务不再保留有关该卡片的信息。使用callback异步回调。 21 22**需要权限：** ohos.permission.REQUIRE_FORM 23 24**系统能力：** SystemCapability.Ability.Form 25 26**参数：** 27 28| 参数名 | 类型 | 必填 | 说明 | 29| ------ | ------ | ---- | ------- | 30| formId | string | 是 | 卡片标识。 | 31| callback | AsyncCallback<void> | 是 | 回调函数。当删除指定的卡片成功，error为undefined，否则为错误对象。 | 32 33**错误码：** 34 35| 错误码ID | 错误信息 | 36| -------- | -------- | 37| 201 | Permissions denied. | 38| 202 | The application is not a system application. | 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| 16501000 | An internal functional error occurred. | 43| 16501001 | The ID of the form to be operated does not exist. | 44| 16501003 | The form cannot be operated by the current application. | 45 46以上错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 47 48**示例：** 49 50```ts 51import { formHost } from '@kit.FormKit'; 52import { BusinessError } from '@kit.BasicServicesKit'; 53 54try { 55 let formId: string = '12400633174999288'; 56 formHost.deleteForm(formId, (error: BusinessError) => { 57 if (error) { 58 console.error(`error, code: ${error.code}, message: ${error.message}`); 59 } else { 60 console.log('formHost deleteForm success'); 61 } 62 }); 63} catch (error) { 64 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 65} 66``` 67 68## deleteForm 69 70deleteForm(formId: string): Promise<void> 71 72删除指定的卡片。调用此方法后，应用程序将无法使用该卡片，卡片管理器服务不再保留有关该卡片的信息。使用Promise异步回调。 73 74**需要权限：** ohos.permission.REQUIRE_FORM 75 76**系统能力：** SystemCapability.Ability.Form 77 78**参数：** 79 80| 参数名 | 类型 | 必填 | 说明 | 81| ------ | ------ | ---- | ------- | 82| formId | string | 是 | 卡片标识。 | 83 84**返回值：** 85 86| 类型 | 说明 | 87| -------- | -------- | 88| Promise<void> | 无返回结果的Promise对象。 | 89 90 91**错误码：** 92 93| 错误码ID | 错误信息 | 94| -------- | -------- | 95| 201 | Permissions denied. | 96| 202 | The application is not a system application. | 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| 16501000 | An internal functional error occurred. | 101| 16501001 | The ID of the form to be operated does not exist. | 102| 16501003 | The form cannot be operated by the current application. | 103 104以上错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 105 106**示例：** 107 108```ts 109import { formHost } from '@kit.FormKit'; 110import { BusinessError } from '@kit.BasicServicesKit'; 111 112try { 113 let formId: string = '12400633174999288'; 114 formHost.deleteForm(formId).then(() => { 115 console.log('formHost deleteForm success'); 116 }).catch((error: BusinessError) => { 117 console.error(`formHost deleteForm, error: ${JSON.stringify(error)}`); 118 }); 119} catch (error) { 120 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 121} 122``` 123 124## releaseForm 125 126releaseForm(formId: string, callback: AsyncCallback<void>): void 127 128释放指定的卡片。调用此方法后，应用程序将无法使用该卡片，但卡片管理器服务仍然保留有关该卡片的缓存信息和存储信息。使用callback异步回调。 129 130**需要权限：** ohos.permission.REQUIRE_FORM 131 132**系统能力：** SystemCapability.Ability.Form 133 134**参数：** 135 136| 参数名 | 类型 | 必填 | 说明 | 137| ------ | ------ | ---- | ------- | 138| formId | string | 是 | 卡片标识。 | 139| callback | AsyncCallback<void> | 是 | 回调函数。当释放指定的卡片成功，error为undefined；否则为错误对象。| 140 141**错误码：** 142 143| 错误码ID | 错误信息 | 144| -------- | -------- | 145| 201 | Permissions denied. | 146| 202 | The application is not a system application. | 147| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 148| 16500050 | IPC connection error. | 149| 16500060 | Service connection error. | 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 154以上错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 155 156**示例：** 157 158```ts 159import { formHost } from '@kit.FormKit'; 160import { BusinessError } from '@kit.BasicServicesKit'; 161 162try { 163 let formId: string = '12400633174999288'; 164 formHost.releaseForm(formId, (error: BusinessError) => { 165 if (error) { 166 console.error(`error, code: ${error.code}, message: ${error.message}`); 167 } 168 }); 169} catch (error) { 170 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 171} 172``` 173 174## releaseForm 175 176releaseForm(formId: string, isReleaseCache: boolean, callback: AsyncCallback<void>): void 177 178释放指定的卡片。调用此方法后，应用程序将无法使用该卡片，卡片管理器服务保留有关该卡片的存储信息，可以选择是否保留缓存信息。使用callback异步回调。 179 180**需要权限：** ohos.permission.REQUIRE_FORM 181 182**系统能力：** SystemCapability.Ability.Form 183 184**参数：** 185 186| 参数名 | 类型 | 必填 | 说明 | 187| -------------- | ------ | ---- | ----------- | 188| formId | string | 是 | 卡片标识。 | 189| isReleaseCache | boolean | 是 | 是否释放缓存。 | 190| callback | AsyncCallback<void> | 是 | 回调函数。当释放指定的卡片成功，error为undefined；否则为错误对象。 | 191 192**错误码：** 193 194| 错误码ID | 错误信息 | 195| -------- | -------- | 196| 201 | Permissions denied. | 197| 202 | The application is not a system application. | 198| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 199| 16500050 | IPC connection error. | 200| 16500060 | Service connection error. | 201| 16501000 | An internal functional error occurred. | 202| 16501001 | The ID of the form to be operated does not exist. | 203| 16501003 | The form cannot be operated by the current application. | 204 205以上错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 206 207**示例：** 208 209```ts 210import { formHost } from '@kit.FormKit'; 211import { BusinessError } from '@kit.BasicServicesKit'; 212 213try { 214 let formId: string = '12400633174999288'; 215 formHost.releaseForm(formId, true, (error: BusinessError) => { 216 if (error) { 217 console.error(`error, code: ${error.code}, message: ${error.message}`); 218 } 219 }); 220} catch(error) { 221 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 222} 223``` 224 225## releaseForm 226 227releaseForm(formId: string, isReleaseCache?: boolean): Promise<void> 228 229释放指定的卡片。调用此方法后，应用程序将无法使用该卡片，卡片管理器服务保留有关该卡片的存储信息，可以选择是否保留缓存信息。使用Promise异步回调。 230 231**需要权限：** ohos.permission.REQUIRE_FORM 232 233**系统能力：** SystemCapability.Ability.Form 234 235**参数：** 236 237| 参数名 | 类型 | 必填 | 说明 | 238| -------------- | ------ | ---- | ----------- | 239| formId | string | 是 | 卡片标识。 | 240| isReleaseCache | boolean | 否 | 是否释放缓存，默认为false。 | 241 242**返回值：** 243 244| 类型 | 说明 | 245| -------- | -------- | 246| Promise<void> | 无返回结果的Promise对象。 | 247 248**错误码：** 249 250| 错误码ID | 错误信息 | 251| -------- | -------- | 252| 201 | Permissions denied. | 253| 202 | The application is not a system application. | 254| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 255| 16500050 | IPC connection error. | 256| 16500060 | Service connection error. | 257| 16501000 | An internal functional error occurred. | 258| 16501001 | The ID of the form to be operated does not exist. | 259| 16501003 | The form cannot be operated by the current application. | 260 261以上错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 262 263**示例：** 264 265```ts 266import { formHost } from '@kit.FormKit'; 267import { BusinessError } from '@kit.BasicServicesKit'; 268 269try { 270 let formId: string = '12400633174999288'; 271 formHost.releaseForm(formId, true).then(() => { 272 console.log('formHost releaseForm success'); 273 }).catch((error: BusinessError) => { 274 console.error(`error, code: ${error.code}, message: ${error.message}`); 275 }); 276} catch(error) { 277 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 278} 279``` 280 281## requestForm 282 283requestForm(formId: string, callback: AsyncCallback<void>): void 284 285请求卡片更新。使用callback异步回调。 286 287**需要权限：** ohos.permission.REQUIRE_FORM 288 289**系统能力：** SystemCapability.Ability.Form 290 291**参数：** 292 293| 参数名 | 类型 | 必填 | 说明 | 294| ------ | ------ | ---- | ------- | 295| formId | string | 是 | 卡片标识。 | 296| callback | AsyncCallback<void> | 是 | 回调函数。当请求卡片更新成功，error为undefined；否则为错误对象。 | 297 298**错误码：** 299 300| 错误码ID | 错误信息 | 301| -------- | -------- | 302| 201 | Permissions denied. | 303| 202 | The application is not a system application. | 304| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 305| 16500050 | IPC connection error. | 306| 16500060 | Service connection error. | 307| 16501000 | An internal functional error occurred. | 308| 16501001 | The ID of the form to be operated does not exist. | 309| 16501003 | The form cannot be operated by the current application. | 310 311以上错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 312 313**示例：** 314 315```ts 316import { formHost } from '@kit.FormKit'; 317import { BusinessError } from '@kit.BasicServicesKit'; 318 319try { 320 let formId: string = '12400633174999288'; 321 formHost.requestForm(formId, (error: BusinessError) => { 322 if (error) { 323 console.error(`error, code: ${error.code}, message: ${error.message}`); 324 } 325 }); 326} catch(error) { 327 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 328} 329``` 330 331## requestForm 332 333requestForm(formId: string): Promise<void> 334 335请求卡片更新。使用Promise异步回调。 336 337**需要权限：** ohos.permission.REQUIRE_FORM 338 339**系统能力：** SystemCapability.Ability.Form 340 341**参数：** 342 343| 参数名 | 类型 | 必填 | 说明 | 344| ------ | ------ | ---- | ------- | 345| formId | string | 是 | 卡片标识。 | 346 347**返回值：** 348 349| 类型 | 说明 | 350| -------- | -------- | 351| Promise<void> | 无返回结果的Promise对象。 | 352 353**错误码：** 354 355| 错误码ID | 错误信息 | 356| -------- | -------- | 357| 201 | Permissions denied. | 358| 202 | The application is not a system application. | 359| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 360| 16500050 | IPC connection error. | 361| 16500060 | Service connection error. | 362| 16501000 | An internal functional error occurred. | 363| 16501001 | The ID of the form to be operated does not exist. | 364| 16501003 | The form cannot be operated by the current application. | 365 366以上错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 367 368**示例：** 369 370```ts 371import { formHost } from '@kit.FormKit'; 372import { BusinessError } from '@kit.BasicServicesKit'; 373 374try { 375 let formId: string = '12400633174999288'; 376 formHost.requestForm(formId).then(() => { 377 console.log('formHost requestForm success'); 378 }).catch((error: BusinessError) => { 379 console.error(`error, code: ${error.code}, message: ${error.message}`); 380 }); 381} catch(error) { 382 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 383} 384``` 385 386## requestFormWithParams<sup>12+</sup> 387 388requestFormWithParams(formId: string, wantParams?: Record<string, Object>): Promise<void> 389 390携带参数请求卡片更新。使用Promise异步回调。 391 392**需要权限：** ohos.permission.REQUIRE_FORM 393 394**系统能力：** SystemCapability.Ability.Form 395 396**参数：** 397 398| 参数名 | 类型 | 必填 | 说明 | 399| ------ | ------ | ---- | ------- | 400| formId | string | 是 | 卡片标识。 | 401| wantParams | Record<string, Object> | 否 | 更新参数。 | 402 403**返回值：** 404 405| 类型 | 说明 | 406| -------- | -------- | 407| Promise<void> | 无返回结果的Promise对象。 | 408 409**错误码：** 410 411| 错误码ID | 错误信息 | 412| -------- | -------- | 413| 201 | Permissions denied. | 414| 202 | The application is not a system application. | 415| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 416| 16500050 | IPC connection error. | 417| 16500060 | Service connection error. | 418| 16501000 | An internal functional error occurred. | 419| 16501001 | The ID of the form to be operated does not exist. | 420| 16501003 | The form cannot be operated by the current application. | 421 422以上错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 423 424**示例：** 425 426```ts 427import { formHost } from '@kit.FormKit'; 428import { BusinessError } from '@kit.BasicServicesKit'; 429 430try { 431 let formId: string = '12400633174999288'; 432 let params: Record<string, Object> = { 433 'ohos.extra.param.key.host_bg_inverse_color': '#ff000000' as Object 434 }; 435 formHost.requestFormWithParams(formId, params).then(() => { 436 console.log('formHost requestFormWithParams success'); 437 }).catch((error: BusinessError) => { 438 console.error(`error, code: ${error.code}, message: ${error.message}`); 439 }); 440} catch(error) { 441 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 442} 443``` 444 445## castToNormalForm 446 447castToNormalForm(formId: string, callback: AsyncCallback<void>): void 448 449将指定的临时卡片转换为普通卡片。使用callback异步回调。 450 451**需要权限：** ohos.permission.REQUIRE_FORM 452 453**系统能力：** SystemCapability.Ability.Form 454 455**参数：** 456 457| 参数名 | 类型 | 必填 | 说明 | 458| ------ | ------ | ---- | ------- | 459| formId | string | 是 | 卡片标识。 | 460| callback | AsyncCallback<void> | 是 | 回调函数。当将指定的临时卡片转换为普通卡片成功，error为undefined，否则为错误对象。 | 461 462**错误码：** 463 464| 错误码ID | 错误信息 | 465| -------- | -------- | 466| 201 | Permissions denied. | 467| 202 | The application is not a system application. | 468| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 469| 16500050 | IPC connection error. | 470| 16501000 | An internal functional error occurred. | 471| 16501001 | The ID of the form to be operated does not exist. | 472| 16501002 | The number of forms exceeds the maximum allowed. | 473| 16501003 | The form cannot be operated by the current application. | 474 475以上错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 476 477**示例：** 478 479```ts 480import { formHost } from '@kit.FormKit'; 481import { BusinessError } from '@kit.BasicServicesKit'; 482 483try { 484 let formId: string = '12400633174999288'; 485 formHost.castToNormalForm(formId, (error: BusinessError) => { 486 if (error) { 487 console.error(`error, code: ${error.code}, message: ${error.message}`); 488 } 489 }); 490} catch(error) { 491 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 492} 493``` 494 495## castToNormalForm 496 497castToNormalForm(formId: string): Promise<void> 498 499将指定的临时卡片转换为普通卡片。使用Promise异步回调。 500 501**需要权限：** ohos.permission.REQUIRE_FORM 502 503**系统能力：** SystemCapability.Ability.Form 504 505**参数：** 506 507| 参数名 | 类型 | 必填 | 说明 | 508| ------ | ------ | ---- | ------- | 509| formId | string | 是 | 卡片标识。 | 510 511**返回值：** 512 513| 类型 | 说明 | 514| -------- | -------- | 515| Promise<void> | 无返回结果的Promise对象。| 516 517**错误码：** 518 519| 错误码ID | 错误信息 | 520| -------- | -------- | 521| 201 | Permissions denied. | 522| 202 | The application is not a system application. | 523| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 524| 16500050 | IPC connection error. | 525| 16501000 | An internal functional error occurred. | 526| 16501001 | The ID of the form to be operated does not exist. | 527| 16501002 | The number of forms exceeds the maximum allowed. | 528| 16501003 | The form cannot be operated by the current application. | 529 530以上错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 531 532**示例：** 533 534```ts 535import { formHost } from '@kit.FormKit'; 536import { BusinessError } from '@kit.BasicServicesKit'; 537 538try { 539 let formId: string = '12400633174999288'; 540 formHost.castToNormalForm(formId).then(() => { 541 console.log('formHost castTempForm success'); 542 }).catch((error: BusinessError) => { 543 console.error(`error, code: ${error.code}, message: ${error.message}`); 544 }); 545} catch(error) { 546 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 547} 548``` 549 550## notifyVisibleForms 551 552notifyVisibleForms(formIds: Array<string>, callback: AsyncCallback<void>): void 553 554向卡片框架发送通知以使指定的卡片可见。该方法调用成功后，会调用onVisibilityChange通知卡片提供方。使用callback异步回调。 555 556**需要权限：** ohos.permission.REQUIRE_FORM 557 558**系统能力：** SystemCapability.Ability.Form 559 560**参数：** 561 562| 参数名 | 类型 | 必填 | 说明 | 563| ------ | ------ | ---- | ------- | 564| formIds | Array<string> | 是 | 卡片标识列表。 | 565| callback | AsyncCallback<void> | 是 | 回调函数。当向卡片框架发送通知以使指定的卡片可见成功，error为undefined，否则为错误对象。 | 566 567**错误码：** 568 569| 错误码ID | 错误信息 | 570| -------- | -------- | 571| 201 | Permissions denied. | 572| 202 | The application is not a system application. | 573| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 574| 16500050 | IPC connection error. | 575| 16500060 | Service connection error. | 576| 16501000 | An internal functional error occurred. | 577 578以上错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 579 580**示例：** 581 582```ts 583import { formHost } from '@kit.FormKit'; 584import { BusinessError } from '@kit.BasicServicesKit'; 585 586try { 587 let formId: string[] = ['12400633174999288']; 588 formHost.notifyVisibleForms(formId, (error: BusinessError) => { 589 if (error) { 590 console.error(`error, code: ${error.code}, message: ${error.message}`); 591 } 592 }); 593} catch (error) { 594 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 595} 596``` 597 598## notifyVisibleForms 599 600notifyVisibleForms(formIds: Array<string>): Promise<void> 601 602向卡片框架发送通知以使指定的卡片可见。该方法调用成功后，会调用onVisibilityChange通知卡片提供方。使用Promise异步回调。 603 604**需要权限：** ohos.permission.REQUIRE_FORM 605 606**系统能力：** SystemCapability.Ability.Form 607 608**参数：** 609 610| 参数名 | 类型 | 必填 | 说明 | 611| ------ | ------ | ---- | ------- | 612| formIds | Array<string> | 是 | 卡片标识列表。 | 613 614**返回值：** 615 616| 类型 | 说明 | 617| -------- | -------- | 618| Promise<void> | 无返回结果的Promise对象。 | 619 620**错误码：** 621 622| 错误码ID | 错误信息 | 623| -------- | -------- | 624| 201 | Permissions denied. | 625| 202 | The application is not a system application. | 626| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 627| 16500050 | IPC connection error. | 628| 16500060 | Service connection error. | 629| 16501000 | An internal functional error occurred. | 630 631以上错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 632 633**示例：** 634 635```ts 636import { formHost } from '@kit.FormKit'; 637import { BusinessError } from '@kit.BasicServicesKit'; 638 639try { 640 let formId: string[] = ['12400633174999288']; 641 formHost.notifyVisibleForms(formId).then(() => { 642 console.log('formHost notifyVisibleForms success'); 643 }).catch((error: BusinessError) => { 644 console.error(`error, code: ${error.code}, message: ${error.message}`); 645 }); 646} catch(error) { 647 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 648} 649``` 650 651## notifyInvisibleForms 652 653notifyInvisibleForms(formIds: Array<string>, callback: AsyncCallback<void>): void 654 655向卡片框架发送通知以使指定的卡片不可见。该方法调用成功后，会调用onVisibilityChange通知卡片提供方。使用callback异步回调。 656 657**需要权限：** ohos.permission.REQUIRE_FORM 658 659**系统能力：** SystemCapability.Ability.Form 660 661**参数：** 662 663| 参数名 | 类型 | 必填 | 说明 | 664| ------ | ------ | ---- | ------- | 665| formIds | Array<string> | 是 | 卡片标识列表。| 666| callback | AsyncCallback<void> | 是 | 回调函数。当向卡片框架发送通知以使指定的卡片不可见成功，error为undefined，否则为错误对象。 | 667 668**错误码：** 669 670| 错误码ID | 错误信息 | 671| -------- | -------- | 672| 201 | Permissions denied. | 673| 202 | The application is not a system application. | 674| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 675| 16500050 | IPC connection error. | 676| 16500060 | Service connection error. | 677| 16501000 | An internal functional error occurred. | 678 679以上错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 680 681**示例：** 682 683```ts 684import { formHost } from '@kit.FormKit'; 685import { BusinessError } from '@kit.BasicServicesKit'; 686 687try { 688 let formId: string[] = ['12400633174999288']; 689 formHost.notifyInvisibleForms(formId, (error: BusinessError) => { 690 if (error) { 691 console.error(`error, code: ${error.code}, message: ${error.message}`); 692 } 693 }); 694} catch(error) { 695 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 696} 697``` 698 699## notifyInvisibleForms 700 701notifyInvisibleForms(formIds: Array<string>): Promise<void> 702 703向卡片框架发送通知以使指定的卡片不可见。该方法调用成功后，会调用onVisibilityChange通知卡片提供方。使用Promise异步回调。 704 705**需要权限：** ohos.permission.REQUIRE_FORM 706 707**系统能力：** SystemCapability.Ability.Form 708 709**参数：** 710 711| 参数名 | 类型 | 必填 | 说明 | 712| ------ | ------ | ---- | ------- | 713| formIds | Array<string> | 是 | 卡片标识列表。 | 714 715**返回值：** 716 717| 类型 | 说明 | 718| -------- | -------- | 719| Promise<void> | 无返回结果的Promise对象。| 720 721**错误码：** 722 723| 错误码ID | 错误信息 | 724| -------- | -------- | 725| 201 | Permissions denied. | 726| 202 | The application is not a system application. | 727| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 728| 16500050 | IPC connection error. | 729| 16500060 | Service connection error. | 730| 16501000 | An internal functional error occurred. | 731 732以上错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 733 734**示例：** 735 736```ts 737import { formHost } from '@kit.FormKit'; 738import { BusinessError } from '@kit.BasicServicesKit'; 739 740try { 741 let formId: string[] = ['12400633174999288']; 742 formHost.notifyInvisibleForms(formId).then(() => { 743 console.log('formHost notifyInvisibleForms success'); 744 }).catch((error: BusinessError) => { 745 console.error(`error, code: ${error.code}, message: ${error.message}`); 746 }); 747} catch(error) { 748 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 749} 750``` 751 752## enableFormsUpdate 753 754enableFormsUpdate(formIds: Array<string>, callback: AsyncCallback<void>): void 755 756向卡片框架发送通知以使指定的卡片可以更新。该方法调用成功后，卡片刷新状态设置为使能，卡片可以接收来自卡片提供方的更新。使用callback异步回调。 757 758**需要权限：** ohos.permission.REQUIRE_FORM 759 760**系统能力：** SystemCapability.Ability.Form 761 762**参数：** 763 764| 参数名 | 类型 | 必填 | 说明 | 765| ------ | ------ | ---- | ------- | 766| formIds | Array<string> | 是 | 卡片标识列表。 | 767| callback | AsyncCallback<void> | 是 | 回调函数。当向卡片框架发送通知以使指定的卡片可以更新成功，error为undefined，否则为错误对象。 | 768 769**错误码：** 770 771| 错误码ID | 错误信息 | 772| -------- | -------- | 773| 201 | Permissions denied. | 774| 202 | The application is not a system application. | 775| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 776| 16500050 | IPC connection error. | 777| 16500060 | Service connection error. | 778| 16501000 | An internal functional error occurred. | 779| 16501003 | The form cannot be operated by the current application. | 780 781以上错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 782 783**示例：** 784 785```ts 786import { formHost } from '@kit.FormKit'; 787import { BusinessError } from '@kit.BasicServicesKit'; 788 789try { 790 let formId: string[] = ['12400633174999288']; 791 formHost.enableFormsUpdate(formId, (error: BusinessError) => { 792 if (error) { 793 console.error(`error, code: ${error.code}, message: ${error.message}`); 794 } 795 }); 796} catch(error) { 797 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 798} 799``` 800 801## enableFormsUpdate 802 803enableFormsUpdate(formIds: Array<string>): Promise<void> 804 805向卡片框架发送通知以使指定的卡片可以更新。该方法调用成功后，卡片刷新状态设置为使能，卡片可以接收来自卡片提供方的更新。使用Promise异步回调。 806 807**需要权限：** ohos.permission.REQUIRE_FORM 808 809**系统能力：** SystemCapability.Ability.Form 810 811**参数：** 812 813| 参数名 | 类型 | 必填 | 说明 | 814| ------ | ------ | ---- | ------- | 815| formIds | Array<string> | 是 | 卡片标识列表。 | 816 817**返回值：** 818 819| 类型 | 说明 | 820| -------- | -------- | 821| Promise<void> | 无返回结果的Promise对象。 | 822 823**错误码：** 824 825| 错误码ID | 错误信息 | 826| -------- | -------- | 827| 201 | Permissions denied. | 828| 202 | The application is not a system application. | 829| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 830| 16500050 | IPC connection error. | 831| 16500060 | Service connection error. | 832| 16501000 | An internal functional error occurred. | 833| 16501003 | The form cannot be operated by the current application. | 834 835以上错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 836 837**示例：** 838 839```ts 840import { formHost } from '@kit.FormKit'; 841import { BusinessError } from '@kit.BasicServicesKit'; 842 843try { 844 let formId: string[] = ['12400633174999288']; 845 formHost.enableFormsUpdate(formId).then(() => { 846 console.log('formHost enableFormsUpdate success'); 847 }).catch((error: BusinessError) => { 848 console.error(`error, code: ${error.code}, message: ${error.message}`); 849 }); 850} catch(error) { 851 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 852} 853``` 854 855## disableFormsUpdate 856 857disableFormsUpdate(formIds: Array<string>, callback: AsyncCallback<void>): void 858 859向卡片框架发送通知以使指定的卡片不可以更新。该方法调用成功后，卡片刷新状态设置为去使能，卡片不可以接收来自卡片提供方的更新。使用callback异步回调。 860 861**需要权限：** ohos.permission.REQUIRE_FORM 862 863**系统能力：** SystemCapability.Ability.Form 864 865**参数：** 866 867| 参数名 | 类型 | 必填 | 说明 | 868| ------ | ------ | ---- | ------- | 869| formIds | Array<string> | 是 | 卡片标识列表。 | 870| callback | AsyncCallback<void> | 是 | 回调函数。当向卡片框架发送通知以使指定的卡片不可以更新成功，error为undefined，否则为错误对象。 | 871 872**错误码：** 873 874| 错误码ID | 错误信息 | 875| -------- | -------- | 876| 201 | Permissions denied. | 877| 202 | The application is not a system application. | 878| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 879| 16500050 | IPC connection error. | 880| 16500060 | Service connection error. | 881| 16501000 | An internal functional error occurred. | 882| 16501001 | The ID of the form to be operated does not exist. | 883| 16501003 | The form cannot be operated by the current application. | 884 885以上错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 886 887**示例：** 888 889```ts 890import { formHost } from '@kit.FormKit'; 891import { BusinessError } from '@kit.BasicServicesKit'; 892 893try { 894 let formId: string[] = ['12400633174999288']; 895 formHost.disableFormsUpdate(formId, (error: BusinessError) => { 896 if (error) { 897 console.error(`error, code: ${error.code}, message: ${error.message}`); 898 } 899 }); 900} catch(error) { 901 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 902} 903``` 904 905## disableFormsUpdate 906 907disableFormsUpdate(formIds: Array<string>): Promise<void> 908 909向卡片框架发送通知以使指定的卡片不可以更新。该方法调用成功后，卡片刷新状态设置为去使能，卡片不可以接收来自卡片提供方的更新。使用Promise异步回调。 910 911**需要权限：** ohos.permission.REQUIRE_FORM 912 913**系统能力：** SystemCapability.Ability.Form 914 915**参数：** 916 917| 参数名 | 类型 | 必填 | 说明 | 918| ------ | ------ | ---- | ------- | 919| formIds | Array<string> | 是 | 卡片标识列表。 | 920 921**返回值：** 922 923| 类型 | 说明 | 924| -------- | -------- | 925| Promise<void> | 无返回结果的Promise对象。 | 926 927**错误码：** 928 929| 错误码ID | 错误信息 | 930| -------- | -------- | 931| 201 | Permissions denied. | 932| 202 | The application is not a system application. | 933| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 934| 16500050 | IPC connection error. | 935| 16500060 | Service connection error. | 936| 16501000 | An internal functional error occurred. | 937| 16501001 | The ID of the form to be operated does not exist. | 938| 16501003 | The form cannot be operated by the current application. | 939 940以上错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 941 942**示例：** 943 944```ts 945import { formHost } from '@kit.FormKit'; 946import { BusinessError } from '@kit.BasicServicesKit'; 947 948try { 949 let formId: string[] = ['12400633174999288']; 950 formHost.disableFormsUpdate(formId).then(() => { 951 console.log('formHost disableFormsUpdate success'); 952 }).catch((error: BusinessError) => { 953 console.error(`error, code: ${error.code}, message: ${error.message}`); 954 }); 955} catch(error) { 956 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 957} 958``` 959 960## isSystemReady 961 962isSystemReady(callback: AsyncCallback<void>): void 963 964检查系统是否准备好。使用callback异步回调。 965 966**系统能力：** SystemCapability.Ability.Form 967 968**参数：** 969 970| 参数名 | 类型 | 必填 | 说明 | 971| ------ | ------ | ---- | ------- | 972| callback | AsyncCallback<void> | 是 | 回调函数。当检查系统是否准备好成功，error为undefined，否则为错误对象。 | 973 974**错误码：** 975 976| 错误码ID | 错误信息 | 977| -------- | -------- | 978| 202 | The application is not a system application. | 979| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 980 981以上错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 982 983**示例：** 984 985```ts 986import { formHost } from '@kit.FormKit'; 987import { BusinessError } from '@kit.BasicServicesKit'; 988 989try { 990 formHost.isSystemReady((error: BusinessError) => { 991 if (error) { 992 console.error(`error, code: ${error.code}, message: ${error.message}`); 993 } 994 }); 995} catch(error) { 996 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 997} 998``` 999 1000## isSystemReady 1001 1002isSystemReady(): Promise<void> 1003 1004检查系统是否准备好。使用Promise异步回调。 1005 1006**系统能力：** SystemCapability.Ability.Form 1007 1008**返回值：** 1009 1010| 类型 | 说明 | 1011| -------- | -------- | 1012| Promise<void> | 无返回结果的Promise对象。 | 1013 1014**错误码：** 1015 1016| 错误码ID | 错误信息 | 1017| -------- | -------- | 1018| 202 | The application is not a system application. | 1019 1020以上错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 1021 1022**示例：** 1023 1024```ts 1025import { formHost } from '@kit.FormKit'; 1026import { BusinessError } from '@kit.BasicServicesKit'; 1027 1028try { 1029 formHost.isSystemReady().then(() => { 1030 console.log('formHost isSystemReady success'); 1031 }).catch((error: BusinessError) => { 1032 console.error(`error, code: ${error.code}, message: ${error.message}`); 1033 }); 1034} catch(error) { 1035 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 1036} 1037``` 1038 1039## getAllFormsInfo 1040 1041getAllFormsInfo(callback: AsyncCallback<Array<formInfo.FormInfo>>): void 1042 1043获取设备上所有应用提供的卡片信息。使用callback异步回调。 1044 1045**需要权限：** ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 1046 1047**系统能力：** SystemCapability.Ability.Form 1048 1049**参数：** 1050 1051| 参数名 | 类型 | 必填 | 说明 | 1052| ------ |----------------------------------------------------------------------------------------------| ---- | ------- | 1053| callback | AsyncCallback<Array<[formInfo.FormInfo](js-apis-app-form-formInfo.md#forminfo)>> | 是 | 回调函数。当获取设备上所有应用提供的卡片信息成功，error为undefined，data为查询到的卡片信息；否则为错误对象。 | 1054 1055**错误码：** 1056 1057| 错误码ID | 错误信息 | 1058| -------- | -------- | 1059| 201 | Permissions denied. | 1060| 202 | The application is not a system application. | 1061| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1062| 16500050 | IPC connection error. | 1063| 16500060 | Service connection error. | 1064| 16501000 | An internal functional error occurred. | 1065 1066以上错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 1067 1068 1069**示例：** 1070 1071```ts 1072import { formHost, formInfo } from '@kit.FormKit'; 1073import { BusinessError } from '@kit.BasicServicesKit'; 1074 1075try { 1076 formHost.getAllFormsInfo((error: BusinessError, data: formInfo.FormInfo[]) => { 1077 if (error) { 1078 console.error(`error, code: ${error.code}, message: ${error.message}`); 1079 } else { 1080 console.log(`formHost getAllFormsInfo, data: ${JSON.stringify(data)}`); 1081 } 1082 }); 1083} catch(error) { 1084 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 1085} 1086``` 1087 1088## getAllFormsInfo 1089 1090getAllFormsInfo(): Promise<Array<formInfo.FormInfo>> 1091 1092获取设备上所有应用提供的卡片信息。使用Promise异步回调。 1093 1094**需要权限：** ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 1095 1096**系统能力：** SystemCapability.Ability.Form 1097 1098**返回值：** 1099 1100| 类型 | 说明 | 1101|:---------------------------------------------------------------------------------------|:----------------------| 1102| Promise<Array<[formInfo.FormInfo](js-apis-app-form-formInfo.md#forminfo)>> | Promise对象。返回查询到的卡片信息。 | 1103 1104**错误码：** 1105 1106| 错误码ID | 错误信息 | 1107| -------- | -------- | 1108| 201 | Permissions denied. | 1109| 202 | The application is not a system application. | 1110| 16500050 | IPC connection error. | 1111| 16500060 | Service connection error. | 1112| 16501000 | An internal functional error occurred. | 1113 1114以上错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 1115 1116**示例：** 1117 1118```ts 1119import { formHost, formInfo } from '@kit.FormKit'; 1120import { BusinessError } from '@kit.BasicServicesKit'; 1121 1122try { 1123 formHost.getAllFormsInfo().then((data: formInfo.FormInfo[]) => { 1124 console.log(`formHost getAllFormsInfo data: ${JSON.stringify(data)}`); 1125 }).catch((error: BusinessError) => { 1126 console.error(`error, code: ${error.code}, message: ${error.message}`); 1127 }); 1128} catch(error) { 1129 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 1130} 1131``` 1132 1133## getFormsInfo 1134 1135getFormsInfo(bundleName: string, callback: AsyncCallback<Array<formInfo.FormInfo>>): void 1136 1137获取设备上指定应用程序提供的卡片信息。使用callback异步回调。 1138 1139**需要权限：** ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 1140 1141**系统能力：** SystemCapability.Ability.Form 1142 1143**参数：** 1144 1145| 参数名 | 类型 | 必填 | 说明 | 1146| ------ |----------------------------------------------------------------------------------------------| ---- | ------- | 1147| bundleName | string | 是 | 要查询的应用Bundle名称。 | 1148| callback | AsyncCallback<Array<[formInfo.FormInfo](js-apis-app-form-formInfo.md#forminfo)>> | 是 | 回调函数。当获取设备上指定应用程序提供的卡片信息成功，error为undefined，data为查询到的卡片信息；否则为错误对象。 | 1149 1150**错误码：** 1151 1152| 错误码ID | 错误信息 | 1153| -------- | -------- | 1154| 201 | Permissions denied. | 1155| 202 | The application is not a system application. | 1156| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1157| 16500050 | IPC connection error. | 1158| 16500060 | Service connection error. | 1159| 16500100 | Failed to obtain the configuration information. | 1160| 16501000 | An internal functional error occurred. | 1161 1162以上错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 1163 1164**示例：** 1165 1166```ts 1167import { formHost, formInfo } from '@kit.FormKit'; 1168import { BusinessError } from '@kit.BasicServicesKit'; 1169 1170try { 1171 formHost.getFormsInfo('com.example.ohos.formjsdemo', (error: BusinessError, data: formInfo.FormInfo[]) => { 1172 if (error) { 1173 console.error(`error, code: ${error.code}, message: ${error.message}`); 1174 } else { 1175 console.log(`formHost getFormsInfo, data: ${JSON.stringify(data)}`); 1176 } 1177 }); 1178} catch(error) { 1179 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 1180} 1181``` 1182 1183## getFormsInfo 1184 1185getFormsInfo(bundleName: string, moduleName: string, callback: AsyncCallback<Array<formInfo.FormInfo>>): void 1186 1187获取设备上指定应用程序提供的卡片信息。使用callback异步回调。 1188 1189**需要权限：** ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 1190 1191**系统能力：** SystemCapability.Ability.Form 1192 1193**参数：** 1194 1195| 参数名 | 类型 | 必填 | 说明 | 1196| ------ |----------------------------------------------------------------------------------------------| ---- | ------- | 1197| bundleName | string | 是 | 要查询的应用Bundle名称。 | 1198| moduleName | string | 是 | 要查询的模块名称。 | 1199| callback | AsyncCallback<Array<[formInfo.FormInfo](js-apis-app-form-formInfo.md#forminfo)>> | 是 | 回调函数。当获取设备上指定应用程序提供的卡片信息成功，error为undefined，data为查询到的卡片信息；否则为错误对象。 | 1200 1201**错误码：** 1202 1203| 错误码ID | 错误信息 | 1204| -------- | -------- | 1205| 201 | Permissions denied. | 1206| 202 | The application is not a system application. | 1207| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1208| 16500050 | IPC connection error. | 1209| 16500060 | Service connection error. | 1210| 16500100 | Failed to obtain the configuration information. | 1211| 16501000 | An internal functional error occurred. | 1212 1213以上错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 1214 1215**示例：** 1216 1217```ts 1218import { formHost, formInfo } from '@kit.FormKit'; 1219import { BusinessError } from '@kit.BasicServicesKit'; 1220 1221try { 1222 formHost.getFormsInfo('com.example.ohos.formjsdemo', 'entry', (error: BusinessError, data: formInfo.FormInfo[]) => { 1223 if (error) { 1224 console.error(`error, code: ${error.code}, message: ${error.message}`); 1225 } else { 1226 console.log(`formHost getFormsInfo, data: ${JSON.stringify(data)}`); 1227 } 1228 }); 1229} catch(error) { 1230 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 1231} 1232``` 1233 1234## getFormsInfo 1235 1236getFormsInfo(bundleName: string, moduleName?: string): Promise<Array<formInfo.FormInfo>> 1237 1238获取设备上指定应用程序提供的卡片信息。使用Promise异步回调。 1239 1240**需要权限：** ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 1241 1242**系统能力：** SystemCapability.Ability.Form 1243 1244**参数：** 1245 1246| 参数名 | 类型 | 必填 | 说明 | 1247| ------ | ------ | ---- | ------- | 1248| bundleName | string | 是 | 要查询的应用Bundle名称。 | 1249| moduleName | string | 否 | 要查询的模块名称，缺省默认为空。 | 1250 1251**返回值：** 1252 1253| 类型 | 说明 | 1254|:---------------------------------------------------------------------------------------| :---------------------------------- | 1255| Promise<Array<[formInfo.FormInfo](js-apis-app-form-formInfo.md#forminfo)>> | Promise对象。返回查询到的卡片信息。 | 1256 1257**错误码：** 1258 1259| 错误码ID | 错误信息 | 1260| -------- | -------- | 1261| 201 | Permissions denied. | 1262| 202 | The application is not a system application. | 1263| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1264| 16500050 | IPC connection error. | 1265| 16500060 | Service connection error. | 1266| 16500100 | Failed to obtain the configuration information. | 1267| 16501000 | An internal functional error occurred. | 1268 1269以上错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 1270 1271**示例：** 1272 1273```ts 1274import { formHost, formInfo } from '@kit.FormKit'; 1275import { BusinessError } from '@kit.BasicServicesKit'; 1276 1277try { 1278 formHost.getFormsInfo('com.example.ohos.formjsdemo', 'entry').then((data: formInfo.FormInfo[]) => { 1279 console.log(`formHost getFormsInfo, data: ${JSON.stringify(data)}`); 1280 }).catch((error: BusinessError) => { 1281 console.error(`error, code: ${error.code}, message: ${error.message}`); 1282 }); 1283} catch(error) { 1284 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 1285} 1286``` 1287 1288## getFormsInfo<sup>12+</sup> 1289 1290getFormsInfo(filter: formInfo.FormInfoFilter): Promise<Array<formInfo.FormInfo>> 1291 1292获取设备上指定应用程序提供的卡片信息。使用Promise异步回调。 1293 1294**需要权限**：ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 1295 1296**系统能力**：SystemCapability.Ability.Form 1297 1298**参数：** 1299 1300| 参数名 | 类型 | 必填 | 说明 | 1301| ------ | ------ | ---- | ------- | 1302| filter | [formInfo.FormInfoFilter](js-apis-app-form-formInfo.md#forminfofilter) | 是 | 卡片信息过滤器。 | 1303 1304**返回值：** 1305 1306| 类型 | 说明 | 1307| :------------ | :---------------------------------- | 1308| Promise<Array<[formInfo.FormInfo](js-apis-app-form-formInfo.md)>> | Promise对象。返回查询到符合条件的卡片信息。 | 1309 1310**错误码：** 1311 1312| 错误码ID | 错误信息 | 1313| -------- | -------- | 1314| 201 | Permissions denied. | 1315| 202 | The application is not a system application. | 1316| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1317| 16500050 | IPC connection error. | 1318| 16500060 | Service connection error. | 1319| 16500100 | Failed to obtain the configuration information. | 1320| 16501000 | An internal functional error occurred. | 1321 1322以上错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 1323 1324**示例：** 1325 1326```ts 1327import { formHost, formInfo } from '@kit.FormKit'; 1328import { BusinessError } from '@kit.BasicServicesKit'; 1329 1330const filter: formInfo.FormInfoFilter = { 1331 bundleName: 'ohos.samples.FormApplication', 1332 moduleName: 'entry', 1333 supportedDimensions: [FormDimension.Dimension_1_2, FormDimension.Dimension_2_2, FormDimension.Dimension_2_4] 1334}; 1335try { 1336 formHost.getFormsInfo(filter).then((data: formInfo.FormInfo[]) => { 1337 console.log(`formHost getFormsInfo, data: ${JSON.stringify(data)}`); 1338 }).catch((error: BusinessError) => { 1339 console.error(`promise error, code: ${error.code}, message: ${error.message})`); 1340 }); 1341} catch (error) { 1342 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`); 1343} 1344``` 1345 1346## deleteInvalidForms 1347 1348deleteInvalidForms(formIds: Array<string>, callback: AsyncCallback<number>): void 1349 1350根据列表删除应用程序的无效卡片。使用callback异步回调。 1351 1352**需要权限：** ohos.permission.REQUIRE_FORM 1353 1354**系统能力：** SystemCapability.Ability.Form 1355 1356**参数：** 1357 1358| 参数名 | 类型 | 必填 | 说明 | 1359| ------ | ------ | ---- | ------- | 1360| formIds | Array<string> | 是 | 有效卡片标识列表。 | 1361| callback | AsyncCallback<number> | 是 | 回调函数。当根据列表删除应用程序的无效卡片成功，error为undefined，data为删除的卡片个数；否则为错误对象。 | 1362 1363**错误码：** 1364 1365| 错误码ID | 错误信息 | 1366| -------- | -------- | 1367| 201 | Permissions denied. | 1368| 202 | The application is not a system application. | 1369| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1370| 16500050 | IPC connection error. | 1371| 16500060 | Service connection error. | 1372| 16501000 | An internal functional error occurred. | 1373 1374以上错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 1375 1376**示例：** 1377 1378```ts 1379import { formHost } from '@kit.FormKit'; 1380import { BusinessError } from '@kit.BasicServicesKit'; 1381 1382try { 1383 let formIds: string[] = new Array('12400633174999288', '12400633174999289'); 1384 formHost.deleteInvalidForms(formIds, (error: BusinessError, data: number) => { 1385 if (error) { 1386 console.error(`error, code: ${error.code}, message: ${error.message}`); 1387 } else { 1388 console.log(`formHost deleteInvalidForms, data: ${JSON.stringify(data)}`); 1389 } 1390 }); 1391} catch(error) { 1392 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 1393} 1394``` 1395 1396## deleteInvalidForms 1397 1398deleteInvalidForms(formIds: Array<string>): Promise<number> 1399 1400根据列表删除应用程序的无效卡片。使用Promise异步回调。 1401 1402**需要权限：** ohos.permission.REQUIRE_FORM 1403 1404**系统能力：** SystemCapability.Ability.Form 1405 1406**参数：** 1407 1408| 参数名 | 类型 | 必填 | 说明 | 1409| ------ | ------ | ---- | ------- | 1410| formIds | Array<string> | 是 | 有效卡片标识列表。 | 1411 1412**返回值：** 1413 1414| 类型 | 说明 | 1415| :------------ | :---------------------------------- | 1416| Promise<number> | Promise对象。返回删除的卡片个数。 | 1417 1418**错误码：** 1419 1420| 错误码ID | 错误信息 | 1421| -------- | -------- | 1422| 201 | Permissions denied. | 1423| 202 | The application is not a system application. | 1424| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1425| 16500050 | IPC connection error. | 1426| 16500060 | Service connection error. | 1427| 16501000 | An internal functional error occurred. | 1428 1429以上错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 1430 1431**示例：** 1432 1433```ts 1434import { formHost } from '@kit.FormKit'; 1435import { BusinessError } from '@kit.BasicServicesKit'; 1436 1437try { 1438 let formIds: string[] = new Array('12400633174999288', '12400633174999289'); 1439 formHost.deleteInvalidForms(formIds).then((data: number) => { 1440 console.log(`formHost deleteInvalidForms, data: ${JSON.stringify(data)}`); 1441 }).catch((error: BusinessError) => { 1442 console.error(`error, code: ${error.code}, message: ${error.message}`); 1443 }); 1444} catch(error) { 1445 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 1446} 1447``` 1448 1449## acquireFormState 1450 1451acquireFormState(want: Want, callback: AsyncCallback<formInfo.FormStateInfo>): void 1452 1453获取卡片状态。使用callback异步回调。 1454 1455**需要权限：** ohos.permission.REQUIRE_FORM 和 ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 1456 1457**系统能力：** SystemCapability.Ability.Form 1458 1459**参数：** 1460 1461| 参数名 | 类型 | 必填 | 说明 | 1462| ------ | ------ | ---- | ------- | 1463| want | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | 是 | 查询卡片状态时携带的want信息。需要包含bundle名、ability名、module名、卡片名、卡片规格等。 | 1464| callback | AsyncCallback<[formInfo.FormStateInfo](js-apis-app-form-formInfo.md#formstateinfo)> | 是 | 回调函数。当获取卡片状态成功，error为undefined，data为获取到的卡片状态；否则为错误对象。 | 1465 1466**错误码：** 1467 1468| 错误码ID | 错误信息 | 1469| -------- | -------- | 1470| 201 | Permissions denied. | 1471| 202 | The application is not a system application. | 1472| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1473| 16500050 | IPC connection error. | 1474| 16500060 | Service connection error. | 1475| 16500100 | Failed to obtain the configuration information. | 1476| 16501000 | An internal functional error occurred. | 1477 1478以上错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 1479 1480**示例：** 1481 1482```ts 1483import { formHost, formInfo } from '@kit.FormKit'; 1484import { Want } from '@kit.AbilityKit'; 1485import { BusinessError } from '@kit.BasicServicesKit'; 1486 1487let want: Want = { 1488 'deviceId': '', 1489 'bundleName': 'ohos.samples.FormApplication', 1490 'abilityName': 'FormAbility', 1491 'parameters': { 1492 'ohos.extra.param.key.module_name': 'entry', 1493 'ohos.extra.param.key.form_name': 'widget', 1494 'ohos.extra.param.key.form_dimension': 2 1495 } 1496}; 1497try { 1498 formHost.acquireFormState(want, (error: BusinessError, data: formInfo.FormStateInfo) => { 1499 if (error) { 1500 console.error(`error, code: ${error.code}, message: ${error.message}`); 1501 } else { 1502 console.log(`formHost acquireFormState, data: ${JSON.stringify(data)}`); 1503 } 1504 }); 1505} catch (error) { 1506 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 1507} 1508``` 1509 1510## acquireFormState 1511 1512acquireFormState(want: Want): Promise<formInfo.FormStateInfo> 1513 1514获取卡片状态。使用Promise异步回调。 1515 1516**需要权限：** ohos.permission.REQUIRE_FORM 和 ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 1517 1518**系统能力：** SystemCapability.Ability.Form 1519 1520**参数：** 1521 1522| 参数名 | 类型 | 必填 | 说明 | 1523| ------ | ------ | ---- | ------- | 1524| want | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | 是 | 查询卡片状态时携带的want信息。需要包含bundle名、ability名、module名、卡片名、卡片规格等。 | 1525 1526**返回值：** 1527 1528| 类型 | 说明 | 1529| :------------ | :---------------------------------- | 1530| Promise<[formInfo.FormStateInfo](js-apis-app-form-formInfo.md#formstateinfo)> | Promise对象。返回卡片状态。 | 1531 1532**错误码：** 1533 1534| 错误码ID | 错误信息 | 1535| -------- | -------- | 1536| 201 | Permissions denied. | 1537| 202 | The application is not a system application. | 1538| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1539| 16500050 | IPC connection error. | 1540| 16500060 | Service connection error. | 1541| 16500100 | Failed to obtain the configuration information. | 1542| 16501000 | An internal functional error occurred. | 1543 1544以上错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 1545 1546**示例：** 1547 1548```ts 1549import { formHost, formInfo } from '@kit.FormKit'; 1550import { Want } from '@kit.AbilityKit'; 1551import { BusinessError } from '@kit.BasicServicesKit'; 1552 1553let want: Want = { 1554 'deviceId': '', 1555 'bundleName': 'ohos.samples.FormApplication', 1556 'abilityName': 'FormAbility', 1557 'parameters': { 1558 'ohos.extra.param.key.module_name': 'entry', 1559 'ohos.extra.param.key.form_name': 'widget', 1560 'ohos.extra.param.key.form_dimension': 2 1561 } 1562}; 1563try { 1564 formHost.acquireFormState(want).then((data: formInfo.FormStateInfo) => { 1565 console.log(`formHost acquireFormState, data: ${JSON.stringify(data)}`); 1566 }).catch((error: BusinessError) => { 1567 console.error(`error, code: ${error.code}, message: ${error.message}`); 1568 }); 1569} catch(error) { 1570 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 1571} 1572``` 1573 1574## on('formUninstall') 1575 1576on(type: 'formUninstall', callback: Callback<string>): void 1577 1578订阅卡片卸载事件。使用callback异步回调。 1579 1580> **说明：** 1581> 1582> 卡片卸载与卡片移除不同。当应用卸载时，对应的卡片会自动卸载。 1583 1584**系统能力：** SystemCapability.Ability.Form 1585 1586**参数：** 1587 1588| 参数名 | 类型 | 必填 | 说明 | 1589| ------ | ------ | ---- | ------- | 1590| type | string | 是 | 填写'formUninstall'，表示卡片卸载事件。 | 1591| callback | Callback<string> | 是 | 回调函数，返回卡片标识。 | 1592 1593**错误码：** 1594 1595| 错误码ID | 错误信息 | 1596| -------- | -------- | 1597| 202 | The application is not a system application. | 1598| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1599 1600以上错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 1601 1602**示例：** 1603 1604```ts 1605import { formHost } from '@kit.FormKit'; 1606 1607formHost.on('formUninstall', (formId: string) => { 1608 console.log(`formHost on formUninstall, formId: ${formId}`); 1609}); 1610``` 1611 1612## off('formUninstall') 1613 1614off(type: 'formUninstall', callback?: Callback<string>): void 1615 1616取消订阅卡片卸载事件。使用callback异步回调。 1617 1618> **说明：** 1619> 1620> 卡片卸载与卡片移除不同。当应用卸载时，对应的卡片会自动卸载。 1621 1622**系统能力：** SystemCapability.Ability.Form 1623 1624**参数：** 1625 1626| 参数名 | 类型 | 必填 | 说明 | 1627| ------ | ------ | ---- | ------- | 1628| type | string | 是 | 填写'formUninstall'，表示卡片卸载事件。 | 1629| callback | Callback<string> | 否 | 回调函数，返回卡片标识。缺省时，表示注销所有已注册事件回调。<br> 需与对应on('formUninstall')的callback一致。| 1630 1631**错误码：** 1632 1633| 错误码ID | 错误信息 | 1634| -------- | -------- | 1635| 202 | The application is not a system application. | 1636| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1637 1638以上错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 1639 1640**示例：** 1641 1642```ts 1643import { formHost } from '@kit.FormKit'; 1644 1645formHost.off('formUninstall', (formId: string) => { 1646 console.log(`formHost on formUninstall, formId: ${formId}`); 1647}); 1648``` 1649 1650## notifyFormsVisible 1651 1652notifyFormsVisible(formIds: Array<string>, isVisible: boolean, callback: AsyncCallback<void>): void 1653 1654通知卡片是否可见。使用callback异步回调。 1655 1656**需要权限：** ohos.permission.REQUIRE_FORM 1657 1658**系统能力：** SystemCapability.Ability.Form 1659 1660**参数：** 1661 1662| 参数名 | 类型 | 必填 | 说明 | 1663| ------ | ------ | ---- | ------- | 1664| formIds | Array<string> | 是 | 卡片标识列表。 | 1665| isVisible | boolean | 是 | 是否可见。 | 1666| callback | AsyncCallback<void> | 是 | 回调函数。当通知卡片是否可见成功，error为undefined，否则为错误对象。 | 1667 1668**错误码：** 1669 1670| 错误码ID | 错误信息 | 1671| -------- | -------- | 1672| 201 | Permissions denied. | 1673| 202 | The application is not a system application. | 1674| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1675| 16500050 | IPC connection error. | 1676| 16500060 | Service connection error. | 1677| 16501000 | An internal functional error occurred. | 1678| 16501003 | The form cannot be operated by the current application. | 1679 1680以上错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 1681 1682**示例：** 1683 1684```ts 1685import { formHost } from '@kit.FormKit'; 1686import { BusinessError } from '@kit.BasicServicesKit'; 1687 1688let formIds: string[] = new Array('12400633174999288', '12400633174999289'); 1689try { 1690 formHost.notifyFormsVisible(formIds, true, (error: BusinessError) => { 1691 if (error) { 1692 console.error(`error, code: ${error.code}, message: ${error.message}`); 1693 } 1694 }); 1695} catch (error) { 1696 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 1697} 1698``` 1699 1700## notifyFormsVisible 1701 1702notifyFormsVisible(formIds: Array<string>, isVisible: boolean): Promise<void> 1703 1704通知卡片是否可见。使用Promise异步回调。 1705 1706**需要权限：** ohos.permission.REQUIRE_FORM 1707 1708**系统能力：** SystemCapability.Ability.Form 1709 1710**参数：** 1711 1712| 参数名 | 类型 | 必填 | 说明 | 1713| ------ | ------ | ---- | ------- | 1714| formIds | Array<string> | 是 | 卡片标识列表。 | 1715| isVisible | boolean | 是 | 是否可见。 | 1716 1717**返回值：** 1718 1719| 类型 | 说明 | 1720| -------- | -------- | 1721| Promise<void> | 无返回结果的Promise对象。 | 1722 1723**错误码：** 1724 1725| 错误码ID | 错误信息 | 1726| -------- | -------- | 1727| 201 | Permissions denied. | 1728| 202 | The application is not a system application. | 1729| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1730| 16500050 | IPC connection error. | 1731| 16500060 | Service connection error. | 1732| 16501000 | An internal functional error occurred. | 1733| 16501003 | The form cannot be operated by the current application. | 1734 1735以上错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 1736 1737**示例：** 1738 1739```ts 1740import { formHost } from '@kit.FormKit'; 1741import { BusinessError } from '@kit.BasicServicesKit'; 1742 1743let formIds: string[] = new Array('12400633174999288', '12400633174999289'); 1744try { 1745 formHost.notifyFormsVisible(formIds, true).then(() => { 1746 console.log('formHost notifyFormsVisible success'); 1747 }).catch((error: BusinessError) => { 1748 console.error(`error, code: ${error.code}, message: ${error.message}`); 1749 }); 1750} catch(error) { 1751 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 1752} 1753``` 1754 1755## notifyFormsEnableUpdate 1756 1757notifyFormsEnableUpdate(formIds: Array<string>, isEnableUpdate: boolean, callback: AsyncCallback<void>): void 1758 1759通知卡片是否启用更新状态。使用callback异步回调。 1760 1761**需要权限：** ohos.permission.REQUIRE_FORM 1762 1763**系统能力：** SystemCapability.Ability.Form 1764 1765**参数：** 1766 1767| 参数名 | 类型 | 必填 | 说明 | 1768| ------ | ------ | ---- | ------- | 1769| formIds | Array<string> | 是 | 卡片标识列表。 | 1770| isEnableUpdate | boolean | 是 | 是否使能更新。 | 1771| callback | AsyncCallback<void> | 是 | 回调函数。当通知卡片是否启用更新状态成功，error为undefined，否则为错误对象。 | 1772 1773**错误码：** 1774 1775| 错误码ID | 错误信息 | 1776| -------- | -------- | 1777| 201 | Permissions denied. | 1778| 202 | The application is not a system application. | 1779| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1780| 16500050 | IPC connection error. | 1781| 16500060 | Service connection error. | 1782| 16501000 | An internal functional error occurred. | 1783| 16501003 | The form cannot be operated by the current application. | 1784 1785以上错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 1786 1787**示例：** 1788 1789```ts 1790import { formHost } from '@kit.FormKit'; 1791import { BusinessError } from '@kit.BasicServicesKit'; 1792 1793let formIds: string[] = new Array('12400633174999288', '12400633174999289'); 1794try { 1795 formHost.notifyFormsEnableUpdate(formIds, true, (error: BusinessError) => { 1796 if (error) { 1797 console.error(`error, code: ${error.code}, message: ${error.message}`); 1798 } 1799 }); 1800} catch(error) { 1801 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 1802} 1803``` 1804 1805## notifyFormsEnableUpdate 1806 1807notifyFormsEnableUpdate(formIds: Array<string>, isEnableUpdate: boolean): Promise<void> 1808 1809通知卡片是否启用更新状态。使用Promise异步回调。 1810 1811**需要权限：** ohos.permission.REQUIRE_FORM 1812 1813**系统能力：** SystemCapability.Ability.Form 1814 1815**参数：** 1816 1817| 参数名 | 类型 | 必填 | 说明 | 1818| ------ | ------ | ---- | ------- | 1819| formIds | Array<string> | 是 | 卡片标识列表。 | 1820| isEnableUpdate | boolean | 是 | 是否使能更新。 | 1821 1822**返回值：** 1823 1824| 类型 | 说明 | 1825| -------- | -------- | 1826| Promise<void> | 无返回结果的Promise对象。 | 1827 1828**错误码：** 1829 1830| 错误码ID | 错误信息 | 1831| -------- | -------- | 1832| 201 | Permissions denied. | 1833| 202 | The application is not a system application. | 1834| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1835| 16500050 | IPC connection error. | 1836| 16500060 | Service connection error. | 1837| 16501000 | An internal functional error occurred. | 1838| 16501003 | The form cannot be operated by the current application. | 1839 1840以上错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 1841 1842**示例：** 1843 1844```ts 1845import { formHost } from '@kit.FormKit'; 1846import { BusinessError } from '@kit.BasicServicesKit'; 1847 1848let formIds: string[] = new Array('12400633174999288', '12400633174999289'); 1849try { 1850 formHost.notifyFormsEnableUpdate(formIds, true).then(() => { 1851 console.log('formHost notifyFormsEnableUpdate success'); 1852 }).catch((error: BusinessError) => { 1853 console.error(`error, code: ${error.code}, message: ${error.message}`); 1854 }); 1855} catch(error) { 1856 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 1857} 1858``` 1859## shareForm 1860 1861shareForm(formId: string, deviceId: string, callback: AsyncCallback<void>): void 1862 1863指定formId和远程设备Id进行卡片分享。使用callback异步回调。 1864 1865**需要权限：** ohos.permission.REQUIRE_FORM 和 ohos.permission.DISTRIBUTED_DATASYNC 1866 1867**系统能力：** SystemCapability.Ability.Form 1868 1869**参数：** 1870 1871| 参数名 | 类型 | 必填 | 说明 | 1872| ------ | ------ | ---- | ------- | 1873| formId | string | 是 | 卡片标识。 | 1874| deviceId | string | 是 | 远程设备标识。 | 1875| callback | AsyncCallback<void> | 是 | 回调函数。当指定formId和远程设备Id进行卡片分享成功，error为undefined，否则为错误对象。 | 1876 1877**错误码：** 1878 1879| 错误码ID | 错误信息 | 1880| -------- | -------- | 1881| 201 | Permissions denied. | 1882| 202 | The application is not a system application. | 1883| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1884| 16500050 | IPC connection error. | 1885| 16501000 | An internal functional error occurred. | 1886| 16501001 | The ID of the form to be operated does not exist. | 1887| 16501003 | The form cannot be operated by the current application. | 1888 1889以上错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 1890 1891**示例：** 1892 1893```ts 1894import { formHost } from '@kit.FormKit'; 1895import { BusinessError } from '@kit.BasicServicesKit'; 1896 1897let formId: string = '12400633174999288'; 1898let deviceId: string = 'EFC11C0C53628D8CC2F8CB5052477E130D075917034613B9884C55CD22B3DEF2'; 1899try { 1900 formHost.shareForm(formId, deviceId, (error: BusinessError) => { 1901 if (error) { 1902 console.error(`error, code: ${error.code}, message: ${error.message}`); 1903 } 1904 }); 1905} catch(error) { 1906 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 1907} 1908``` 1909 1910## shareForm 1911 1912shareForm(formId: string, deviceId: string): Promise<void> 1913 1914指定formId和远程设备Id进行卡片分享。使用Promise异步回调。 1915 1916**需要权限：** ohos.permission.REQUIRE_FORM 和 ohos.permission.DISTRIBUTED_DATASYNC 1917 1918**系统能力：** SystemCapability.Ability.Form 1919 1920**参数：** 1921 1922| 参数名 | 类型 | 必填 | 说明 | 1923| ------ | ------ | ---- | ------- | 1924| formId | string | 是 | 卡片标识。 | 1925| deviceId | string | 是 | 远程设备标识。 | 1926 1927**返回值：** 1928 1929| 类型 | 说明 | 1930| -------- | -------- | 1931| Promise<void> | 无返回结果的Promise对象。 | 1932 1933**错误码：** 1934 1935| 错误码ID | 错误信息 | 1936| -------- | -------- | 1937| 201 | Permissions denied. | 1938| 202 | The application is not a system application. | 1939| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1940| 16500050 | IPC connection error. | 1941| 16501000 | An internal functional error occurred. | 1942| 16501001 | The ID of the form to be operated does not exist. | 1943| 16501003 | The form cannot be operated by the current application. | 1944 1945以上错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 1946 1947**示例：** 1948 1949```ts 1950import { formHost } from '@kit.FormKit'; 1951import { BusinessError } from '@kit.BasicServicesKit'; 1952 1953let formId: string = '12400633174999288'; 1954let deviceId: string = 'EFC11C0C53628D8CC2F8CB5052477E130D075917034613B9884C55CD22B3DEF2'; 1955try { 1956 formHost.shareForm(formId, deviceId).then(() => { 1957 console.log('formHost shareForm success'); 1958 }).catch((error: BusinessError) => { 1959 console.error(`error, code: ${error.code}, message: ${error.message}`); 1960 }); 1961} catch(error) { 1962 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 1963} 1964``` 1965 1966## notifyFormsPrivacyProtected 1967 1968notifyFormsPrivacyProtected(formIds: Array\<string>, isProtected: boolean, callback: AsyncCallback\<void>): void 1969 1970通知指定卡片隐私保护状态改变。使用callback异步回调。 1971 1972**需要权限：** ohos.permission.REQUIRE_FORM 1973 1974**系统能力：** SystemCapability.Ability.Form 1975 1976**参数：** 1977 1978| 参数名 | 类型 | 必填 | 说明 | 1979| ------ | ------ | ---- | ------- | 1980| formIds | Array\<string\> | 是 | 需要修改隐私保护的卡片标识列表。 | 1981| isProtected | boolean | 是 | 是否进行隐私保护。 | 1982| callback | AsyncCallback\<void> | 是 | 回调函数。当指定卡片设置隐私保护属性成功，error为undefined，否则为错误对象。 | 1983 1984**错误码：** 1985 1986| 错误码ID | 错误信息 | 1987| -------- | -------- | 1988| 201 | Permissions denied. | 1989| 202 | The application is not a system application. | 1990| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1991| 16500050 | IPC connection error. | 1992| 16500060 | Service connection error. | 1993| 16501000 | An internal functional error occurred. | 1994 1995以上错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 1996 1997**示例：** 1998 1999```ts 2000import { formHost } from '@kit.FormKit'; 2001import { BusinessError } from '@kit.BasicServicesKit'; 2002 2003let formIds: string[] = new Array('12400633174999288', '12400633174999289'); 2004try { 2005 formHost.notifyFormsPrivacyProtected(formIds, true, (error: BusinessError) => { 2006 if (error) { 2007 console.error(`error, code: ${error.code}, message: ${error.message}`); 2008 } 2009 }); 2010} catch(error) { 2011 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 2012} 2013``` 2014 2015## notifyFormsPrivacyProtected 2016 2017notifyFormsPrivacyProtected(formIds: Array\<string\>, isProtected: boolean): Promise\<void\> 2018 2019通知指定卡片隐私保护状态改变。使用Promise异步回调。 2020 2021**需要权限：** ohos.permission.REQUIRE_FORM 2022 2023**系统能力：** SystemCapability.Ability.Form 2024 2025**参数：** 2026 2027| 参数名 | 类型 | 必填 | 说明 | 2028| ----------- | --------------- | ---- | -------------------------------- | 2029| formIds | Array\<string\> | 是 | 需要修改隐私保护的卡片标识列表。 | 2030| isProtected | boolean | 是 | 是否进行隐私保护。 | 2031 2032**返回值：** 2033 2034| 类型 | 说明 | 2035| ------------------- | ------------------------- | 2036| Promise<void> | 无返回结果的Promise对象。 | 2037 2038**错误码：** 2039 2040| 错误码ID | 错误信息 | 2041| -------- | -------- | 2042| 201 | Permissions denied. | 2043| 202 | The application is not a system application. | 2044| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 2045| 16500050 | IPC connection error. | 2046| 16500060 | Service connection error. | 2047| 16501000 | An internal functional error occurred. | 2048 2049以上错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 2050 2051```ts 2052import { formHost } from '@kit.FormKit'; 2053import { BusinessError } from '@kit.BasicServicesKit'; 2054 2055let formIds: string[] = new Array('12400633174999288', '12400633174999289'); 2056try { 2057 formHost.notifyFormsPrivacyProtected(formIds, true).then(() => { 2058 console.log('formHost notifyFormsPrivacyProtected success'); 2059 }).catch((error: BusinessError) => { 2060 console.error(`error, code: ${error.code}, message: ${error.message}`); 2061 }); 2062} catch(error) { 2063 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 2064} 2065``` 2066 2067## acquireFormData<sup>10+</sup> 2068 2069acquireFormData(formId: string, callback: AsyncCallback\<Record\<string, Object>>): void 2070 2071请求卡片提供方数据。使用callback异步回调。 2072 2073**模型约束：** 此接口仅可在Stage模型下使用。 2074 2075**需要权限：** ohos.permission.REQUIRE_FORM 2076 2077**系统能力：** SystemCapability.Ability.Form 2078 2079**参数：** 2080 2081| 参数名 | 类型 | 必填 | 说明 | 2082| ------ | ------ | ---- | ------- | 2083| formId | string | 是 | 卡片标识。 | 2084| callback | AsyncCallback\<Record\<string, Object> | 是 | 以callback方式返回接口运行结果及分享数据。 | 2085 2086**错误码：** 2087 2088| 错误码ID | 错误信息 | 2089| -------- | -------- | 2090| 201 | Permissions denied. | 2091| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 2092| 16500050 | IPC connection error. | 2093| 16500060 | Service connection error. | 2094| 16500100 | Failed to obtain the configuration information. | 2095| 16501000 | An internal functional error occurred. | 2096 2097以上错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 2098 2099**示例：** 2100 2101```ts 2102import { formHost } from '@kit.FormKit'; 2103import { BusinessError } from '@kit.BasicServicesKit'; 2104 2105let formId: string = '12400633174999288'; 2106try { 2107 formHost.acquireFormData(formId, (error, data) => { 2108 if (error) { 2109 console.error(`error, code: ${error.code}, message: ${error.message}`); 2110 } else { 2111 console.log(`formHost acquireFormData, data: ${JSON.stringify(data)}`); 2112 } 2113 }); 2114} catch(error) { 2115 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 2116} 2117``` 2118 2119## acquireFormData<sup>10+</sup> 2120 2121acquireFormData(formId: string): Promise\<Record\<string, Object>> 2122 2123请求卡片提供方数据。使用Promise异步回调。 2124 2125**模型约束：** 此接口仅可在Stage模型下使用。 2126 2127**需要权限：** ohos.permission.REQUIRE_FORM 2128 2129**系统能力：** SystemCapability.Ability.Form 2130 2131**参数：** 2132 2133| 参数名 | 类型 | 必填 | 说明 | 2134| ----------- | --------------- | ---- | -------------------------------- | 2135| formId | string | 是 | 卡片标识。 | 2136 2137**返回值：** 2138 2139| 类型 | 说明 | 2140| ------------------- | ------------------------- | 2141| Promise\<Record\<string, Object>>| 以Promise方式返回接口运行结果及分享数据。 | 2142 2143**错误码：** 2144 2145| 错误码ID | 错误信息 | 2146| -------- | -------- | 2147| 201 | Permissions denied. | 2148| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 2149| 16500050 | IPC connection error. | 2150| 16500060 | Service connection error. | 2151| 16500100 | Failed to obtain the configuration information. | 2152| 16501000 | An internal functional error occurred. | 2153 2154以上错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 2155 2156```ts 2157import { formHost } from '@kit.FormKit'; 2158import { BusinessError } from '@kit.BasicServicesKit'; 2159 2160let formId: string = '12400633174999288'; 2161try { 2162 formHost.acquireFormData(formId).then((data) => { 2163 console.log('formHost acquireFormData success' + data); 2164 }).catch((error: BusinessError) => { 2165 console.error(`error, code: ${error.code}, message: ${error.message}`); 2166 }); 2167} catch(error) { 2168 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 2169} 2170``` 2171 2172## setRouterProxy<sup>11+</sup> 2173 2174setRouterProxy(formIds: Array<string>, proxy: Callback<Want>, callback: AsyncCallback<void>): void 2175 2176设置卡片跳转代理。使用callback异步回调，返回卡片跳转所需要Want信息。 2177 2178 2179 2180> **说明：** 2181> 2182>- 一般情况下，对于桌面添加的卡片，当卡片触发router跳转时，卡片框架会检测其跳转目的地是否合理，是否有跳转权限，然后进行应用跳转。如果卡片使用方添加了卡片，并设置了卡片跳转代理，那么卡片触发router跳转时，卡片框架不会再为其进行跳转操作，会把包含跳转目的地的want参数返回给卡片使用方。因此如果卡片使用方希望使用该want信息进行应用跳转，需要确保自身拥有应用跳转的权限，参考 2183[UIAbilityContext.startAbility()](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability)接口。 2184> 2185>- 一个formId最多只能设置一个跳转代理，多次设置后，最后设置的proxy生效。 2186 2187**需要权限：** ohos.permission.REQUIRE_FORM 2188 2189**系统能力：** SystemCapability.Ability.Form 2190 2191**参数：** 2192 2193| 参数名 | 类型 | 必填 | 说明 | 2194| -------- | ------------------------- | ---- | ------------------------------------------------------------ | 2195| formIds | Array<string> | 是 | 卡片标识数组。 | 2196| proxy | Callback<Want> | 是 | 回调函数。返回跳转所需要的Want信息。 | 2197| callback | AsyncCallback<void> | 是 | 回调函数，当指定卡片设置router跳转代理成功时，error为undefined；否则抛出异常。 | 2198 2199**错误码：** 2200 2201| 错误码ID | 错误信息 | 2202| -------- | ------------------------------------------------------------ | 2203| 201 | Permissions denied. | 2204| 202 | The application is not a system application. | 2205| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 2206| 16500050 | IPC connection error. | 2207| 16500060 | Service connection error. | 2208| 16501000 | An internal functional error occurred. | 2209| 16501003 | The form cannot be operated by the current application. | 2210 2211以上错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 2212 2213**示例：** 2214 2215```ts 2216import { common, Want } from '@kit.AbilityKit'; 2217import { formHost } from '@kit.FormKit'; 2218import { BusinessError } from '@kit.BasicServicesKit'; 2219 2220@Entry 2221@Component 2222struct CardExample { 2223 private context = getContext(this) as common.UIAbilityContext; 2224 @State formId: number = 0; 2225 @State fwidth: number = 420; 2226 @State fheight: number = 280; 2227 2228 build() { 2229 Column() { 2230 FormComponent({ 2231 id: this.formId, 2232 name: "widget", 2233 bundle: "com.example.cardprovider", 2234 ability: "EntryFormAbility", 2235 module: "entry", 2236 dimension: FormDimension.Dimension_2_2, 2237 temporary: false, 2238 }) 2239 .allowUpdate(true) 2240 .size({ width: this.fwidth, height: this.fheight }) 2241 .visibility(Visibility.Visible) 2242 .onAcquired((form) => { 2243 console.log(`testTag form info : ${JSON.stringify(form)}`); 2244 this.formId = form.id; 2245 try { 2246 let formIds: string[] = [this.formId.toString()]; 2247 formHost.setRouterProxy(formIds, (want: Want) => { 2248 console.info(`formHost recv router event, want: ${JSON.stringify(want)}`); 2249 // 卡片使用方自己处理跳转 2250 this.context.startAbility(want, (err: BusinessError) => { 2251 console.info(`formHost startAbility error, code: ${err.code}, message: ${err.message}`); 2252 }); 2253 }, (err: BusinessError) => { 2254 console.error(`set router proxy error, code: ${err.code}, message: ${err.message}`); 2255 }) 2256 } catch (e) { 2257 console.log('formHost setRouterProxy catch exception: ' + JSON.stringify(e)); 2258 } 2259 }) 2260 } 2261 .width('100%') 2262 .height('100%') 2263 } 2264} 2265``` 2266 2267## setRouterProxy<sup>11+</sup> 2268 2269setRouterProxy(formIds: Array<string>, proxy: Callback<Want>): Promise<void> 2270 2271设置卡片跳转代理。使用Promise异步回调，返回卡片跳转所需要Want信息。 2272 2273> **说明：** 2274> 2275>- 一般情况下，对于桌面添加的卡片，当卡片触发router跳转时，卡片框架会检测其跳转目的地是否合理，是否有跳转权限，然后进行应用跳转。如果卡片使用方添加了卡片，并设置了卡片跳转代理，那么卡片触发router跳转时，卡片框架不会再为其进行跳转操作，会把包含跳转目的地的want参数返回给卡片使用方。因此如果卡片使用方希望使用该want信息进行应用跳转，需要确保自身拥有应用跳转的权限，参考[UIAbilityContext.startAbility()](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability)接口。 2276> 2277>- 一个formId最多只能设置一个跳转代理，多次设置后，最后设置的proxy生效。 2278 2279 2280 2281**需要权限：** ohos.permission.REQUIRE_FORM 2282 2283**系统能力：** SystemCapability.Ability.Form 2284 2285**参数：** 2286 2287| 参数名 | 类型 | 必填 | 说明 | 2288| ------- | -------------------- | ---- | ------------------------------------ | 2289| formIds | Array<string> | 是 | 卡片标识数组。 | 2290| proxy | Callback<Want> | 是 | 回调函数。返回跳转所需要的Want信息。 | 2291 2292**返回值：** 2293 2294| 类型 | 说明 | 2295| ------------------- | ------------------------- | 2296| Promise<void> | 无返回结果的Promise对象。 | 2297 2298**错误码：** 2299 2300| 错误码ID | 错误信息 | 2301| -------- | ------------------------------------------------------------ | 2302| 201 | Permissions denied. | 2303| 202 | The application is not a system application. | 2304| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 2305| 16500050 | IPC connection error. | 2306| 16500060 | Service connection error. | 2307| 16501000 | An internal functional error occurred. | 2308| 16501003 | The form cannot be operated by the current application. | 2309 2310以上错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 2311 2312**示例：** 2313 2314```ts 2315import { formHost } from '@kit.FormKit'; 2316import { common, Want } from '@kit.AbilityKit'; 2317import { BusinessError } from '@kit.BasicServicesKit'; 2318 2319@Entry 2320@Component 2321struct CardExample { 2322 private context = getContext(this) as common.UIAbilityContext; 2323 @State formId: number = 0; 2324 @State fwidth: number = 420; 2325 @State fheight: number = 280; 2326 2327 build() { 2328 Column() { 2329 FormComponent({ 2330 id: this.formId, 2331 name: "widget", 2332 bundle: "com.example.cardprovider", 2333 ability: "EntryFormAbility", 2334 module: "entry", 2335 dimension: FormDimension.Dimension_2_2, 2336 temporary: false, 2337 }) 2338 .allowUpdate(true) 2339 .size({ width: this.fwidth, height: this.fheight }) 2340 .visibility(Visibility.Visible) 2341 .onAcquired((form) => { 2342 console.log(`testTag form info : ${JSON.stringify(form)}`); 2343 this.formId = form.id; 2344 try { 2345 let formIds: string[] = [this.formId.toString()]; 2346 formHost.setRouterProxy(formIds, (want: Want) => { 2347 console.info(`formHost recv router event, want: ${JSON.stringify(want)}`); 2348 // 卡片使用方自己处理跳转 2349 this.context.startAbility(want, (err: BusinessError) => { 2350 console.info(`formHost startAbility error, code: ${err.code}, message: ${err.message}`); 2351 }); 2352 }).then(() => { 2353 console.info('formHost set router proxy success'); 2354 }).catch((err: BusinessError) => { 2355 console.error(`set router proxy error, code: ${err.code}, message: ${err.message}`); 2356 }) 2357 } catch (e) { 2358 console.log('formHost setRouterProxy catch exception: ' + JSON.stringify(e)); 2359 } 2360 }) 2361 } 2362 .width('100%') 2363 .height('100%') 2364 } 2365} 2366``` 2367 2368## clearRouterProxy<sup>11+</sup> 2369 2370clearRouterProxy(formIds:Array<string>, callback: AsyncCallback<void>): void 2371 2372清除卡片跳转代理。使用callback异步回调。 2373 2374**需要权限：** ohos.permission.REQUIRE_FORM 2375 2376**系统能力：** SystemCapability.Ability.Form 2377 2378**参数：** 2379 2380| 参数名 | 类型 | 必填 | 说明 | 2381| -------- | ------------------------- | ---- | ------------------------------------------------------------ | 2382| formIds | Array<string>; | 是 | 卡片标识数组。 | 2383| callback | AsyncCallback<void> | 是 | 回调函数，当指定卡片取消router跳转代理成功时，error为undefined；否则抛出异常。 | 2384 2385**错误码：** 2386 2387| 错误码ID | 错误信息 | 2388| -------- | ------------------------------------------------------------ | 2389| 201 | Permissions denied. | 2390| 202 | The application is not a system application. | 2391| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 2392| 16500050 | IPC connection error. | 2393| 16500060 | Service connection error. | 2394| 16501000 | An internal functional error occurred. | 2395| 16501003 | The form cannot be operated by the current application. | 2396 2397以上错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 2398 2399**示例：** 2400 2401```ts 2402import { formHost } from '@kit.FormKit'; 2403import { BusinessError } from '@kit.BasicServicesKit'; 2404 2405try { 2406 let formIds: string[] = ['12400633174999288']; 2407 formHost.clearRouterProxy(formIds, (err: BusinessError) => { 2408 if (err) { 2409 console.error(`formHost clear router proxy error, code: ${err.code}, message: ${err.message}`); 2410 } 2411 }); 2412} catch (error) { 2413 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 2414} 2415``` 2416 2417## clearRouterProxy<sup>11+</sup> 2418 2419clearRouterProxy(formIds:Array<string>): Promise<void> 2420 2421清除卡片跳转代理。使用Promise异步回调。 2422 2423**需要权限：** ohos.permission.REQUIRE_FORM 2424 2425**系统能力：** SystemCapability.Ability.Form 2426 2427**参数：** 2428 2429| 参数名 | 类型 | 必填 | 说明 | 2430| ------- | ------------------- | ---- | -------------- | 2431| formIds | Array<string> | 是 | 卡片标识数组。 | 2432 2433**返回值：** 2434 2435| 类型 | 说明 | 2436| ------------------- | ------------------------- | 2437| Promise<void> | 无返回结果的Promise对象。 | 2438 2439**错误码：** 2440 2441| 错误码ID | 错误信息 | 2442| -------- | ------------------------------------------------------------ | 2443| 201 | Permissions denied. | 2444| 202 | The application is not a system application. | 2445| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 2446| 16500050 | IPC connection error. | 2447| 16500060 | Service connection error. | 2448| 16501000 | An internal functional error occurred. | 2449| 16501003 | The form cannot be operated by the current application. | 2450 2451以上错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 2452 2453**示例：** 2454 2455```ts 2456import { formHost } from '@kit.FormKit'; 2457import { BusinessError } from '@kit.BasicServicesKit'; 2458 2459try { 2460 let formIds: string[] = ['12400633174999288']; 2461 formHost.clearRouterProxy(formIds).then(() => { 2462 console.log('formHost clear rourter proxy success'); 2463 }).catch((err: BusinessError) => { 2464 console.error(`formHost clear router proxy error, code: ${err.code}, message: ${err.message}`); 2465 }); 2466} catch (error) { 2467 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 2468} 2469``` 2470## setFormsRecyclable<sup>11+</sup> 2471 2472setFormsRecyclable(formIds:Array<string>, callback: AsyncCallback<void>): void 2473 2474设置卡片可回收。使用callback异步回调。 2475 2476**模型约束：** 此接口仅可在Stage模型下使用。 2477 2478**需要权限：** ohos.permission.REQUIRE_FORM 2479 2480**系统能力：** SystemCapability.Ability.Form 2481 2482**参数：** 2483 2484| 参数名 | 类型 | 必填 | 说明 | 2485| -------- | ------------------------- | ---- | ------------------------------------------------------------ | 2486| formIds | Array<string>; | 是 | 卡片标识数组。 | 2487| callback | AsyncCallback<void> | 是 | 回调函数，当设置卡片可回收成功时，error为undefined；否则抛出异常。 | 2488 2489**错误码：** 2490 2491| 错误码ID | 错误信息 | 2492| -------- | ------------------------------------------------------------ | 2493| 201 | Permissions denied. | 2494| 202 | The application is not a system application. | 2495| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 2496| 16500050 | IPC connection error. | 2497| 16500060 | Service connection error. | 2498| 16501000 | An internal functional error occurred. | 2499 2500以上错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 2501 2502**示例：** 2503 2504```ts 2505import { formHost } from '@kit.FormKit'; 2506import { BusinessError } from '@kit.BasicServicesKit'; 2507 2508try { 2509 let formIds: string[] = ['12400633174999288']; 2510 formHost.setFormsRecyclable(formIds, (err: BusinessError) => { 2511 if (err) { 2512 console.error(`setFormsRecyclable error, code: ${err.code}, message: ${err.message}`); 2513 } 2514 }); 2515} catch (error) { 2516 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 2517} 2518``` 2519 2520## setFormsRecyclable<sup>11+</sup> 2521 2522setFormsRecyclable(formIds:Array<string>): Promise<void> 2523 2524设置卡片可回收。使用Promise异步回调。 2525 2526**模型约束：** 此接口仅可在Stage模型下使用。 2527 2528**需要权限：** ohos.permission.REQUIRE_FORM 2529 2530**系统能力：** SystemCapability.Ability.Form 2531 2532**参数：** 2533 2534| 参数名 | 类型 | 必填 | 说明 | 2535| ------- | ------------------- | ---- | -------------- | 2536| formIds | Array<string> | 是 | 卡片标识数组。 | 2537 2538**返回值：** 2539 2540| 类型 | 说明 | 2541| ------------------- | ------------------------- | 2542| Promise<void> | 无返回结果的Promise对象。 | 2543 2544**错误码：** 2545 2546| 错误码ID | 错误信息 | 2547| -------- | ------------------------------------------------------------ | 2548| 201 | Permissions denied. | 2549| 202 | The application is not a system application. | 2550| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 2551| 16500050 | IPC connection error. | 2552| 16500060 | Service connection error. | 2553| 16501000 | An internal functional error occurred. | 2554 2555以上错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 2556 2557**示例：** 2558 2559```ts 2560import { formHost } from '@kit.FormKit'; 2561import { BusinessError } from '@kit.BasicServicesKit'; 2562 2563try { 2564 let formIds: string[] = ['12400633174999288']; 2565 formHost.setFormsRecyclable(formIds).then(() => { 2566 console.log('setFormsRecyclable success'); 2567 }).catch((err: BusinessError) => { 2568 console.error(`setFormsRecyclable error, code: ${err.code}, message: ${err.message}`); 2569 }); 2570} catch (error) { 2571 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 2572} 2573``` 2574## recoverForms<sup>11+</sup> 2575 2576recoverForms(formIds:Array<string>, callback: AsyncCallback<void>): void 2577 2578恢复卡片。使用callback异步回调。 2579 2580**模型约束：** 此接口仅可在Stage模型下使用。 2581 2582**需要权限：** ohos.permission.REQUIRE_FORM 2583 2584**系统能力：** SystemCapability.Ability.Form 2585 2586**参数：** 2587 2588| 参数名 | 类型 | 必填 | 说明 | 2589| -------- | ------------------------- | ---- | ------------------------------------------------------------ | 2590| formIds | Array<string>; | 是 | 卡片标识数组。 | 2591| callback | AsyncCallback<void> | 是 | 回调函数，当恢复卡片成功时，error为undefined；否则抛出异常。 | 2592 2593**错误码：** 2594 2595| 错误码ID | 错误信息 | 2596| -------- | ------------------------------------------------------------ | 2597| 201 | Permissions denied. | 2598| 202 | The application is not a system application. | 2599| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 2600| 16500050 | IPC connection error. | 2601| 16500060 | Service connection error. | 2602| 16501000 | An internal functional error occurred. | 2603 2604以上错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 2605 2606**示例：** 2607 2608```ts 2609import { formHost } from '@kit.FormKit'; 2610import { BusinessError } from '@kit.BasicServicesKit'; 2611 2612try { 2613 let formIds: string[] = ['12400633174999288']; 2614 formHost.recoverForms(formIds, (err: BusinessError) => { 2615 if (err) { 2616 console.error(`recoverForms error, code: ${err.code}, message: ${err.message}`); 2617 } 2618 }); 2619} catch (error) { 2620 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 2621} 2622``` 2623## recoverForms<sup>11+</sup> 2624 2625recoverForms(formIds: Array<string>): Promise<void> 2626 2627恢复被回收的卡片，并将它的状态更新为不可回收，如果卡片未被回收则只更新状态为不可回收。使用Promise异步回调。 2628 2629**模型约束：** 此接口仅可在Stage模型下使用。 2630 2631**需要权限：** ohos.permission.REQUIRE_FORM 2632 2633**系统能力：** SystemCapability.Ability.Form 2634 2635**参数：** 2636 2637| 参数名 | 类型 | 必填 | 说明 | 2638| ------- | ------------------- | ---- | -------------- | 2639| formIds | Array<string> | 是 | 卡片标识数组。 | 2640 2641**返回值：** 2642 2643| 类型 | 说明 | 2644| ------------------- | ------------------------- | 2645| Promise<void> | 无返回结果的Promise对象。 | 2646 2647 2648**错误码：** 2649 2650| 错误码ID | 错误信息 | 2651| -------- | ------------------------------------------------------------ | 2652| 201 | Permissions denied. | 2653| 202 | The application is not a system application. | 2654| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 2655| 16500050 | IPC connection error. | 2656| 16500060 | Service connection error. | 2657| 16501000 | An internal functional error occurred. | 2658 2659以上错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 2660 2661**示例：** 2662 2663```ts 2664import { formHost } from '@kit.FormKit'; 2665import { BusinessError } from '@kit.BasicServicesKit'; 2666 2667try { 2668 let formIds: string[] = ['12400633174999288']; 2669 formHost.recoverForms(formIds).then(() => { 2670 console.info('recover forms success'); 2671 }).catch((err: BusinessError) => { 2672 console.error(`formHost recover forms error, code: ${err.code}, message: ${err.message}`); 2673 }); 2674} catch (e) { 2675 console.info(`catch error, code: ${e.code}, message: ${e.message}`); 2676} 2677``` 2678## recycleForms<sup>12+</sup> 2679 2680recycleForms(formIds: Array<string>): Promise<void> 2681 2682立即回收卡片内存。使用Promise异步回调。 2683 2684**模型约束：** 此接口仅可在Stage模型下使用。 2685 2686**需要权限：** ohos.permission.REQUIRE_FORM 2687 2688**系统能力：** SystemCapability.Ability.Form 2689 2690**参数：** 2691 2692| 参数名 | 类型 | 必填 | 说明 | 2693| ------- | ------------------- | ---- | -------------- | 2694| formIds | Array<string> | 是 | 卡片标识数组。 | 2695 2696**返回值：** 2697 2698| 类型 | 说明 | 2699| ------------------- | ------------------------- | 2700| Promise<void> | 无返回结果的Promise对象。 | 2701 2702 2703**错误码：** 2704 2705| 错误码ID | 错误信息 | 2706| -------- | ------------------------------------------------------------ | 2707| 201 | Permissions denied. | 2708| 202 | The application is not a system application. | 2709| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 2710| 16500050 | IPC connection error. | 2711| 16500060 | Service connection error. | 2712| 16501000 | An internal functional error occurred. | 2713 2714以上错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 2715 2716**示例：** 2717 2718```ts 2719import { formHost } from '@kit.FormKit'; 2720import { BusinessError } from '@kit.BasicServicesKit'; 2721 2722try { 2723 let formIds: string[] = ['12400633174999288']; 2724 formHost.recycleForms(formIds).then(() => { 2725 console.info('recycle forms success'); 2726 }).catch((err: BusinessError) => { 2727 console.error(`formHost recycle forms error, code: ${err.code}, message: ${err.message}`); 2728 }); 2729} catch (e) { 2730 console.error(`catch error, code: ${e.code}, message: ${e.message}`); 2731} 2732``` 2733 2734## updateFormLocation<sup>12+</sup> 2735updateFormLocation(formId: string, location: formInfo.FormLocation): void; 2736 2737更新卡片位置。 2738 2739**模型约束**: 此接口仅可在Stage模型下使用。 2740 2741**需要权限**：ohos.permission.REQUIRE_FORM 2742 2743**系统能力**：SystemCapability.Ability.Form 2744 2745**参数：** 2746 2747| 参数名 | 类型 | 必填 | 说明 | 2748| ------ | ------ | ---- | ------- | 2749| formId | string | 是 | 卡片标识。 | 2750| location |[formInfo.FormLocation](js-apis-app-form-formInfo-sys.md#formlocation) | 是 | 卡片位置。 | 2751 2752**错误码：** 2753 2754| 错误码ID | 错误信息 | 2755| -------- | ------------------------------------------------------------ | 2756| 201 | Permissions denied. | 2757| 202 | The application is not a system application. | 2758| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 2759| 16500050 | IPC connection error. | 2760| 16500060 | Service connection error. | 2761| 16501000 | An internal functional error occurred. | 2762| 16501001 | The ID of the form to be operated does not exist. | 2763| 16501003 | The form cannot be operated by the current application. | 2764 2765以上错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 2766 2767**示例：** 2768 2769```ts 2770import { formHost, formInfo } from '@kit.FormKit'; 2771import { BusinessError } from '@kit.BasicServicesKit'; 2772 2773try { 2774 let formId: string = '12400633174999288'; 2775 formHost.updateFormLocation(formId, formInfo.FormLocation.SCREEN_LOCK); 2776} catch (error) { 2777 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 2778} 2779``` 2780 2781## setPublishFormResult<sup>12+</sup> 2782 2783setPublishFormResult(formId: string, result: formInfo.PublishFormResult): void; 2784 2785设置卡片加桌结果。 2786 2787**模型约束**: 此接口仅可在Stage模型下使用。 2788 2789**需要权限**：ohos.permission.REQUIRE_FORM 2790 2791**系统能力**：SystemCapability.Ability.Form 2792 2793**参数：** 2794 2795| 参数名 | 类型 | 必填 | 说明 | 2796| ------ | ------------------------------------------------------------ | ---- | ------------------ | 2797| formId | string | 是 | 卡片标识。 | 2798| result | [PublishFormResult](js-apis-app-form-formInfo-sys.md#publishformresult) | 是 | 发布卡片加桌结果。 | 2799 2800**错误码：** 2801 2802| 错误码ID | 错误信息 | 2803| -------- | ------------------------------------------------------------ | 2804| 201 | Permissions denied. | 2805| 202 | The application is not a system application. | 2806| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 2807| 16500050 | IPC connection error. | 2808| 16500060 | Service connection error. | 2809| 16501000 | An internal functional error occurred. | 2810| 16501001 | The ID of the form to be operated does not exist. | 2811 2812以上错误码的详细介绍请参见[卡片错误码](errorcode-form.md)。 2813 2814**示例：** 2815 2816```ts 2817import { formHost, formInfo } from '@kit.FormKit'; 2818import { BusinessError } from '@kit.BasicServicesKit'; 2819 2820try { 2821 let formId: string = '12400633174999288'; 2822 let res: formInfo.PublishFormResult = {code: formInfo.PublishFormErrorCode.SUCCESS, message: ''}; 2823 formHost.setPublishFormResult(formId, res); 2824} catch (error) { 2825 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 2826} 2827``` 2828