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