1# @ohos.application.formHost (formHost)(系统接口) 2 3formHost模块提供了卡片使用方相关接口的能力，包括对使用方同一用户下安装的卡片进行删除、释放、请求更新，获取信息、状态等操作。 4 5> **说明：** 6> 7> 本模块首批接口从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8> 从API version 9 开始不再维护，建议使用[formHost](js-apis-app-form-formHost-sys.md)替代。 9> 本模块接口均为系统接口。 10 11## 导入模块 12 13```ts 14import formHost from '@ohos.application.formHost'; 15``` 16 17## deleteForm 18 19deleteForm(formId: string, callback: AsyncCallback<void>): void 20 21删除指定的卡片。调用此方法后，应用程序将无法使用该卡片，卡片管理器服务不再保留有关该卡片的信息。使用callback异步回调。 22 23**需要权限：** ohos.permission.REQUIRE_FORM 24 25**系统能力：** SystemCapability.Ability.Form 26 27**参数：** 28 29| 参数名 | 类型 | 必填 | 说明 | 30| ------ | ------ | ---- | ------- | 31| formId | string | 是 | 卡片标识。 | 32| callback | AsyncCallback<void> | 是 | 回调函数。当删除指定的卡片成功，error为undefined，否则为错误对象。 | 33 34**示例：** 35 36```ts 37import Base from '@ohos.base'; 38 39let formId: string = '12400633174999288'; 40formHost.deleteForm(formId, (error: Base.BusinessError) => { 41 if (error.code) { 42 console.error(`formHost deleteForm, error: ${JSON.stringify(error)}`); 43 } 44}); 45``` 46 47## deleteForm 48 49deleteForm(formId: string): Promise<void> 50 51删除指定的卡片。调用此方法后，应用程序将无法使用该卡片，卡片管理器服务不再保留有关该卡片的信息。使用Promise异步回调。 52 53**需要权限：** ohos.permission.REQUIRE_FORM 54 55**系统能力：** SystemCapability.Ability.Form 56 57**参数：** 58 59| 参数名 | 类型 | 必填 | 说明 | 60| ------ | ------ | ---- | ------- | 61| formId | string | 是 | 卡片标识。 | 62 63**返回值：** 64 65| 类型 | 说明 | 66| -------- | -------- | 67| Promise<void> | 无返回结果的Promise对象。 | 68 69**示例：** 70 71```ts 72import Base from '@ohos.base'; 73 74let formId: string = '12400633174999288'; 75formHost.deleteForm(formId).then(() => { 76 console.log('formHost deleteForm success'); 77}).catch((error: Base.BusinessError) => { 78 console.error(`formHost deleteForm, error: ${JSON.stringify(error)}`); 79}); 80``` 81 82## releaseForm 83 84releaseForm(formId: string, callback: AsyncCallback<void>): void 85 86释放指定的卡片。调用此方法后，应用程序将无法使用该卡片，但卡片管理器服务仍然保留有关该卡片的缓存信息和存储信息。使用callback异步回调。 87 88**需要权限：** ohos.permission.REQUIRE_FORM 89 90**系统能力：** SystemCapability.Ability.Form 91 92**参数：** 93 94| 参数名 | 类型 | 必填 | 说明 | 95| ------ | ------ | ---- | ------- | 96| formId | string | 是 | 卡片标识。 | 97| callback | AsyncCallback<void> | 是 | 回调函数。当释放指定的卡片成功，error为undefined；否则为错误对象。| 98 99**示例：** 100 101```ts 102import Base from '@ohos.base'; 103 104let formId: string = '12400633174999288'; 105formHost.releaseForm(formId, (error: Base.BusinessError) => { 106 if (error.code) { 107 console.error(`formHost releaseForm, error: ${JSON.stringify(error)}`); 108 } else { 109 console.log('formHost releaseForm success'); 110 } 111}); 112``` 113 114## releaseForm 115 116releaseForm(formId: string, isReleaseCache: boolean, callback: AsyncCallback<void>): void 117 118释放指定的卡片。调用此方法后，应用程序将无法使用该卡片，卡片管理器服务保留有关该卡片的存储信息，可以选择是否保留缓存信息。使用callback异步回调。 119 120**需要权限：** ohos.permission.REQUIRE_FORM 121 122**系统能力：** SystemCapability.Ability.Form 123 124**参数：** 125 126| 参数名 | 类型 | 必填 | 说明 | 127| -------------- | ------ | ---- | ----------- | 128| formId | string | 是 | 卡片标识。 | 129| isReleaseCache | boolean | 是 | 是否释放缓存。 | 130| callback | AsyncCallback<void> | 是 | 回调函数。当释放指定的卡片成功，error为undefined；否则为错误对象。 | 131 132**示例：** 133 134```ts 135import Base from '@ohos.base'; 136 137let formId: string = '12400633174999288'; 138formHost.releaseForm(formId, true, (error: Base.BusinessError) => { 139 if (error.code) { 140 console.error(`formHost releaseForm, error: ${JSON.stringify(error)}`); 141 } else { 142 console.log('formHost releaseForm success'); 143 } 144}); 145``` 146 147## releaseForm 148 149releaseForm(formId: string, isReleaseCache?: boolean): Promise<void> 150 151释放指定的卡片。调用此方法后，应用程序将无法使用该卡片，卡片管理器服务保留有关该卡片的存储信息，可以选择是否保留缓存信息。使用Promise异步回调。 152 153**需要权限：** ohos.permission.REQUIRE_FORM 154 155**系统能力：** SystemCapability.Ability.Form 156 157**参数：** 158 159| 参数名 | 类型 | 必填 | 说明 | 160| -------------- | ------ | ---- | ----------- | 161| formId | string | 是 | 卡片标识。 | 162| isReleaseCache | boolean | 否 | 是否释放缓存，默认为false。 | 163 164**返回值：** 165 166| 类型 | 说明 | 167| -------- | -------- | 168| Promise<void> | 无返回结果的Promise对象。 | 169 170**示例：** 171 172```ts 173import Base from '@ohos.base'; 174 175let formId: string = '12400633174999288'; 176formHost.releaseForm(formId, true).then(() => { 177 console.log('formHost releaseForm success'); 178}).catch((error: Base.BusinessError) => { 179 console.error(`formHost releaseForm, error: ${JSON.stringify(error)}`); 180}); 181``` 182 183## requestForm 184 185requestForm(formId: string, callback: AsyncCallback<void>): void 186 187请求卡片更新。使用callback异步回调。 188 189**需要权限：** ohos.permission.REQUIRE_FORM 190 191**系统能力：** SystemCapability.Ability.Form 192 193**参数：** 194 195| 参数名 | 类型 | 必填 | 说明 | 196| ------ | ------ | ---- | ------- | 197| formId | string | 是 | 卡片标识。 | 198| callback | AsyncCallback<void> | 是 | 回调函数。当请求卡片更新成功，error为undefined；否则为错误对象。 | 199 200**示例：** 201 202```ts 203import Base from '@ohos.base'; 204 205let formId: string = '12400633174999288'; 206formHost.requestForm(formId, (error: Base.BusinessError) => { 207 if (error.code) { 208 console.error(`formHost requestForm, error: ${JSON.stringify(error)}`); 209 } 210}); 211``` 212 213## requestForm 214 215requestForm(formId: string): Promise<void> 216 217请求卡片更新。使用Promise异步回调。 218 219**需要权限：** ohos.permission.REQUIRE_FORM 220 221**系统能力：** SystemCapability.Ability.Form 222 223**参数：** 224 225| 参数名 | 类型 | 必填 | 说明 | 226| ------ | ------ | ---- | ------- | 227| formId | string | 是 | 卡片标识。 | 228 229**返回值：** 230 231| 类型 | 说明 | 232| -------- | -------- | 233| Promise<void> | 无返回结果的Promise对象。 | 234 235**示例：** 236 237```ts 238import Base from '@ohos.base'; 239 240let formId: string = '12400633174999288'; 241formHost.requestForm(formId).then(() => { 242 console.log('formHost requestForm success'); 243}).catch((error: Base.BusinessError) => { 244 console.error(`formHost requestForm, error: ${JSON.stringify(error)}`); 245}); 246``` 247 248## castTempForm 249 250castTempForm(formId: string, callback: AsyncCallback<void>): void 251 252将指定的临时卡片转换为普通卡片。使用callback异步回调。 253 254**需要权限：** ohos.permission.REQUIRE_FORM 255 256**系统能力：** SystemCapability.Ability.Form 257 258**参数：** 259 260| 参数名 | 类型 | 必填 | 说明 | 261| ------ | ------ | ---- | ------- | 262| formId | string | 是 | 卡片标识。 | 263| callback | AsyncCallback<void> | 是 | 回调函数。当将指定的临时卡片转换为普通卡片成功，error为undefined，否则为错误对象。 | 264 265**示例：** 266 267```ts 268import Base from '@ohos.base'; 269 270let formId: string = '12400633174999288'; 271formHost.castTempForm(formId, (error: Base.BusinessError) => { 272 if (error.code) { 273 console.error(`formHost castTempForm, error: ${JSON.stringify(error)}`); 274 } 275}); 276``` 277 278## castTempForm 279 280castTempForm(formId: string): Promise<void> 281 282将指定的临时卡片转换为普通卡片。使用Promise异步回调。 283 284**需要权限：** ohos.permission.REQUIRE_FORM 285 286**系统能力：** SystemCapability.Ability.Form 287 288**参数：** 289 290| 参数名 | 类型 | 必填 | 说明 | 291| ------ | ------ | ---- | ------- | 292| formId | string | 是 | 卡片标识。 | 293 294**返回值：** 295 296| 类型 | 说明 | 297| -------- | -------- | 298| Promise<void> | 无返回结果的Promise对象。| 299 300**示例：** 301 302```ts 303import Base from '@ohos.base'; 304 305let formId: string = '12400633174999288'; 306formHost.castTempForm(formId).then(() => { 307 console.log('formHost castTempForm success'); 308}).catch((error: Base.BusinessError) => { 309 console.error(`formHost castTempForm, error: ${JSON.stringify(error)}`); 310}); 311``` 312 313## notifyVisibleForms 314 315notifyVisibleForms(formIds: Array<string>, callback: AsyncCallback<void>): void 316 317向卡片框架发送通知以使指定的卡片可见。该方法调用成功后，会调用onVisibilityChange通知卡片提供方。使用callback异步回调。 318 319**需要权限：** ohos.permission.REQUIRE_FORM 320 321**系统能力：** SystemCapability.Ability.Form 322 323**参数：** 324 325| 参数名 | 类型 | 必填 | 说明 | 326| ------ | ------ | ---- | ------- | 327| formIds | Array<string> | 是 | 卡片标识列表。 | 328| callback | AsyncCallback<void> | 是 | 回调函数。当向卡片框架发送通知以使指定的卡片可见成功，error为undefined，否则为错误对象。 | 329 330**示例：** 331 332```ts 333import Base from '@ohos.base'; 334 335let formId: string[] = ['12400633174999288']; 336formHost.notifyVisibleForms(formId, (error: Base.BusinessError) => { 337 if (error.code) { 338 console.error(`formHost notifyVisibleForms, error: ${JSON.stringify(error)}`); 339 } 340}); 341``` 342 343## notifyVisibleForms 344 345notifyVisibleForms(formIds: Array<string>): Promise<void> 346 347向卡片框架发送通知以使指定的卡片可见。该方法调用成功后，会调用onVisibilityChange通知卡片提供方。使用Promise异步回调。 348 349**需要权限：** ohos.permission.REQUIRE_FORM 350 351**系统能力：** SystemCapability.Ability.Form 352 353**参数：** 354 355| 参数名 | 类型 | 必填 | 说明 | 356| ------ | ------ | ---- | ------- | 357| formIds | Array<string> | 是 | 卡片标识列表。 | 358 359**返回值：** 360 361| 类型 | 说明 | 362| -------- | -------- | 363| Promise<void> | 无返回结果的Promise对象。 | 364 365**示例：** 366 367```ts 368import Base from '@ohos.base'; 369 370let formId: string[] = ['12400633174999288']; 371formHost.notifyVisibleForms(formId).then(() => { 372 console.log('formHost notifyVisibleForms success'); 373}).catch((error: Base.BusinessError) => { 374 console.error(`formHost notifyVisibleForms, error: ${JSON.stringify(error)}`); 375}); 376``` 377 378## notifyInvisibleForms 379 380notifyInvisibleForms(formIds: Array<string>, callback: AsyncCallback<void>): void 381 382向卡片框架发送通知以使指定的卡片不可见。该方法调用成功后，会调用onVisibilityChange通知卡片提供方。使用callback异步回调。 383 384**需要权限：** ohos.permission.REQUIRE_FORM 385 386**系统能力：** SystemCapability.Ability.Form 387 388**参数：** 389 390| 参数名 | 类型 | 必填 | 说明 | 391| ------ | ------ | ---- | ------- | 392| formIds | Array<string> | 是 | 卡片标识列表。| 393| callback | AsyncCallback<void> | 是 | 回调函数。当向卡片框架发送通知以使指定的卡片不可见成功，error为undefined，否则为错误对象。 | 394 395**示例：** 396 397```ts 398import Base from '@ohos.base'; 399 400let formId: string[] = ['12400633174999288']; 401formHost.notifyInvisibleForms(formId, (error: Base.BusinessError) => { 402 if (error.code) { 403 console.error(`formHost notifyInvisibleForms, error: ${JSON.stringify(error)}`); 404 } 405}); 406``` 407 408## notifyInvisibleForms 409 410notifyInvisibleForms(formIds: Array<string>): Promise<void> 411 412向卡片框架发送通知以使指定的卡片不可见。该方法调用成功后，会调用onVisibilityChange通知卡片提供方。使用Promise异步回调。 413 414**需要权限：** ohos.permission.REQUIRE_FORM 415 416**系统能力：** SystemCapability.Ability.Form 417 418**参数：** 419 420| 参数名 | 类型 | 必填 | 说明 | 421| ------ | ------ | ---- | ------- | 422| formIds | Array<string> | 是 | 卡片标识列表。 | 423 424**返回值：** 425 426| 类型 | 说明 | 427| -------- | -------- | 428| Promise<void> | 无返回结果的Promise对象。| 429 430**示例：** 431 432```ts 433import Base from '@ohos.base'; 434 435let formId: string[] = ['12400633174999288']; 436formHost.notifyInvisibleForms(formId).then(() => { 437 console.log('formHost notifyInvisibleForms success'); 438}).catch((error: Base.BusinessError) => { 439 console.error(`formHost notifyInvisibleForms, error: ${JSON.stringify(error)}`); 440}); 441``` 442 443## enableFormsUpdate 444 445enableFormsUpdate(formIds: Array<string>, callback: AsyncCallback<void>): void 446 447向卡片框架发送通知以使指定的卡片可以更新。该方法调用成功后，卡片刷新状态设置为使能，卡片可以接收来自卡片提供方的更新。使用callback异步回调。 448 449**需要权限：** ohos.permission.REQUIRE_FORM 450 451**系统能力：** SystemCapability.Ability.Form 452 453**参数：** 454 455| 参数名 | 类型 | 必填 | 说明 | 456| ------ | ------ | ---- | ------- | 457| formIds | Array<string> | 是 | 卡片标识列表。 | 458| callback | AsyncCallback<void> | 是 | 回调函数。当向卡片框架发送通知以使指定的卡片可以更新成功，error为undefined，否则为错误对象。 | 459 460**示例：** 461 462```ts 463import Base from '@ohos.base'; 464 465let formId: string[] = ['12400633174999288']; 466formHost.enableFormsUpdate(formId, (error: Base.BusinessError) => { 467 if (error.code) { 468 console.error(`formHost enableFormsUpdate, error: ${JSON.stringify(error)}`); 469 } 470}); 471``` 472 473## enableFormsUpdate 474 475enableFormsUpdate(formIds: Array<string>): Promise<void> 476 477向卡片框架发送通知以使指定的卡片可以更新。该方法调用成功后，卡片刷新状态设置为使能，卡片可以接收来自卡片提供方的更新。使用Promise异步回调。 478 479**需要权限：** ohos.permission.REQUIRE_FORM 480 481**系统能力：** SystemCapability.Ability.Form 482 483**参数：** 484 485| 参数名 | 类型 | 必填 | 说明 | 486| ------ | ------ | ---- | ------- | 487| formIds | Array<string> | 是 | 卡片标识列表。 | 488 489**返回值：** 490 491| 类型 | 说明 | 492| -------- | -------- | 493| Promise<void> | 无返回结果的Promise对象。 | 494 495**示例：** 496 497```ts 498import Base from '@ohos.base'; 499 500let formId: string[] = ['12400633174999288']; 501formHost.enableFormsUpdate(formId).then(() => { 502 console.log('formHost enableFormsUpdate success'); 503}).catch((error: Base.BusinessError) => { 504 console.error(`formHost enableFormsUpdate, error: ${JSON.stringify(error)}`); 505}); 506``` 507 508## disableFormsUpdate 509 510disableFormsUpdate(formIds: Array<string>, callback: AsyncCallback<void>): void 511 512向卡片框架发送通知以使指定的卡片不可以更新。该方法调用成功后，卡片刷新状态设置为去使能，卡片不可以接收来自卡片提供方的更新。使用callback异步回调。 513 514**需要权限：** ohos.permission.REQUIRE_FORM 515 516**系统能力：** SystemCapability.Ability.Form 517 518**参数：** 519 520| 参数名 | 类型 | 必填 | 说明 | 521| ------ | ------ | ---- | ------- | 522| formIds | Array<string> | 是 | 卡片标识列表。 | 523| callback | AsyncCallback<void> | 是 | 回调函数。当向卡片框架发送通知以使指定的卡片不可以更新成功，error为undefined，否则为错误对象。 | 524 525**示例：** 526 527```ts 528import Base from '@ohos.base'; 529 530let formId: string[] = ['12400633174999288']; 531formHost.disableFormsUpdate(formId, (error: Base.BusinessError) => { 532 if (error.code) { 533 console.error(`formHost disableFormsUpdate, error: ${JSON.stringify(error)}`); 534 } 535}); 536``` 537 538## disableFormsUpdate 539 540disableFormsUpdate(formIds: Array<string>): Promise<void> 541 542向卡片框架发送通知以使指定的卡片不可以更新。该方法调用成功后，卡片刷新状态设置为去使能，卡片不可以接收来自卡片提供方的更新。使用Promise异步回调。 543 544**需要权限：** ohos.permission.REQUIRE_FORM 545 546**系统能力：** SystemCapability.Ability.Form 547 548**参数：** 549 550| 参数名 | 类型 | 必填 | 说明 | 551| ------ | ------ | ---- | ------- | 552| formIds | Array<string> | 是 | 卡片标识列表。 | 553 554**返回值：** 555 556| 类型 | 说明 | 557| -------- | -------- | 558| Promise<void> | 无返回结果的Promise对象。 | 559 560**示例：** 561 562```ts 563import Base from '@ohos.base'; 564 565let formId: string[] = ['12400633174999288']; 566formHost.disableFormsUpdate(formId).then(() => { 567 console.log('formHost disableFormsUpdate success'); 568}).catch((error: Base.BusinessError) => { 569 console.error(`formHost disableFormsUpdate, error: ${JSON.stringify(error)}`); 570}); 571``` 572 573## isSystemReady 574 575isSystemReady(callback: AsyncCallback<void>): void 576 577检查系统是否准备好。使用callback异步回调。 578 579**系统能力：** SystemCapability.Ability.Form 580 581**参数：** 582 583| 参数名 | 类型 | 必填 | 说明 | 584| ------ | ------ | ---- | ------- | 585| callback | AsyncCallback<void> | 是 | 回调函数。当检查系统是否准备好成功，error为undefined，否则为错误对象。 | 586 587**示例：** 588 589```ts 590import Base from '@ohos.base'; 591 592let formId: string = '12400633174999288'; 593formHost.isSystemReady((error: Base.BusinessError) => { 594 if (error.code) { 595 console.error(`formHost isSystemReady, error: ${JSON.stringify(error)}`); 596 } 597}); 598``` 599 600## isSystemReady 601 602isSystemReady(): Promise<void> 603 604检查系统是否准备好。使用Promise异步回调。 605 606**系统能力：** SystemCapability.Ability.Form 607 608**返回值：** 609 610| 类型 | 说明 | 611| -------- | -------- | 612| Promise<void> | 无返回结果的Promise对象。 | 613 614**示例：** 615 616```ts 617import Base from '@ohos.base'; 618 619let formId: string = '12400633174999288'; 620formHost.isSystemReady().then(() => { 621 console.log('formHost isSystemReady success'); 622}).catch((error: Base.BusinessError) => { 623 console.error(`formHost isSystemReady, error: ${JSON.stringify(error)}`); 624}); 625``` 626 627## getAllFormsInfo 628 629getAllFormsInfo(callback: AsyncCallback<Array<formInfo.FormInfo>>): void 630 631获取设备上所有应用提供的卡片信息。使用callback异步回调。 632 633**需要权限：** ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 634 635**系统能力：** SystemCapability.Ability.Form 636 637**参数：** 638 639| 参数名 | 类型 | 必填 | 说明 | 640| ------ | ------ | ---- | ------- | 641| callback | AsyncCallback<Array<[formInfo.FormInfo](js-apis-app-form-formInfo.md)>> | 是 | 回调函数。当获取设备上所有应用提供的卡片信息成功，error为undefined，data为查询到的卡片信息；否则为错误对象。 | 642 643**示例：** 644 645```ts 646import formInfo from '@ohos.app.form.formInfo'; 647import Base from '@ohos.base'; 648 649formHost.getAllFormsInfo((error: Base.BusinessError, data: formInfo.FormInfo[]) => { 650 if (error.code) { 651 console.error(`formHost getAllFormsInfo, error: ${JSON.stringify(error)}`); 652 } else { 653 console.log(`formHost getAllFormsInfo, data: ${JSON.stringify(data)}`); 654 } 655}); 656``` 657 658## getAllFormsInfo 659 660getAllFormsInfo(): Promise<Array<formInfo.FormInfo>> 661 662获取设备上所有应用提供的卡片信息。使用Promise异步回调。 663 664**需要权限：** ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 665 666**系统能力：** SystemCapability.Ability.Form 667 668**返回值：** 669 670| 类型 | 说明 | 671| :------------ | :---------------------------------- | 672| Promise<Array<[formInfo.FormInfo](js-apis-app-form-formInfo.md)>> | Promise对象。返回查询到的卡片信息。 | 673 674**示例：** 675 676 ```ts 677 import formInfo from '@ohos.app.form.formInfo'; 678 import Base from '@ohos.base'; 679 680 formHost.getAllFormsInfo().then((data: formInfo.FormInfo[]) => { 681 console.log(`formHost getAllFormsInfo data: ${JSON.stringify(data)}`); 682 }).catch((error: Base.BusinessError) => { 683 console.error(`formHost getAllFormsInfo, error: ${JSON.stringify(error)}`); 684 }); 685 ``` 686 687## getFormsInfo 688 689getFormsInfo(bundleName: string, callback: AsyncCallback<Array<formInfo.FormInfo>>): void 690 691获取设备上指定应用程序提供的卡片信息。使用callback异步回调。 692 693**需要权限：** ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 694 695**系统能力：** SystemCapability.Ability.Form 696 697**参数：** 698 699| 参数名 | 类型 | 必填 | 说明 | 700| ------ | ------ | ---- | ------- | 701| bundleName | string | 是 | 要查询的应用Bundle名称。 | 702| callback | AsyncCallback<Array<[formInfo.FormInfo](js-apis-app-form-formInfo.md)>> | 是 | 回调函数。当获取设备上指定应用程序提供的卡片信息成功，error为undefined，data为查询到的卡片信息；否则为错误对象。 | 703 704**示例：** 705 706```ts 707import formInfo from '@ohos.app.form.formInfo'; 708import Base from '@ohos.base'; 709 710formHost.getFormsInfo('com.example.ohos.formjsdemo', (error: Base.BusinessError, data: formInfo.FormInfo[]) => { 711 if (error.code) { 712 console.error(`formHost getFormsInfo, error: ${JSON.stringify(error)}`); 713 } else { 714 console.log(`formHost getFormsInfo, data: ${JSON.stringify(data)}`); 715 } 716}); 717``` 718 719## getFormsInfo 720 721getFormsInfo(bundleName: string, moduleName: string, callback: AsyncCallback<Array<formInfo.FormInfo>>): void 722 723获取设备上指定应用程序提供的卡片信息。使用callback异步回调。 724 725**需要权限：** ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 726 727**系统能力：** SystemCapability.Ability.Form 728 729**参数：** 730 731| 参数名 | 类型 | 必填 | 说明 | 732| ------ | ------ | ---- | ------- | 733| bundleName | string | 是 | 要查询的应用程序Bundle名称。 | 734| moduleName | string | 是 | 要查询的模块名称。 | 735| callback | AsyncCallback<Array<[formInfo.FormInfo](js-apis-app-form-formInfo.md)>> | 是 | 回调函数。当获取设备上指定应用程序提供的卡片信息成功，error为undefined，data为查询到的卡片信息；否则为错误对象。 | 736 737**示例：** 738 739```ts 740import formInfo from '@ohos.app.form.formInfo'; 741import Base from '@ohos.base'; 742 743formHost.getFormsInfo('com.example.ohos.formjsdemo', 'entry', (error: Base.BusinessError, data: formInfo.FormInfo[]) => { 744 if (error.code) { 745 console.error(`formHost getFormsInfo, error: ${JSON.stringify(error)}`); 746 } else { 747 console.log(`formHost getFormsInfo, data: ${JSON.stringify(data)}`); 748 } 749}); 750``` 751 752## getFormsInfo 753 754getFormsInfo(bundleName: string, moduleName?: string): Promise<Array<formInfo.FormInfo>> 755 756获取设备上指定应用程序提供的卡片信息。使用Promise异步回调。 757 758**需要权限：** ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 759 760**系统能力：** SystemCapability.Ability.Form 761 762**参数：** 763 764| 参数名 | 类型 | 必填 | 说明 | 765| ------ | ------ | ---- | ------- | 766| bundleName | string | 是 | 要查询的应用程序Bundle名称。 | 767| moduleName | string | 否 | 要查询的模块名称。 | 768 769**返回值：** 770 771| 类型 | 说明 | 772| :------------ | :---------------------------------- | 773| Promise<Array<[formInfo.FormInfo](js-apis-app-form-formInfo.md)>> | Promise对象。返回查询到的卡片信息。 | 774 775**示例：** 776 777 ```ts 778 import formInfo from '@ohos.app.form.formInfo'; 779 import Base from '@ohos.base'; 780 781 formHost.getFormsInfo('com.example.ohos.formjsdemo', 'entry').then((data: formInfo.FormInfo[]) => { 782 console.log(`formHost getFormsInfo, data: ${JSON.stringify(data)}`); 783 }).catch((error: Base.BusinessError) => { 784 console.error(`formHost getFormsInfo, error: ${JSON.stringify(error)}`); 785 }); 786 ``` 787 788## deleteInvalidForms 789 790deleteInvalidForms(formIds: Array<string>, callback: AsyncCallback<number>): void 791 792根据列表删除应用程序的无效卡片。使用callback异步回调。 793 794**需要权限：** ohos.permission.REQUIRE_FORM 795 796**系统能力：** SystemCapability.Ability.Form 797 798**参数：** 799 800| 参数名 | 类型 | 必填 | 说明 | 801| ------ | ------ | ---- | ------- | 802| formIds | Array<string> | 是 | 有效卡片标识列表。 | 803| callback | AsyncCallback<number> | 是 | 回调函数。当根据列表删除应用程序的无效卡片成功，error为undefined，data为删除的卡片个数；否则为错误对象。 | 804 805**示例：** 806 807```ts 808import Base from '@ohos.base'; 809 810let formIds: string[] = new Array('12400633174999288', '12400633174999289'); 811formHost.deleteInvalidForms(formIds, (error: Base.BusinessError, data: number) => { 812 if (error.code) { 813 console.error(`formHost deleteInvalidForms, error: ${JSON.stringify(error)}`); 814 } else { 815 console.log(`formHost deleteInvalidForms, data: ${JSON.stringify(data)}`); 816 } 817}); 818``` 819 820## deleteInvalidForms 821 822deleteInvalidForms(formIds: Array<string>): Promise<number> 823 824根据列表删除应用程序的无效卡片。使用Promise异步回调。 825 826**需要权限：** ohos.permission.REQUIRE_FORM 827 828**系统能力：** SystemCapability.Ability.Form 829 830**参数：** 831 832| 参数名 | 类型 | 必填 | 说明 | 833| ------ | ------ | ---- | ------- | 834| formIds | Array<string> | 是 | 有效卡片标识列表。 | 835 836**返回值：** 837 838| 类型 | 说明 | 839| :------------ | :---------------------------------- | 840| Promise<number> | Promise对象。返回删除的卡片个数。 | 841 842**示例：** 843 844```ts 845import Base from '@ohos.base'; 846 847let formIds: string[] = new Array('12400633174999288', '12400633174999289'); 848formHost.deleteInvalidForms(formIds).then((data: number) => { 849 console.log(`formHost deleteInvalidForms, data: ${JSON.stringify(data)}`); 850}).catch((error: Base.BusinessError) => { 851 console.error(`formHost deleteInvalidForms, error: ${JSON.stringify(error)}`); 852}); 853``` 854 855## acquireFormState 856 857acquireFormState(want: Want, callback: AsyncCallback<formInfo.FormStateInfo>): void 858 859获取卡片状态。使用callback异步回调。 860 861**需要权限：** ohos.permission.REQUIRE_FORM 和 ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 862 863**系统能力：** SystemCapability.Ability.Form 864 865**参数：** 866 867| 参数名 | 类型 | 必填 | 说明 | 868| ------ | ------ | ---- | ------- | 869| want | [Want](../apis-ability-kit/js-apis-application-want.md) | 是 | 查询卡片状态时携带的want信息。需要包含bundle名、ability名、module名、卡片名、卡片规格等。 | 870| callback | AsyncCallback<[formInfo.FormStateInfo](js-apis-application-formInfo.md#formstateinfo)> | 是 | 回调函数。当获取卡片状态成功，error为undefined，data为获取到的卡片状态；否则为错误对象。 | 871 872**示例：** 873 874```ts 875import Want from '@ohos.app.ability.Want'; 876import formInfo from '@ohos.app.form.formInfo'; 877import Base from '@ohos.base'; 878 879let want: Want = { 880 'deviceId': '', 881 'bundleName': 'ohos.samples.FormApplication', 882 'abilityName': 'FormAbility', 883 'parameters': { 884 'ohos.extra.param.key.module_name': 'entry', 885 'ohos.extra.param.key.form_name': 'widget', 886 'ohos.extra.param.key.form_dimension': 2 887 } 888}; 889formHost.acquireFormState(want, (error:Base.BusinessError, data: formInfo.FormStateInfo) => { 890 if (error.code) { 891 console.error(`formHost acquireFormState, error: ${JSON.stringify(error)}`); 892 } else { 893 console.log(`formHost acquireFormState, data: ${JSON.stringify(data)}`); 894 } 895}); 896``` 897 898## acquireFormState 899 900acquireFormState(want: Want): Promise<formInfo.FormStateInfo> 901 902获取卡片状态。使用Promise异步回调。 903 904**需要权限：** ohos.permission.REQUIRE_FORM 和 ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 905 906**系统能力：** SystemCapability.Ability.Form 907 908**参数：** 909 910| 参数名 | 类型 | 必填 | 说明 | 911| ------ | ------ | ---- | ------- | 912| want | [Want](../apis-ability-kit/js-apis-application-want.md) | 是 | 查询卡片状态时携带的want信息。 | 913 914**返回值：** 915 916| 类型 | 说明 | 917| :------------ | :---------------------------------- | 918| Promise<[formInfo.FormStateInfo](js-apis-application-formInfo.md#formstateinfo)> | Promise对象。返回卡片状态。 | 919 920**示例：** 921 922```ts 923import Want from '@ohos.app.ability.Want'; 924import formInfo from '@ohos.app.form.formInfo'; 925import Base from '@ohos.base'; 926 927let want: Want = { 928 'deviceId': '', 929 'bundleName': 'ohos.samples.FormApplication', 930 'abilityName': 'FormAbility', 931 'parameters': { 932 'ohos.extra.param.key.module_name': 'entry', 933 'ohos.extra.param.key.form_name': 'widget', 934 'ohos.extra.param.key.form_dimension': 2 935 } 936}; 937formHost.acquireFormState(want).then((data: formInfo.FormStateInfo) => { 938 console.log(`formHost acquireFormState, data: ${JSON.stringify(data)}`); 939}).catch((error: Base.BusinessError) => { 940 console.error(`formHost acquireFormState, error: ${JSON.stringify(error)}`); 941}); 942``` 943 944## on('formUninstall') 945 946on(type: 'formUninstall', callback: Callback<string>): void 947 948订阅卡片卸载事件。使用callback异步回调。 949 950> **说明：** 951> 952> 卡片卸载与卡片移除不同。当应用卸载时，对应的卡片会自动卸载。 953 954**系统能力：** SystemCapability.Ability.Form 955 956**参数：** 957 958| 参数名 | 类型 | 必填 | 说明 | 959| ------ | ------ | ---- | ------- | 960| type | string | 是 | 填写'formUninstall'，表示卡片卸载事件。 | 961| callback | Callback<string> | 是 | 回调函数，返回卡片标识。 | 962 963**示例：** 964 965```ts 966import Base from '@ohos.base'; 967 968formHost.on('formUninstall', (formId: string) => { 969 console.log(`formHost on formUninstall, formId: ${formId}`); 970}); 971``` 972 973## off('formUninstall') 974 975off(type: 'formUninstall', callback?: Callback<string>): void 976 977取消订阅卡片卸载事件。使用callback异步回调。 978 979> **说明：** 980> 981> 卡片卸载与卡片移除不同。当应用卸载时，对应的卡片会自动卸载。 982 983**系统能力：** SystemCapability.Ability.Form 984 985**参数：** 986 987| 参数名 | 类型 | 必填 | 说明 | 988| ------ | ------ | ---- | ------- | 989| type | string | 是 | 填写'formUninstall'，表示卡片卸载事件。 | 990| callback | Callback<string> | 否 | 回调函数，返回卡片标识。缺省时，表示注销所有已注册事件回调。<br> 需与对应on('formUninstall')的callback一致。| 991 992**示例：** 993 994```ts 995import Base from '@ohos.base'; 996 997formHost.off('formUninstall', (formId: string) => { 998 console.log(`formHost on formUninstall, formId: ${formId}`); 999}); 1000``` 1001 1002## notifyFormsVisible 1003 1004notifyFormsVisible(formIds: Array<string>, isVisible: boolean, callback: AsyncCallback<void>): void 1005 1006通知卡片是否可见。使用callback异步回调。 1007 1008**需要权限：** ohos.permission.REQUIRE_FORM 1009 1010**系统能力：** SystemCapability.Ability.Form 1011 1012**参数：** 1013 1014| 参数名 | 类型 | 必填 | 说明 | 1015| ------ | ------ | ---- | ------- | 1016| formIds | Array<string> | 是 | 卡片标识列表。 | 1017| isVisible | boolean | 是 | 是否可见。 | 1018| callback | AsyncCallback<void> | 是 | 回调函数。当通知卡片是否可见成功，error为undefined，否则为错误对象。 | 1019 1020**示例：** 1021 1022```ts 1023import Base from '@ohos.base'; 1024 1025let formIds: string[]= new Array('12400633174999288', '12400633174999289'); 1026formHost.notifyFormsVisible(formIds, true, (error: Base.BusinessError) => { 1027 if (error.code) { 1028 console.error(`formHost notifyFormsVisible, error: ${JSON.stringify(error)}`); 1029 } 1030}); 1031``` 1032 1033## notifyFormsVisible 1034 1035notifyFormsVisible(formIds: Array<string>, isVisible: boolean): Promise<void> 1036 1037通知卡片是否可见。使用Promise异步回调。 1038 1039**需要权限：** ohos.permission.REQUIRE_FORM 1040 1041**系统能力：** SystemCapability.Ability.Form 1042 1043**参数：** 1044 1045| 参数名 | 类型 | 必填 | 说明 | 1046| ------ | ------ | ---- | ------- | 1047| formIds | Array<string> | 是 | 卡片标识列表。 | 1048| isVisible | boolean | 是 | 是否可见。 | 1049 1050**返回值：** 1051 1052| 类型 | 说明 | 1053| -------- | -------- | 1054| Promise<void> | 无返回结果的Promise对象。 | 1055 1056**示例：** 1057 1058```ts 1059import Base from '@ohos.base'; 1060 1061let formIds: string[] = new Array('12400633174999288', '12400633174999289'); 1062formHost.notifyFormsVisible(formIds, true).then(() => { 1063 console.log('formHost notifyFormsVisible success'); 1064}).catch((error: Base.BusinessError) => { 1065 console.error(`formHost notifyFormsVisible, error: ${JSON.stringify(error)}`); 1066}); 1067``` 1068 1069## notifyFormsEnableUpdate 1070 1071notifyFormsEnableUpdate(formIds: Array<string>, isEnableUpdate: boolean, callback: AsyncCallback<void>): void 1072 1073通知卡片是否启用更新状态。使用callback异步回调。 1074 1075**需要权限：** ohos.permission.REQUIRE_FORM 1076 1077**系统能力：** SystemCapability.Ability.Form 1078 1079**参数：** 1080 1081| 参数名 | 类型 | 必填 | 说明 | 1082| ------ | ------ | ---- | ------- | 1083| formIds | Array<string> | 是 | 卡片标识列表。 | 1084| isEnableUpdate | boolean | 是 | 是否使能更新。 | 1085| callback | AsyncCallback<void> | 是 | 回调函数。当通知卡片是否启用更新状态成功，error为undefined，否则为错误对象。 | 1086 1087**示例：** 1088 1089```ts 1090import Base from '@ohos.base'; 1091 1092let formIds: string[] = new Array('12400633174999288', '12400633174999289'); 1093formHost.notifyFormsEnableUpdate(formIds, true, (error: Base.BusinessError) => { 1094 if (error.code) { 1095 console.error(`formHost notifyFormsEnableUpdate, error: ${JSON.stringify(error)}`); 1096 } 1097}); 1098``` 1099 1100## notifyFormsEnableUpdate 1101 1102notifyFormsEnableUpdate(formIds: Array<string>, isEnableUpdate: boolean): Promise<void> 1103 1104通知卡片是否启用更新状态。使用Promise异步回调。 1105 1106**需要权限：** ohos.permission.REQUIRE_FORM 1107 1108**系统能力：** SystemCapability.Ability.Form 1109 1110**参数：** 1111 1112 | 参数名 | 类型 | 必填 | 说明 | 1113 | ------ | ------ | ---- | ------- | 1114 | formIds | Array<string> | 是 | 卡片标识列表。 | 1115 | isEnableUpdate | boolean | 是 | 是否使能更新。 | 1116 1117**返回值：** 1118 1119 | 类型 | 说明 | 1120 | -------- | -------- | 1121 | Promise<void> | 无返回结果的Promise对象。 | 1122 1123**示例：** 1124 1125```ts 1126import Base from '@ohos.base'; 1127 1128let formIds: string[] = new Array('12400633174999288', '12400633174999289'); 1129formHost.notifyFormsEnableUpdate(formIds, true).then(() => { 1130 console.log('formHost notifyFormsEnableUpdate success'); 1131}).catch((error: Base.BusinessError) => { 1132 console.error(`formHost notifyFormsEnableUpdate, error: ${JSON.stringify(error)}`); 1133}); 1134``` 1135