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