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