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