1# @ohos.application.formHost (FormHost) 2 3The **FormHost** module provides APIs related to the widget host, which is an application that displays the widget content and controls the position where the widget is displayed. You can use the APIs to delete, release, and update widgets installed by the same user, and obtain widget information and status. 4 5> **NOTE** 6> 7> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. 8> This module is deprecated since API version 9. You are advised to use [formHost](js-apis-app-form-formHost.md) instead. 9> The APIs provided by this module are system APIs. 10 11## Modules to Import 12 13```ts 14import formHost from '@ohos.application.formHost'; 15``` 16 17## deleteForm 18 19deleteForm(formId: string, callback: AsyncCallback<void>): void 20 21Deletes a widget. After this API is called, the application can no longer use the widget, and the Widget Manager will not retain the widget information. This API uses an asynchronous callback to return the result. 22 23**Required permissions**: ohos.permission.REQUIRE_FORM 24 25**System capability**: SystemCapability.Ability.Form 26 27**Parameters** 28 29| Name| Type | Mandatory| Description | 30| ------ | ------ | ---- | ------- | 31| formId | string | Yes | Widget ID.| 32| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the widget is deleted, **err** is undefined; otherwise, **err** is an error object.| 33 34**Example** 35 36```ts 37let formId = '12400633174999288'; 38formHost.deleteForm(formId, (error, data) => { 39 if (error.code) { 40 console.log('formHost deleteForm, error:' + JSON.stringify(error)); 41 } 42}); 43``` 44 45## deleteForm 46 47deleteForm(formId: string): Promise<void> 48 49Deletes a widget. After this API is called, the application can no longer use the widget, and the Widget Manager will not retain the widget information. This API uses a promise to return the result. 50 51**Required permissions**: ohos.permission.REQUIRE_FORM 52 53**System capability**: SystemCapability.Ability.Form 54 55**Parameters** 56 57| Name| Type | Mandatory| Description | 58| ------ | ------ | ---- | ------- | 59| formId | string | Yes | Widget ID.| 60 61**Return value** 62 63| Type| Description| 64| -------- | -------- | 65| Promise<void> | Promise that returns no value.| 66 67**Example** 68 69```ts 70let formId = '12400633174999288'; 71formHost.deleteForm(formId).then(() => { 72 console.log('formHost deleteForm success'); 73}).catch((error) => { 74 console.log('formHost deleteForm, error:' + JSON.stringify(error)); 75}); 76``` 77 78## releaseForm 79 80releaseForm(formId: string, callback: AsyncCallback<void>): void 81 82Releases a widget. After this API is called, the application can no longer use the widget, but the Widget Manager still retains the widget cache and storage information. This API uses an asynchronous callback to return the result. 83 84**Required permissions**: ohos.permission.REQUIRE_FORM 85 86**System capability**: SystemCapability.Ability.Form 87 88**Parameters** 89 90| Name| Type | Mandatory| Description | 91| ------ | ------ | ---- | ------- | 92| formId | string | Yes | Widget ID.| 93| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the widget is released, **err** is undefined; otherwise, **err** is an error object.| 94 95**Example** 96 97```ts 98let formId = '12400633174999288'; 99formHost.releaseForm(formId, (error, data) => { 100 if (error.code) { 101 console.log('formHost releaseForm, error:' + JSON.stringify(error)); 102 } 103}); 104``` 105 106## releaseForm 107 108releaseForm(formId: string, isReleaseCache: boolean, callback: AsyncCallback<void>): void 109 110Releases a widget. After this API is called, the application can no longer use the widget, but the Widget Manager retains the storage information about the widget and retains or releases the cache information based on the setting. This API uses an asynchronous callback to return the result. 111 112**Required permissions**: ohos.permission.REQUIRE_FORM 113 114**System capability**: SystemCapability.Ability.Form 115 116**Parameters** 117 118| Name | Type | Mandatory| Description | 119| -------------- | ------ | ---- | ----------- | 120| formId | string | Yes | Widget ID. | 121| isReleaseCache | boolean | Yes | Whether to release the cache.| 122| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the widget is released, **err** is undefined; otherwise, **err** is an error object.| 123 124**Example** 125 126```ts 127let formId = '12400633174999288'; 128formHost.releaseForm(formId, true, (error, data) => { 129 if (error.code) { 130 console.log('formHost releaseForm, error:' + JSON.stringify(error)); 131 } 132}); 133``` 134 135## releaseForm 136 137releaseForm(formId: string, isReleaseCache?: boolean): Promise<void> 138 139Releases a widget. After this API is called, the application can no longer use the widget, but the Widget Manager retains the storage information about the widget and retains or releases the cache information based on the setting. This API uses a promise to return the result. 140 141**Required permissions**: ohos.permission.REQUIRE_FORM 142 143**System capability**: SystemCapability.Ability.Form 144 145**Parameters** 146 147| Name | Type | Mandatory| Description | 148| -------------- | ------ | ---- | ----------- | 149| formId | string | Yes | Widget ID. | 150| isReleaseCache | boolean | No | Whether to release the cache.| 151 152**Return value** 153 154| Type| Description| 155| -------- | -------- | 156| Promise<void> | Promise that returns no value.| 157 158**Example** 159 160```ts 161let formId = '12400633174999288'; 162formHost.releaseForm(formId, true).then(() => { 163 console.log('formHost releaseForm success'); 164}).catch((error) => { 165 console.log('formHost releaseForm, error:' + JSON.stringify(error)); 166}); 167``` 168 169## requestForm 170 171requestForm(formId: string, callback: AsyncCallback<void>): void 172 173Requests a widget update. This API uses an asynchronous callback to return the result. 174 175**Required permissions**: ohos.permission.REQUIRE_FORM 176 177**System capability**: SystemCapability.Ability.Form 178 179**Parameters** 180 181| Name| Type | Mandatory| Description | 182| ------ | ------ | ---- | ------- | 183| formId | string | Yes | Widget ID.| 184| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the widget is updated, **err** is undefined; otherwise, **err** is an error object.| 185 186**Example** 187 188```ts 189let formId = '12400633174999288'; 190formHost.requestForm(formId, (error, data) => { 191 if (error.code) { 192 console.log('formHost requestForm, error:' + JSON.stringify(error)); 193 } 194}); 195``` 196 197## requestForm 198 199requestForm(formId: string): Promise<void> 200 201Requests a widget update. This API uses a promise to return the result. 202 203**Required permissions**: ohos.permission.REQUIRE_FORM 204 205**System capability**: SystemCapability.Ability.Form 206 207**Parameters** 208 209| Name| Type | Mandatory| Description | 210| ------ | ------ | ---- | ------- | 211| formId | string | Yes | Widget ID.| 212 213**Return value** 214 215| Type| Description| 216| -------- | -------- | 217| Promise<void> | Promise that returns no value.| 218 219**Example** 220 221```ts 222let formId = '12400633174999288'; 223formHost.requestForm(formId).then(() => { 224 console.log('formHost requestForm success'); 225}).catch((error) => { 226 console.log('formHost requestForm, error:' + JSON.stringify(error)); 227}); 228``` 229 230## castTempForm 231 232castTempForm(formId: string, callback: AsyncCallback<void>): void 233 234Converts a temporary widget to a normal one. This API uses an asynchronous callback to return the result. 235 236**Required permissions**: ohos.permission.REQUIRE_FORM 237 238**System capability**: SystemCapability.Ability.Form 239 240**Parameters** 241 242| Name| Type | Mandatory| Description | 243| ------ | ------ | ---- | ------- | 244| formId | string | Yes | Widget ID.| 245| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the widget is converted to a normal one, **error** is undefined; otherwise, **error** is an error object.| 246 247**Example** 248 249```ts 250let formId = '12400633174999288'; 251formHost.castTempForm(formId, (error, data) => { 252 if (error.code) { 253 console.log('formHost castTempForm, error:' + JSON.stringify(error)); 254 } 255}); 256``` 257 258## castTempForm 259 260castTempForm(formId: string): Promise<void> 261 262Converts a temporary widget to a normal one. This API uses a promise to return the result. 263 264**Required permissions**: ohos.permission.REQUIRE_FORM 265 266**System capability**: SystemCapability.Ability.Form 267 268**Parameters** 269 270| Name| Type | Mandatory| Description | 271| ------ | ------ | ---- | ------- | 272| formId | string | Yes | Widget ID.| 273 274**Return value** 275 276| Type| Description| 277| -------- | -------- | 278| Promise<void> | Promise that returns no value.| 279 280**Example** 281 282```ts 283let formId = '12400633174999288'; 284formHost.castTempForm(formId).then(() => { 285 console.log('formHost castTempForm success'); 286}).catch((error) => { 287 console.log('formHost castTempForm, error:' + JSON.stringify(error)); 288}); 289``` 290 291## notifyVisibleForms 292 293notifyVisibleForms(formIds: Array<string>, callback: AsyncCallback<void>): void 294 295Instructs the widget framework to make a widget visible. After this API is called, **onVisibilityChange** is invoked to notify the widget provider. This API uses an asynchronous callback to return the result. 296 297**Required permissions**: ohos.permission.REQUIRE_FORM 298 299**System capability**: SystemCapability.Ability.Form 300 301**Parameters** 302 303| Name| Type | Mandatory| Description | 304| ------ | ------ | ---- | ------- | 305| formIds | Array<string> | Yes | List of widget IDs. | 306| callback | AsyncCallback<void> | Yes| Callback used to return the result. If a notification is sent to the widget framework to make the widget visible, **error** is undefined; otherwise, **error** is an error object.| 307 308**Example** 309 310```ts 311let formId = ['12400633174999288']; 312formHost.notifyVisibleForms(formId, (error, data) => { 313 if (error.code) { 314 console.log('formHost notifyVisibleForms, error:' + JSON.stringify(error)); 315 } 316}); 317``` 318 319## notifyVisibleForms 320 321notifyVisibleForms(formIds: Array<string>): Promise<void> 322 323Instructs the widget framework to make a widget visible. After this API is called, **onVisibilityChange** is invoked to notify the widget provider. This API uses a promise to return the result. 324 325**Required permissions**: ohos.permission.REQUIRE_FORM 326 327**System capability**: SystemCapability.Ability.Form 328 329**Parameters** 330 331| Name| Type | Mandatory| Description | 332| ------ | ------ | ---- | ------- | 333| formIds | Array<string> | Yes | List of widget IDs.| 334 335**Return value** 336 337| Type| Description| 338| -------- | -------- | 339| Promise<void> | Promise that returns no value.| 340 341**Example** 342 343```ts 344let formId = ['12400633174999288']; 345formHost.notifyVisibleForms(formId).then(() => { 346 console.log('formHost notifyVisibleForms success'); 347}).catch((error) => { 348 console.log('formHost notifyVisibleForms, error:' + JSON.stringify(error)); 349}); 350``` 351 352## notifyInvisibleForms 353 354notifyInvisibleForms(formIds: Array<string>, callback: AsyncCallback<void>): void 355 356Instructs the widget framework to make a widget invisible. After this API is called, **onVisibilityChange** is invoked to notify the widget provider. This API uses an asynchronous callback to return the result. 357 358**Required permissions**: ohos.permission.REQUIRE_FORM 359 360**System capability**: SystemCapability.Ability.Form 361 362**Parameters** 363 364| Name| Type | Mandatory| Description | 365| ------ | ------ | ---- | ------- | 366| formIds | Array<string> | Yes | List of widget IDs.| 367| callback | AsyncCallback<void> | Yes| Callback used to return the result. If a notification is sent to the widget framework to make the widget invisible, **error** is undefined; otherwise, **error** is an error object.| 368 369**Example** 370 371```ts 372let formId = ['12400633174999288']; 373formHost.notifyInvisibleForms(formId, (error, data) => { 374 if (error.code) { 375 console.log('formHost notifyInvisibleForms, error:' + JSON.stringify(error)); 376 } 377}); 378``` 379 380## notifyInvisibleForms 381 382notifyInvisibleForms(formIds: Array<string>): Promise<void> 383 384Instructs the widget framework to make a widget invisible. After this API is called, **onVisibilityChange** is invoked to notify the widget provider. This API uses a promise to return the result. 385 386**Required permissions**: ohos.permission.REQUIRE_FORM 387 388**System capability**: SystemCapability.Ability.Form 389 390**Parameters** 391 392| Name| Type | Mandatory| Description | 393| ------ | ------ | ---- | ------- | 394| formIds | Array<string> | Yes | List of widget IDs.| 395 396**Return value** 397 398| Type| Description| 399| -------- | -------- | 400| Promise<void> | Promise that returns no value.| 401 402**Example** 403 404```ts 405let formId = ['12400633174999288']; 406formHost.notifyInvisibleForms(formId).then(() => { 407 console.log('formHost notifyInvisibleForms success'); 408}).catch((error) => { 409 console.log('formHost notifyInvisibleForms, error:' + JSON.stringify(error)); 410}); 411``` 412 413## enableFormsUpdate 414 415enableFormsUpdate(formIds: Array<string>, callback: AsyncCallback<void>): void 416 417Instructs the widget framework to make a widget updatable. After this API is called, the widget is in the enabled state and can receive updates from the widget provider. This API uses an asynchronous callback to return the result. 418 419**Required permissions**: ohos.permission.REQUIRE_FORM 420 421**System capability**: SystemCapability.Ability.Form 422 423**Parameters** 424 425| Name| Type | Mandatory| Description | 426| ------ | ------ | ---- | ------- | 427| formIds | Array<string> | Yes | List of widget IDs. | 428| callback | AsyncCallback<void> | Yes| Callback used to return the result. If a notification is sent to the widget framework to make the widget updatable, **error** is undefined; otherwise, **error** is an error object.| 429 430**Example** 431 432```ts 433let formId = ['12400633174999288']; 434formHost.enableFormsUpdate(formId, (error, data) => { 435 if (error.code) { 436 console.log('formHost enableFormsUpdate, error:' + JSON.stringify(error)); 437 } 438}); 439``` 440 441## enableFormsUpdate 442 443enableFormsUpdate(formIds: Array<string>): Promise<void> 444 445Instructs the widget framework to make a widget updatable. After this API is called, the widget is in the enabled state and can receive updates from the widget provider. This API uses a promise to return the result. 446 447**Required permissions**: ohos.permission.REQUIRE_FORM 448 449**System capability**: SystemCapability.Ability.Form 450 451**Parameters** 452 453| Name| Type | Mandatory| Description | 454| ------ | ------ | ---- | ------- | 455| formIds | Array<string> | Yes | List of widget IDs.| 456 457**Return value** 458 459| Type| Description| 460| -------- | -------- | 461| Promise<void> | Promise that returns no value.| 462 463**Example** 464 465```ts 466let formId = ['12400633174999288']; 467formHost.enableFormsUpdate(formId).then(() => { 468 console.log('formHost enableFormsUpdate success'); 469}).catch((error) => { 470 console.log('formHost enableFormsUpdate, error:' + JSON.stringify(error)); 471}); 472``` 473 474## disableFormsUpdate 475 476disableFormsUpdate(formIds: Array<string>, callback: AsyncCallback<void>): void 477 478Instructs the widget framework to make a widget not updatable. After this API is called, the widget cannot receive updates from the widget provider. This API uses an asynchronous callback to return the result. 479 480**Required permissions**: ohos.permission.REQUIRE_FORM 481 482**System capability**: SystemCapability.Ability.Form 483 484**Parameters** 485 486| Name| Type | Mandatory| Description | 487| ------ | ------ | ---- | ------- | 488| formIds | Array<string> | Yes | List of widget IDs. | 489| callback | AsyncCallback<void> | Yes| Callback used to return the result. If a notification is sent to the widget framework to make the widget not updatable, **error** is undefined; otherwise, **error** is an error object.| 490 491**Example** 492 493```ts 494let formId = ['12400633174999288']; 495formHost.disableFormsUpdate(formId, (error, data) => { 496 if (error.code) { 497 console.log('formHost disableFormsUpdate, error:' + JSON.stringify(error)); 498 } 499}); 500``` 501 502## disableFormsUpdate 503 504disableFormsUpdate(formIds: Array<string>): Promise<void> 505 506Instructs the widget framework to make a widget not updatable. After this API is called, the widget cannot receive updates from the widget provider. This API uses a promise to return the result. 507 508**Required permissions**: ohos.permission.REQUIRE_FORM 509 510**System capability**: SystemCapability.Ability.Form 511 512**Parameters** 513 514| Name| Type | Mandatory| Description | 515| ------ | ------ | ---- | ------- | 516| formIds | Array<string> | Yes | List of widget IDs.| 517 518**Return value** 519 520| Type| Description| 521| -------- | -------- | 522| Promise<void> | Promise that returns no value.| 523 524**Example** 525 526```ts 527let formId = ['12400633174999288']; 528formHost.disableFormsUpdate(formId).then(() => { 529 console.log('formHost disableFormsUpdate success'); 530}).catch((error) => { 531 console.log('formHost disableFormsUpdate, error:' + JSON.stringify(error)); 532}); 533``` 534 535## isSystemReady 536 537isSystemReady(callback: AsyncCallback<void>): void 538 539Checks whether the system is ready. This API uses an asynchronous callback to return the result. 540 541**System capability**: SystemCapability.Ability.Form 542 543**Parameters** 544 545| Name| Type | Mandatory| Description | 546| ------ | ------ | ---- | ------- | 547| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the check is successful, **error** is undefined; otherwise, **error** is an error object.| 548 549**Example** 550 551```ts 552let formId = '12400633174999288'; 553formHost.isSystemReady((error, data) => { 554 if (error.code) { 555 console.log('formHost isSystemReady, error:' + JSON.stringify(error)); 556 } 557}); 558``` 559 560## isSystemReady 561 562isSystemReady(): Promise<void> 563 564Checks whether the system is ready. This API uses a promise to return the result. 565 566**System capability**: SystemCapability.Ability.Form 567 568**Return value** 569 570| Type| Description| 571| -------- | -------- | 572| Promise<void> | Promise that returns no value.| 573 574**Example** 575 576```ts 577let formId = '12400633174999288'; 578formHost.isSystemReady().then(() => { 579 console.log('formHost isSystemReady success'); 580}).catch((error) => { 581 console.log('formHost isSystemReady, error:' + JSON.stringify(error)); 582}); 583``` 584 585## getAllFormsInfo 586 587getAllFormsInfo(callback: AsyncCallback<Array<formInfo.FormInfo>>): void 588 589Obtains the widget information provided by all applications on the device. This API uses an asynchronous callback to return the result. 590 591**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 592 593**System capability**: SystemCapability.Ability.Form 594 595**Parameters** 596 597| Name| Type | Mandatory| Description | 598| ------ | ------ | ---- | ------- | 599| callback | AsyncCallback<Array<[FormInfo](js-apis-application-formInfo.md)>> | Yes| Callback used to return the result. If the widget information is obtained, **error** is undefined and **data** is the information obtained; otherwise, **error** is an error object.| 600 601**Example** 602 603```ts 604formHost.getAllFormsInfo((error, data) => { 605 if (error.code) { 606 console.log('formHost getAllFormsInfo, error:' + JSON.stringify(error)); 607 } else { 608 console.log('formHost getAllFormsInfo, data:' + JSON.stringify(data)); 609 } 610}); 611``` 612 613## getAllFormsInfo 614 615getAllFormsInfo(): Promise<Array<formInfo.FormInfo>> 616 617Obtains the widget information provided by all applications on the device. This API uses a promise to return the result. 618 619**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 620 621**System capability**: SystemCapability.Ability.Form 622 623**Return value** 624 625| Type | Description | 626| :------------ | :---------------------------------- | 627| Promise<Array<[FormInfo](js-apis-application-formInfo.md)>> | Promise used to return the information obtained.| 628 629**Example** 630 631 ```ts 632 formHost.getAllFormsInfo().then((data) => { 633 console.log('formHost getAllFormsInfo data:' + JSON.stringify(data)); 634 }).catch((error) => { 635 console.log('formHost getAllFormsInfo, error:' + JSON.stringify(error)); 636 }); 637 ``` 638 639## getFormsInfo 640 641getFormsInfo(bundleName: string, callback: AsyncCallback<Array<formInfo.FormInfo>>): void 642 643Obtains the widget information provided by a given application on the device. This API uses an asynchronous callback to return the result. 644 645**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 646 647**System capability**: SystemCapability.Ability.Form 648 649**Parameters** 650 651| Name| Type | Mandatory| Description | 652| ------ | ------ | ---- | ------- | 653| bundleName | string | Yes| Bundle name of the application.| 654| callback | AsyncCallback<Array<[FormInfo](js-apis-application-formInfo.md)>> | Yes| Callback used to return the result. If the widget information is obtained, **error** is undefined and **data** is the information obtained; otherwise, **error** is an error object.| 655 656**Example** 657 658```ts 659formHost.getFormsInfo('com.example.ohos.formjsdemo', (error, data) => { 660 if (error.code) { 661 console.log('formHost getFormsInfo, error:' + JSON.stringify(error)); 662 } else { 663 console.log('formHost getFormsInfo, data:' + JSON.stringify(data)); 664 } 665}); 666``` 667 668## getFormsInfo 669 670getFormsInfo(bundleName: string, moduleName: string, callback: AsyncCallback<Array<formInfo.FormInfo>>): void 671 672Obtains the widget information provided by a given application on the device. This API uses an asynchronous callback to return the result. 673 674**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 675 676**System capability**: SystemCapability.Ability.Form 677 678**Parameters** 679 680| Name| Type | Mandatory| Description | 681| ------ | ------ | ---- | ------- | 682| bundleName | string | Yes| Bundle name of the application.| 683| moduleName | string | Yes| Module name.| 684| callback | AsyncCallback<Array<[FormInfo](js-apis-application-formInfo.md)>> | Yes| Callback used to return the result. If the widget information is obtained, **error** is undefined and **data** is the information obtained; otherwise, **error** is an error object.| 685 686**Example** 687 688```ts 689formHost.getFormsInfo('com.example.ohos.formjsdemo', 'entry', (error, data) => { 690 if (error.code) { 691 console.log('formHost getFormsInfo, error:' + JSON.stringify(error)); 692 } else { 693 console.log('formHost getFormsInfo, data:' + JSON.stringify(data)); 694 } 695}); 696``` 697 698## getFormsInfo 699 700getFormsInfo(bundleName: string, moduleName?: string): Promise<Array<formInfo.FormInfo>> 701 702Obtains the widget information provided by a given application on the device. This API uses a promise to return the result. 703 704**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 705 706**System capability**: SystemCapability.Ability.Form 707 708**Parameters** 709 710| Name| Type | Mandatory| Description | 711| ------ | ------ | ---- | ------- | 712| bundleName | string | Yes| Bundle name of the application.| 713| moduleName | string | No| Module name.| 714 715**Return value** 716 717| Type | Description | 718| :------------ | :---------------------------------- | 719| Promise<Array<[FormInfo](js-apis-application-formInfo.md)>> | Promise used to return the information obtained.| 720 721**Example** 722 723 ```ts 724 formHost.getFormsInfo('com.example.ohos.formjsdemo', 'entry').then((data) => { 725 console.log('formHost getFormsInfo, data:' + JSON.stringify(data)); 726 }).catch((error) => { 727 console.log('formHost getFormsInfo, error:' + JSON.stringify(error)); 728 }); 729 ``` 730 731## deleteInvalidForms 732 733deleteInvalidForms(formIds: Array<string>, callback: AsyncCallback<number>): void 734 735Deletes invalid widgets from the list. This API uses an asynchronous callback to return the result. 736 737**Required permissions**: ohos.permission.REQUIRE_FORM 738 739**System capability**: SystemCapability.Ability.Form 740 741**Parameters** 742 743| Name| Type | Mandatory| Description | 744| ------ | ------ | ---- | ------- | 745| formIds | Array<string> | Yes | List of valid widget IDs.| 746| callback | AsyncCallback<number> | Yes| Callback used to return the result. If the invalid widgets are deleted, **error** is undefined and **data** is the number of widgets deleted; otherwise, **error** is an error object.| 747 748**Example** 749 750```ts 751let formIds = new Array('12400633174999288', '12400633174999289'); 752formHost.deleteInvalidForms(formIds, (error, data) => { 753 if (error.code) { 754 console.log('formHost deleteInvalidForms, error:' + JSON.stringify(error)); 755 } else { 756 console.log('formHost deleteInvalidForms, data:' + JSON.stringify(data)); 757 } 758}); 759``` 760 761## deleteInvalidForms 762 763deleteInvalidForms(formIds: Array<string>): Promise<number> 764 765Deletes invalid widgets from the list. This API uses a promise to return the result. 766 767**Required permissions**: ohos.permission.REQUIRE_FORM 768 769**System capability**: SystemCapability.Ability.Form 770 771**Parameters** 772 773| Name| Type | Mandatory| Description | 774| ------ | ------ | ---- | ------- | 775| formIds | Array<string> | Yes | List of valid widget IDs.| 776 777**Return value** 778 779| Type | Description | 780| :------------ | :---------------------------------- | 781| Promise<number> | Promise used to return the number of widgets deleted.| 782 783**Example** 784 785```ts 786let formIds = new Array('12400633174999288', '12400633174999289'); 787formHost.deleteInvalidForms(formIds).then((data) => { 788 console.log('formHost deleteInvalidForms, data:' + JSON.stringify(data)); 789}).catch((error) => { 790 console.log('formHost deleteInvalidForms, error:' + JSON.stringify(error)); 791}); 792``` 793 794## acquireFormState 795 796acquireFormState(want: Want, callback: AsyncCallback<formInfo.FormStateInfo>): void 797 798Obtains the widget state. This API uses an asynchronous callback to return the result. 799 800**Required permissions**: ohos.permission.REQUIRE_FORM and ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 801 802**System capability**: SystemCapability.Ability.Form 803 804**Parameters** 805 806| Name| Type | Mandatory| Description | 807| ------ | ------ | ---- | ------- | 808| want | [Want](js-apis-application-want.md) | Yes | **Want** information carried to query the widget state. The information must contain the bundle name, ability name, module name, widget name, and widget dimensions.| 809| callback | AsyncCallback<[FormStateInfo](js-apis-application-formInfo.md#formstateinfo)> | Yes| Callback used to return the result. If the widget state is obtained, **error** is undefined and **data** is the widget state obtained; otherwise, **error** is an error object.| 810 811**Example** 812 813```ts 814let want = { 815 'deviceId': '', 816 'bundleName': 'ohos.samples.FormApplication', 817 'abilityName': 'FormAbility', 818 'parameters': { 819 'ohos.extra.param.key.module_name': 'entry', 820 'ohos.extra.param.key.form_name': 'widget', 821 'ohos.extra.param.key.form_dimension': 2 822 } 823}; 824formHost.acquireFormState(want, (error, data) => { 825 if (error.code) { 826 console.log('formHost acquireFormState, error:' + JSON.stringify(error)); 827 } else { 828 console.log('formHost acquireFormState, data:' + JSON.stringify(data)); 829 } 830}); 831``` 832 833## acquireFormState 834 835acquireFormState(want: Want): Promise<formInfo.FormStateInfo> 836 837Obtains the widget state. This API uses a promise to return the result. 838 839**Required permissions**: ohos.permission.REQUIRE_FORM and ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 840 841**System capability**: SystemCapability.Ability.Form 842 843**Parameters** 844 845| Name| Type | Mandatory| Description | 846| ------ | ------ | ---- | ------- | 847| want | [Want](js-apis-application-want.md) | Yes | **Want** information carried to query the widget state.| 848 849**Return value** 850 851| Type | Description | 852| :------------ | :---------------------------------- | 853| Promise<[FormStateInfo](js-apis-application-formInfo.md#formstateinfo)> | Promise used to return the widget state obtained.| 854 855**Example** 856 857```ts 858let want = { 859 'deviceId': '', 860 'bundleName': 'ohos.samples.FormApplication', 861 'abilityName': 'FormAbility', 862 'parameters': { 863 'ohos.extra.param.key.module_name': 'entry', 864 'ohos.extra.param.key.form_name': 'widget', 865 'ohos.extra.param.key.form_dimension': 2 866 } 867}; 868formHost.acquireFormState(want).then((data) => { 869 console.log('formHost acquireFormState, data:' + JSON.stringify(data)); 870}).catch((error) => { 871 console.log('formHost acquireFormState, error:' + JSON.stringify(error)); 872}); 873``` 874 875## on('formUninstall') 876 877on(type: 'formUninstall', callback: Callback<string>): void 878 879Subscribes to widget uninstall events. This API uses an asynchronous callback to return the result. 880 881**System capability**: SystemCapability.Ability.Form 882 883**Parameters** 884 885| Name| Type | Mandatory| Description | 886| ------ | ------ | ---- | ------- | 887| type | string | Yes | Event type. The value **'formUninstall'** indicates a widget uninstallation event.| 888| callback | Callback<string> | Yes| Callback used to return the widget ID.| 889 890**Example** 891 892```ts 893let callback = function(formId) { 894 console.log('formHost on formUninstall, formId:' + formId); 895} 896formHost.on('formUninstall', callback); 897``` 898 899## off('formUninstall') 900 901off(type: 'formUninstall', callback?: Callback<string>): void 902 903Unsubscribes from widget uninstall events. This API uses an asynchronous callback to return the result. 904 905**System capability**: SystemCapability.Ability.Form 906 907**Parameters** 908 909| Name| Type | Mandatory| Description | 910| ------ | ------ | ---- | ------- | 911| type | string | Yes | Event type. The value **'formUninstall'** indicates a widget uninstallation event.| 912| callback | Callback<string> | No| Callback used to return the widget ID. If it is left unspecified, it indicates the callback for all the events that have been subscribed.<br> The value must be the same as that in **on('formUninstall')**.| 913 914**Example** 915 916```ts 917let callback = function(formId) { 918 console.log('formHost on formUninstall, formId:' + formId); 919} 920formHost.off('formUninstall', callback); 921``` 922 923## notifyFormsVisible 924 925notifyFormsVisible(formIds: Array<string>, isVisible: boolean, callback: AsyncCallback<void>): void 926 927Instructs the widgets to make themselves visible. This API uses an asynchronous callback to return the result. 928 929**Required permissions**: ohos.permission.REQUIRE_FORM 930 931**System capability**: SystemCapability.Ability.Form 932 933**Parameters** 934 935| Name| Type | Mandatory| Description | 936| ------ | ------ | ---- | ------- | 937| formIds | Array<string> | Yes | List of widget IDs.| 938| isVisible | boolean | Yes | Whether to make the widgets visible.| 939| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the notification is sent, **error** is undefined; otherwise, **error** is an error object.| 940 941**Example** 942 943```ts 944let formIds = new Array('12400633174999288', '12400633174999289'); 945formHost.notifyFormsVisible(formIds, true, (error, data) => { 946 if (error.code) { 947 console.log('formHost notifyFormsVisible, error:' + JSON.stringify(error)); 948 } 949}); 950``` 951 952## notifyFormsVisible 953 954notifyFormsVisible(formIds: Array<string>, isVisible: boolean): Promise<void> 955 956Instructs the widgets to make themselves visible. This API uses a promise to return the result. 957 958**Required permissions**: ohos.permission.REQUIRE_FORM 959 960**System capability**: SystemCapability.Ability.Form 961 962**Parameters** 963 964| Name| Type | Mandatory| Description | 965| ------ | ------ | ---- | ------- | 966| formIds | Array<string> | Yes | List of widget IDs.| 967| isVisible | boolean | Yes | Whether to make the widgets visible.| 968 969**Return value** 970 971| Type| Description| 972| -------- | -------- | 973| Promise<void> | Promise that returns no value.| 974 975**Example** 976 977```ts 978let formIds = new Array('12400633174999288', '12400633174999289'); 979formHost.notifyFormsVisible(formIds, true).then(() => { 980 console.log('formHost notifyFormsVisible success'); 981}).catch((error) => { 982 console.log('formHost notifyFormsVisible, error:' + JSON.stringify(error)); 983}); 984``` 985 986## notifyFormsEnableUpdate 987 988notifyFormsEnableUpdate(formIds: Array<string>, isEnableUpdate: boolean, callback: AsyncCallback<void>): void 989 990Instructs the widgets to enable or disable updates. This API uses an asynchronous callback to return the result. 991 992**Required permissions**: ohos.permission.REQUIRE_FORM 993 994**System capability**: SystemCapability.Ability.Form 995 996**Parameters** 997 998| Name| Type | Mandatory| Description | 999| ------ | ------ | ---- | ------- | 1000| formIds | Array<string> | Yes | List of widget IDs.| 1001| isEnableUpdate | boolean | Yes | Whether to make the widgets updatable.| 1002| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the notification is sent, **error** is undefined; otherwise, **error** is an error object.| 1003 1004**Example** 1005 1006```ts 1007let formIds = new Array('12400633174999288', '12400633174999289'); 1008formHost.notifyFormsEnableUpdate(formIds, true, (error, data) => { 1009 if (error.code) { 1010 console.log('formHost notifyFormsEnableUpdate, error:' + JSON.stringify(error)); 1011 } 1012}); 1013``` 1014 1015## notifyFormsEnableUpdate 1016 1017notifyFormsEnableUpdate(formIds: Array<string>, isEnableUpdate: boolean): Promise<void> 1018 1019Instructs the widgets to enable or disable updates. This API uses a promise to return the result. 1020 1021**Required permissions**: ohos.permission.REQUIRE_FORM 1022 1023**System capability**: SystemCapability.Ability.Form 1024 1025**Parameters** 1026 1027 | Name| Type | Mandatory| Description | 1028 | ------ | ------ | ---- | ------- | 1029 | formIds | Array<string> | Yes | List of widget IDs.| 1030 | isEnableUpdate | boolean | Yes | Whether to make the widgets updatable.| 1031 1032**Return value** 1033 1034 | Type| Description| 1035 | -------- | -------- | 1036 | Promise<void> | Promise that returns no value.| 1037 1038**Example** 1039 1040```ts 1041let formIds = new Array('12400633174999288', '12400633174999289'); 1042formHost.notifyFormsEnableUpdate(formIds, true).then(() => { 1043 console.log('formHost notifyFormsEnableUpdate success'); 1044}).catch((error) => { 1045 console.log('formHost notifyFormsEnableUpdate, error:' + JSON.stringify(error)); 1046}); 1047``` 1048