1# @ohos.app.form.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 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. 8> The APIs provided by this module are system APIs. 9 10## Modules to Import 11 12```ts 13import formHost from '@ohos.app.form.formHost'; 14``` 15 16## deleteForm 17 18deleteForm(formId: string, callback: AsyncCallback<void>): void 19 20Deletes 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. 21 22**Required permissions**: ohos.permission.REQUIRE_FORM 23 24**System capability**: SystemCapability.Ability.Form 25 26**Parameters** 27 28| Name| Type | Mandatory| Description | 29| ------ | ------ | ---- | ------- | 30| formId | string | Yes | Widget ID.| 31| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the widget is deleted, **error** is undefined; otherwise, **error** is an error object.| 32 33**Error codes** 34 35| Error Code ID| Error Message| 36| -------- | -------- | 37| 201 | Permissions denied. | 38| 202 | The application is not a system application. | 39| 401 | If the input parameter is not valid parameter. | 40| 16500050 | An IPC connection error happened. | 41| 16500060 | A service connection error happened, please try again later. | 42| 16501000 | An internal functional error occurred. | 43| 16501001 | The ID of the form to be operated does not exist. | 44| 16501003 | The form can not be operated by the current application. | 45 46For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). 47 48**Example** 49 50```ts 51try { 52 var formId = '12400633174999288'; 53 formHost.deleteForm(formId, (error, data) => { 54 if (error) { 55 console.log('formHost deleteForm, error:' + JSON.stringify(error)); 56 } else { 57 console.log('formHost deleteForm success'); 58 } 59 }); 60} catch (error) { 61 console.log(`catch err->${JSON.stringify(error)}`); 62} 63 64``` 65 66## deleteForm 67 68deleteForm(formId: string): Promise<void> 69 70Deletes 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. 71 72**Required permissions**: ohos.permission.REQUIRE_FORM 73 74**System capability**: SystemCapability.Ability.Form 75 76**Parameters** 77 78| Name| Type | Mandatory| Description | 79| ------ | ------ | ---- | ------- | 80| formId | string | Yes | Widget ID.| 81 82**Return value** 83 84| Type| Description| 85| -------- | -------- | 86| Promise<void> | Promise that returns no value.| 87 88 89**Error codes** 90 91| Error Code ID| Error Message| 92| -------- | -------- | 93| 201 | Permissions denied. | 94| 202 | The application is not a system application. | 95| 401 | If the input parameter is not valid parameter. | 96| 16500050 | An IPC connection error happened. | 97| 16500060 | A service connection error happened, please try again later. | 98| 16501000 | An internal functional error occurred. | 99| 16501001 | The ID of the form to be operated does not exist. | 100| 16501003 | The form can not be operated by the current application. | 101 102For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). 103 104**Example** 105 106```ts 107try { 108 var formId = '12400633174999288'; 109 formHost.deleteForm(formId).then(() => { 110 console.log('formHost deleteForm success'); 111 }).catch((error) => { 112 console.log('formHost deleteForm, error:' + JSON.stringify(error)); 113 }); 114} catch(error) { 115 console.log(`catch err->${JSON.stringify(error)}`); 116} 117``` 118 119## releaseForm 120 121releaseForm(formId: string, callback: AsyncCallback<void>): void 122 123Releases 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. 124 125**Required permissions**: ohos.permission.REQUIRE_FORM 126 127**System capability**: SystemCapability.Ability.Form 128 129**Parameters** 130 131| Name| Type | Mandatory| Description | 132| ------ | ------ | ---- | ------- | 133| formId | string | Yes | Widget ID.| 134| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the widget is released, **error** is undefined; otherwise, **error** is an error object.| 135 136**Error codes** 137 138| Error Code ID| Error Message| 139| -------- | -------- | 140| 201 | Permissions denied. | 141| 202 | The application is not a system application. | 142| 401 | If the input parameter is not valid parameter. | 143| 16500050 | An IPC connection error happened. | 144| 16500060 | A service connection error happened, please try again later. | 145| 16501000 | An internal functional error occurred. | 146| 16501001 | The ID of the form to be operated does not exist. | 147| 16501003 | The form can not be operated by the current application. | 148 149For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). 150 151**Example** 152 153```ts 154try { 155 var formId = '12400633174999288'; 156 formHost.releaseForm(formId, (error, data) => { 157 if (error) { 158 console.log('formHost releaseForm, error:' + JSON.stringify(error)); 159 } 160 }); 161} catch(error) { 162 console.log(`catch err->${JSON.stringify(error)}`); 163} 164``` 165 166## releaseForm 167 168releaseForm(formId: string, isReleaseCache: boolean, callback: AsyncCallback<void>): void 169 170Releases 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. 171 172**Required permissions**: ohos.permission.REQUIRE_FORM 173 174**System capability**: SystemCapability.Ability.Form 175 176**Parameters** 177 178| Name | Type | Mandatory| Description | 179| -------------- | ------ | ---- | ----------- | 180| formId | string | Yes | Widget ID. | 181| isReleaseCache | boolean | Yes | Whether to release the cache.| 182| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the widget is released, **error** is undefined; otherwise, **error** is an error object.| 183 184**Error codes** 185 186| Error Code ID| Error Message| 187| -------- | -------- | 188| 201 | Permissions denied. | 189| 202 | The application is not a system application. | 190| 401 | If the input parameter is not valid parameter. | 191| 16500050 | An IPC connection error happened. | 192| 16500060 | A service connection error happened, please try again later. | 193| 16501000 | An internal functional error occurred. | 194| 16501001 | The ID of the form to be operated does not exist. | 195| 16501003 | The form can not be operated by the current application. | 196 197For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). 198 199**Example** 200 201```ts 202try { 203 var formId = '12400633174999288'; 204 formHost.releaseForm(formId, true, (error, data) => { 205 if (error) { 206 console.log('formHost releaseForm, error:' + JSON.stringify(error)); 207 } 208 }); 209} catch(error) { 210 console.log(`catch err->${JSON.stringify(error)}`); 211} 212``` 213 214## releaseForm 215 216releaseForm(formId: string, isReleaseCache?: boolean): Promise<void> 217 218Releases 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. 219 220**Required permissions**: ohos.permission.REQUIRE_FORM 221 222**System capability**: SystemCapability.Ability.Form 223 224**Parameters** 225 226| Name | Type | Mandatory| Description | 227| -------------- | ------ | ---- | ----------- | 228| formId | string | Yes | Widget ID. | 229| isReleaseCache | boolean | No | Whether to release the cache.| 230 231**Return value** 232 233| Type| Description| 234| -------- | -------- | 235| Promise<void> | Promise that returns no value.| 236 237**Error codes** 238 239| Error Code ID| Error Message| 240| -------- | -------- | 241| 201 | Permissions denied. | 242| 202 | The application is not a system application. | 243| 401 | If the input parameter is not valid parameter. | 244| 16500050 | An IPC connection error happened. | 245| 16500060 | A service connection error happened, please try again later. | 246| 16501000 | An internal functional error occurred. | 247| 16501001 | The ID of the form to be operated does not exist. | 248| 16501003 | The form can not be operated by the current application. | 249 250For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). 251 252**Example** 253 254```ts 255try { 256 var formId = '12400633174999288'; 257 formHost.releaseForm(formId, true).then(() => { 258 console.log('formHost releaseForm success'); 259 }).catch((error) => { 260 console.log('formHost releaseForm, error:' + JSON.stringify(error)); 261 }); 262} catch(error) { 263 console.log(`catch err->${JSON.stringify(error)}`); 264} 265``` 266 267## requestForm 268 269requestForm(formId: string, callback: AsyncCallback<void>): void 270 271Requests a widget update. This API uses an asynchronous callback to return the result. 272 273**Required permissions**: ohos.permission.REQUIRE_FORM 274 275**System capability**: SystemCapability.Ability.Form 276 277**Parameters** 278 279| Name| Type | Mandatory| Description | 280| ------ | ------ | ---- | ------- | 281| formId | string | Yes | Widget ID.| 282| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the widget is updated, **error** is undefined; otherwise, **error** is an error object.| 283 284**Error codes** 285 286| Error Code ID| Error Message| 287| -------- | -------- | 288| 201 | Permissions denied. | 289| 202 | The application is not a system application. | 290| 401 | If the input parameter is not valid parameter. | 291| 16500050 | An IPC connection error happened. | 292| 16500060 | A service connection error happened, please try again later. | 293| 16501000 | An internal functional error occurred. | 294| 16501001 | The ID of the form to be operated does not exist. | 295| 16501003 | The form can not be operated by the current application. | 296 297For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). 298 299**Example** 300 301```ts 302try { 303 var formId = '12400633174999288'; 304 formHost.requestForm(formId, (error, data) => { 305 if (error) { 306 console.log('formHost requestForm, error:' + JSON.stringify(error)); 307 } 308 }); 309} catch(error) { 310 console.log(`catch err->${JSON.stringify(error)}`); 311} 312``` 313 314## requestForm 315 316requestForm(formId: string): Promise<void> 317 318Requests a widget update. This API uses a promise to return the result. 319 320**Required permissions**: ohos.permission.REQUIRE_FORM 321 322**System capability**: SystemCapability.Ability.Form 323 324**Parameters** 325 326| Name| Type | Mandatory| Description | 327| ------ | ------ | ---- | ------- | 328| formId | string | Yes | Widget ID.| 329 330**Return value** 331 332| Type| Description| 333| -------- | -------- | 334| Promise<void> | Promise that returns no value.| 335 336**Error codes** 337 338| Error Code ID| Error Message| 339| -------- | -------- | 340| 201 | Permissions denied. | 341| 202 | The application is not a system application. | 342| 401 | If the input parameter is not valid parameter. | 343| 16500050 | An IPC connection error happened. | 344| 16500060 | A service connection error happened, please try again later. | 345| 16501000 | An internal functional error occurred. | 346| 16501001 | The ID of the form to be operated does not exist. | 347| 16501003 | The form can not be operated by the current application. | 348 349For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). 350 351**Example** 352 353```ts 354try { 355 var formId = '12400633174999288'; 356 formHost.requestForm(formId).then(() => { 357 console.log('formHost requestForm success'); 358 }).catch((error) => { 359 console.log('formHost requestForm, error:' + JSON.stringify(error)); 360 }); 361} catch(error) { 362 console.log(`catch err->${JSON.stringify(error)}`); 363} 364 365``` 366 367## castToNormalForm 368 369castToNormalForm(formId: string, callback: AsyncCallback<void>): void 370 371Converts a temporary widget to a normal one. This API uses an asynchronous callback to return the result. 372 373**Required permissions**: ohos.permission.REQUIRE_FORM 374 375**System capability**: SystemCapability.Ability.Form 376 377**Parameters** 378 379| Name| Type | Mandatory| Description | 380| ------ | ------ | ---- | ------- | 381| formId | string | Yes | Widget ID.| 382| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the widget is converted to a normal one, **err** is undefined; otherwise, **err** is an error object.| 383 384**Error codes** 385 386| Error Code ID| Error Message| 387| -------- | -------- | 388| 201 | Permissions denied. | 389| 202 | The application is not a system application. | 390| 401 | If the input parameter is not valid parameter. | 391| 16500050 | An IPC connection error happened. | 392| 16501000 | An internal functional error occurred. | 393| 16501001 | The ID of the form to be operated does not exist. | 394| 16501002 | The number of forms exceeds upper bound. | 395| 16501003 | The form can not be operated by the current application. | 396 397For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). 398 399**Example** 400 401```ts 402try { 403 var formId = '12400633174999288'; 404 formHost.castToNormalForm(formId, (error, data) => { 405 if (error) { 406 console.log('formHost castTempForm, error:' + JSON.stringify(error)); 407 } 408 }); 409} catch(error) { 410 console.log(`catch err->${JSON.stringify(error)}`); 411} 412``` 413 414## castToNormalForm 415 416castToNormalForm(formId: string): Promise<void> 417 418Converts a temporary widget to a normal one. This API uses a promise to return the result. 419 420**Required permissions**: ohos.permission.REQUIRE_FORM 421 422**System capability**: SystemCapability.Ability.Form 423 424**Parameters** 425 426| Name| Type | Mandatory| Description | 427| ------ | ------ | ---- | ------- | 428| formId | string | Yes | Widget ID.| 429 430**Return value** 431 432| Type| Description| 433| -------- | -------- | 434| Promise<void> | Promise that returns no value.| 435 436**Error codes** 437 438| Error Code ID| Error Message| 439| -------- | -------- | 440| 201 | Permissions denied. | 441| 202 | The application is not a system application. | 442| 401 | If the input parameter is not valid parameter. | 443| 16500050 | An IPC connection error happened. | 444| 16501000 | An internal functional error occurred. | 445| 16501001 | The ID of the form to be operated does not exist. | 446| 16501002 | The number of forms exceeds upper bound. | 447| 16501003 | The form can not be operated by the current application. | 448 449For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). 450 451**Example** 452 453```ts 454try { 455 var formId = '12400633174999288'; 456 formHost.castToNormalForm(formId).then(() => { 457 console.log('formHost castTempForm success'); 458 }).catch((error) => { 459 console.log('formHost castTempForm, error:' + JSON.stringify(error)); 460 }); 461} catch(error) { 462 console.log(`catch err->${JSON.stringify(error)}`); 463} 464``` 465 466## notifyVisibleForms 467 468notifyVisibleForms(formIds: Array<string>, callback: AsyncCallback<void>): void 469 470Instructs 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. 471 472**Required permissions**: ohos.permission.REQUIRE_FORM 473 474**System capability**: SystemCapability.Ability.Form 475 476**Parameters** 477 478| Name| Type | Mandatory| Description | 479| ------ | ------ | ---- | ------- | 480| formIds | Array<string> | Yes | List of widget IDs. | 481| callback | AsyncCallback<void> | Yes| Callback used to return the result. If a notification is sent to the widget framework to make the widget visible, **err** is undefined; otherwise, **err** is an error object.| 482 483**Error codes** 484 485| Error Code ID| Error Message| 486| -------- | -------- | 487| 201 | Permissions denied. | 488| 202 | The application is not a system application. | 489| 401 | If the input parameter is not valid parameter. | 490| 16500050 | An IPC connection error happened. | 491| 16500060 | A service connection error happened, please try again later. | 492| 16501000 | An internal functional error occurred. | 493 494For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). 495 496**Example** 497 498```ts 499try { 500 var formId = ['12400633174999288']; 501 formHost.notifyVisibleForms(formId, (error, data) => { 502 if (error) { 503 console.log('formHost notifyVisibleForms, error:' + JSON.stringify(error)); 504 } 505 }); 506} catch(error) { 507 console.log(`catch err->${JSON.stringify(error)}`); 508} 509``` 510 511## notifyVisibleForms 512 513notifyVisibleForms(formIds: Array<string>): Promise<void> 514 515Instructs 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. 516 517**Required permissions**: ohos.permission.REQUIRE_FORM 518 519**System capability**: SystemCapability.Ability.Form 520 521**Parameters** 522 523| Name| Type | Mandatory| Description | 524| ------ | ------ | ---- | ------- | 525| formIds | Array<string> | Yes | List of widget IDs.| 526 527**Return value** 528 529| Type| Description| 530| -------- | -------- | 531| Promise<void> | Promise that returns no value.| 532 533**Error codes** 534 535| Error Code ID| Error Message| 536| -------- | -------- | 537| 201 | Permissions denied. | 538| 202 | The application is not a system application. | 539| 401 | If the input parameter is not valid parameter. | 540| 16500050 | An IPC connection error happened. | 541| 16500060 | A service connection error happened, please try again later. | 542| 16501000 | An internal functional error occurred. | 543 544For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). 545 546**Example** 547 548```ts 549try { 550 var formId = ['12400633174999288']; 551 formHost.notifyVisibleForms(formId).then(() => { 552 console.log('formHost notifyVisibleForms success'); 553 }).catch((error) => { 554 console.log('formHost notifyVisibleForms, error:' + JSON.stringify(error)); 555 }); 556} catch(error) { 557 console.log(`catch err->${JSON.stringify(error)}`); 558} 559``` 560 561## notifyInvisibleForms 562 563notifyInvisibleForms(formIds: Array<string>, callback: AsyncCallback<void>): void 564 565Instructs 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. 566 567**Required permissions**: ohos.permission.REQUIRE_FORM 568 569**System capability**: SystemCapability.Ability.Form 570 571**Parameters** 572 573| Name| Type | Mandatory| Description | 574| ------ | ------ | ---- | ------- | 575| formIds | Array<string> | Yes | List of widget IDs.| 576| callback | AsyncCallback<void> | Yes| Callback used to return the result. If a notification is sent to the widget framework to make the widget invisible, **err** is undefined; otherwise, **err** is an error object.| 577 578**Error codes** 579 580| Error Code ID| Error Message| 581| -------- | -------- | 582| 201 | Permissions denied. | 583| 202 | The application is not a system application. | 584| 401 | If the input parameter is not valid parameter. | 585| 16500050 | An IPC connection error happened. | 586| 16500060 | A service connection error happened, please try again later. | 587| 16501000 | An internal functional error occurred. | 588 589For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). 590 591**Example** 592 593```ts 594try { 595 var formId = ['12400633174999288']; 596 formHost.notifyInvisibleForms(formId, (error, data) => { 597 if (error) { 598 console.log('formHost notifyInvisibleForms, error:' + JSON.stringify(error)); 599 } 600 }); 601} catch(error) { 602 console.log(`catch err->${JSON.stringify(error)}`); 603} 604``` 605 606## notifyInvisibleForms 607 608notifyInvisibleForms(formIds: Array<string>): Promise<void> 609 610Instructs 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. 611 612**Required permissions**: ohos.permission.REQUIRE_FORM 613 614**System capability**: SystemCapability.Ability.Form 615 616**Parameters** 617 618| Name| Type | Mandatory| Description | 619| ------ | ------ | ---- | ------- | 620| formIds | Array<string> | Yes | List of widget IDs.| 621 622**Return value** 623 624| Type| Description| 625| -------- | -------- | 626| Promise<void> | Promise that returns no value.| 627 628**Error codes** 629 630| Error Code ID| Error Message| 631| -------- | -------- | 632| 201 | Permissions denied. | 633| 202 | The application is not a system application. | 634| 401 | If the input parameter is not valid parameter. | 635| 16500050 | An IPC connection error happened. | 636| 16500060 | A service connection error happened, please try again later. | 637| 16501000 | An internal functional error occurred. | 638 639For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). 640 641**Example** 642 643```ts 644try { 645 var formId = ['12400633174999288']; 646 formHost.notifyInvisibleForms(formId).then(() => { 647 console.log('formHost notifyInvisibleForms success'); 648 }).catch((error) => { 649 console.log('formHost notifyInvisibleForms, error:' + JSON.stringify(error)); 650 }); 651} catch(error) { 652 console.log(`catch err->${JSON.stringify(error)}`); 653} 654``` 655 656## enableFormsUpdate 657 658enableFormsUpdate(formIds: Array<string>, callback: AsyncCallback<void>): void 659 660Instructs 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. 661 662**Required permissions**: ohos.permission.REQUIRE_FORM 663 664**System capability**: SystemCapability.Ability.Form 665 666**Parameters** 667 668| Name| Type | Mandatory| Description | 669| ------ | ------ | ---- | ------- | 670| formIds | Array<string> | Yes | List of widget IDs. | 671| callback | AsyncCallback<void> | Yes| Callback used to return the result. If a notification is sent to the widget framework to make the widget updatable, **err** is undefined; otherwise, **err** is an error object.| 672 673**Error codes** 674 675| Error Code ID| Error Message| 676| -------- | -------- | 677| 201 | Permissions denied. | 678| 202 | The application is not a system application. | 679| 401 | If the input parameter is not valid parameter. | 680| 16500050 | An IPC connection error happened. | 681| 16500060 | A service connection error happened, please try again later. | 682| 16501000 | An internal functional error occurred. | 683| 16501003 | The form can not be operated by the current application. | 684 685For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). 686 687**Example** 688 689```ts 690try { 691 var formId = ['12400633174999288']; 692 formHost.enableFormsUpdate(formId, (error, data) => { 693 if (error) { 694 console.log('formHost enableFormsUpdate, error:' + JSON.stringify(error)); 695 } 696 }); 697} catch(error) { 698 console.log(`catch err->${JSON.stringify(error)}`); 699} 700``` 701 702## enableFormsUpdate 703 704enableFormsUpdate(formIds: Array<string>): Promise<void> 705 706Instructs 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. 707 708**Required permissions**: ohos.permission.REQUIRE_FORM 709 710**System capability**: SystemCapability.Ability.Form 711 712**Parameters** 713 714| Name| Type | Mandatory| Description | 715| ------ | ------ | ---- | ------- | 716| formIds | Array<string> | Yes | List of widget IDs.| 717 718**Return value** 719 720| Type| Description| 721| -------- | -------- | 722| Promise<void> | Promise that returns no value.| 723 724**Error codes** 725 726| Error Code ID| Error Message| 727| -------- | -------- | 728| 201 | Permissions denied. | 729| 202 | The application is not a system application. | 730| 401 | If the input parameter is not valid parameter. | 731| 16500050 | An IPC connection error happened. | 732| 16500060 | A service connection error happened, please try again later. | 733| 16501000 | An internal functional error occurred. | 734| 16501003 | The form can not be operated by the current application. | 735 736For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). 737 738**Example** 739 740```ts 741try { 742 var formId = ['12400633174999288']; 743 formHost.enableFormsUpdate(formId).then(() => { 744 console.log('formHost enableFormsUpdate success'); 745 }).catch((error) => { 746 console.log('formHost enableFormsUpdate, error:' + JSON.stringify(error)); 747 }); 748} catch(error) { 749 console.log(`catch err->${JSON.stringify(error)}`); 750} 751``` 752 753## disableFormsUpdate 754 755disableFormsUpdate(formIds: Array<string>, callback: AsyncCallback<void>): void 756 757Instructs 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. 758 759**Required permissions**: ohos.permission.REQUIRE_FORM 760 761**System capability**: SystemCapability.Ability.Form 762 763**Parameters** 764 765| Name| Type | Mandatory| Description | 766| ------ | ------ | ---- | ------- | 767| formIds | Array<string> | Yes | List of widget IDs. | 768| 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, **err** is undefined; otherwise, **err** is an error object.| 769 770**Error codes** 771 772| Error Code ID| Error Message| 773| -------- | -------- | 774| 201 | Permissions denied. | 775| 202 | The application is not a system application. | 776| 401 | If the input parameter is not valid parameter. | 777| 16500050 | An IPC connection error happened. | 778| 16500060 | A service connection error happened, please try again later. | 779| 16501000 | An internal functional error occurred. | 780| 16501001 | The ID of the form to be operated does not exist. | 781| 16501003 | The form can not be operated by the current application. | 782 783For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). 784 785**Example** 786 787```ts 788try { 789 var formId = ['12400633174999288']; 790 formHost.disableFormsUpdate(formId, (error, data) => { 791 if (error) { 792 console.log('formHost disableFormsUpdate, error:' + JSON.stringify(error)); 793 } 794 }); 795} catch(error) { 796 console.log(`catch err->${JSON.stringify(error)}`); 797} 798``` 799 800## disableFormsUpdate 801 802disableFormsUpdate(formIds: Array<string>): Promise<void> 803 804Instructs 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. 805 806**Required permissions**: ohos.permission.REQUIRE_FORM 807 808**System capability**: SystemCapability.Ability.Form 809 810**Parameters** 811 812| Name| Type | Mandatory| Description | 813| ------ | ------ | ---- | ------- | 814| formIds | Array<string> | Yes | List of widget IDs.| 815 816**Return value** 817 818| Type| Description| 819| -------- | -------- | 820| Promise<void> | Promise that returns no value.| 821 822**Error codes** 823 824| Error Code ID| Error Message| 825| -------- | -------- | 826| 201 | Permissions denied. | 827| 202 | The application is not a system application. | 828| 401 | If the input parameter is not valid parameter. | 829| 16500050 | An IPC connection error happened. | 830| 16500060 | A service connection error happened, please try again later. | 831| 16501000 | An internal functional error occurred. | 832| 16501001 | The ID of the form to be operated does not exist. | 833| 16501003 | The form can not be operated by the current application. | 834 835For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). 836 837**Example** 838 839```ts 840try { 841 var formId = ['12400633174999288']; 842 formHost.disableFormsUpdate(formId).then(() => { 843 console.log('formHost disableFormsUpdate success'); 844 }).catch((error) => { 845 console.log('formHost disableFormsUpdate, error:' + JSON.stringify(error)); 846 }); 847} catch(error) { 848 console.log(`catch err->${JSON.stringify(error)}`); 849} 850``` 851 852## isSystemReady 853 854isSystemReady(callback: AsyncCallback<void>): void 855 856Checks whether the system is ready. This API uses an asynchronous callback to return the result. 857 858**System capability**: SystemCapability.Ability.Form 859 860**Parameters** 861 862| Name| Type | Mandatory| Description | 863| ------ | ------ | ---- | ------- | 864| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the check is successful, **err** is undefined; otherwise, **err** is an error object.| 865 866**Error codes** 867 868| Error Code ID| Error Message| 869| -------- | -------- | 870| 202 | The application is not a system application. | 871| 401 | If the input parameter is not valid parameter. | 872 873For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). 874 875**Example** 876 877```ts 878try { 879 var formId = '12400633174999288'; 880 formHost.isSystemReady((error, data) => { 881 if (error) { 882 console.log('formHost isSystemReady, error:' + JSON.stringify(error)); 883 } 884 }); 885} catch(error) { 886 console.log(`catch err->${JSON.stringify(error)}`); 887} 888``` 889 890## isSystemReady 891 892isSystemReady(): Promise<void> 893 894Checks whether the system is ready. This API uses a promise to return the result. 895 896**System capability**: SystemCapability.Ability.Form 897 898**Return value** 899 900| Type| Description| 901| -------- | -------- | 902| Promise<void> | Promise that returns no value.| 903 904**Error codes** 905 906| Error Code ID| Error Message| 907| -------- | -------- | 908| 202 | The application is not a system application. | 909 910For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). 911 912**Example** 913 914```ts 915try { 916 var formId = '12400633174999288'; 917 formHost.isSystemReady().then(() => { 918 console.log('formHost isSystemReady success'); 919 }).catch((error) => { 920 console.log('formHost isSystemReady, error:' + JSON.stringify(error)); 921 }); 922} catch(error) { 923 console.log(`catch err->${JSON.stringify(error)}`); 924} 925``` 926 927## getAllFormsInfo 928 929getAllFormsInfo(callback: AsyncCallback<Array<formInfo.FormInfo>>): void 930 931Obtains the widget information provided by all applications on the device. This API uses an asynchronous callback to return the result. 932 933**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 934 935**System capability**: SystemCapability.Ability.Form 936 937**Error codes** 938 939| Error Code ID| Error Message| 940| -------- | -------- | 941| 201 | Permissions denied. | 942| 202 | The application is not a system application. | 943| 401 | If the input parameter is not valid parameter. | 944| 16500050 | An IPC connection error happened. | 945| 16500060 | A service connection error happened, please try again later. | 946| 16501000 | An internal functional error occurred. | 947 948For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). 949 950**Parameters** 951 952| Name| Type | Mandatory| Description | 953| ------ | ------ | ---- | ------- | 954| callback | AsyncCallback<Array<[FormInfo](js-apis-app-form-formInfo.md)>> | Yes| Callback used to return the result. If the widget information is obtained, **err** is undefined and **data** is the information obtained; otherwise, **err** is an error object.| 955 956**Example** 957 958```ts 959try { 960 formHost.getAllFormsInfo((error, data) => { 961 if (error) { 962 console.log('formHost getAllFormsInfo, error:' + JSON.stringify(error)); 963 } else { 964 console.log('formHost getAllFormsInfo, data:' + JSON.stringify(data)); 965 } 966 }); 967} catch(error) { 968 console.log(`catch err->${JSON.stringify(error)}`); 969} 970``` 971 972## getAllFormsInfo 973 974getAllFormsInfo(): Promise<Array<formInfo.FormInfo>> 975 976Obtains the widget information provided by all applications on the device. This API uses a promise to return the result. 977 978**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 979 980**System capability**: SystemCapability.Ability.Form 981 982**Error codes** 983 984| Error Code ID| Error Message| 985| -------- | -------- | 986| 201 | Permissions denied. | 987| 202 | The application is not a system application. | 988| 16500050 | An IPC connection error happened. | 989| 16500060 | A service connection error happened, please try again later. | 990| 16501000 | An internal functional error occurred. | 991 992For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). 993 994**Return value** 995 996| Type | Description | 997| :------------ | :---------------------------------- | 998| Promise<Array<[FormInfo](js-apis-app-form-formInfo.md)>> | Promise used to return the information obtained.| 999 1000**Example** 1001 1002```ts 1003try { 1004 formHost.getAllFormsInfo().then((data) => { 1005 console.log('formHost getAllFormsInfo data:' + JSON.stringify(data)); 1006 }).catch((error) => { 1007 console.log('formHost getAllFormsInfo, error:' + JSON.stringify(error)); 1008 }); 1009} catch(error) { 1010 console.log(`catch err->${JSON.stringify(error)}`); 1011} 1012``` 1013 1014## getFormsInfo 1015 1016getFormsInfo(bundleName: string, callback: AsyncCallback<Array<formInfo.FormInfo>>): void 1017 1018Obtains the widget information provided by a given application on the device. This API uses an asynchronous callback to return the result. 1019 1020**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 1021 1022**System capability**: SystemCapability.Ability.Form 1023 1024**Parameters** 1025 1026| Name| Type | Mandatory| Description | 1027| ------ | ------ | ---- | ------- | 1028| bundleName | string | Yes| Bundle name of the application.| 1029| callback | AsyncCallback<Array<[FormInfo](js-apis-app-form-formInfo.md)>> | Yes| Callback used to return the result. If the widget information is obtained, **err** is undefined and **data** is the information obtained; otherwise, **err** is an error object.| 1030 1031**Error codes** 1032 1033| Error Code ID| Error Message| 1034| -------- | -------- | 1035| 201 | Permissions denied. | 1036| 202 | The application is not a system application. | 1037| 401 | If the input parameter is not valid parameter. | 1038| 16500050 | An IPC connection error happened. | 1039| 16500060 | A service connection error happened, please try again later. | 1040| 16500100 | Failed to obtain the configuration information. | 1041| 16501000 | An internal functional error occurred. | 1042 1043For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). 1044 1045**Example** 1046 1047```ts 1048try { 1049 formHost.getFormsInfo('com.example.ohos.formjsdemo', (error, data) => { 1050 if (error) { 1051 console.log('formHost getFormsInfo, error:' + JSON.stringify(error)); 1052 } else { 1053 console.log('formHost getFormsInfo, data:' + JSON.stringify(data)); 1054 } 1055 }); 1056} catch(error) { 1057 console.log(`catch err->${JSON.stringify(error)}`); 1058} 1059``` 1060 1061## getFormsInfo 1062 1063getFormsInfo(bundleName: string, moduleName: string, callback: AsyncCallback<Array<formInfo.FormInfo>>): void 1064 1065Obtains the widget information provided by a given application on the device. This API uses an asynchronous callback to return the result. 1066 1067**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 1068 1069**System capability**: SystemCapability.Ability.Form 1070 1071**Parameters** 1072 1073| Name| Type | Mandatory| Description | 1074| ------ | ------ | ---- | ------- | 1075| bundleName | string | Yes| Bundle name of the application.| 1076| moduleName | string | Yes| Module name.| 1077| callback | AsyncCallback<Array<[FormInfo](js-apis-app-form-formInfo.md)>> | Yes| Callback used to return the result. If the widget information is obtained, **err** is undefined and **data** is the information obtained; otherwise, **err** is an error object.| 1078 1079**Error codes** 1080 1081| Error Code ID| Error Message| 1082| -------- | -------- | 1083| 201 | Permissions denied. | 1084| 202 | The application is not a system application. | 1085| 401 | If the input parameter is not valid parameter. | 1086| 16500050 | An IPC connection error happened. | 1087| 16500060 | A service connection error happened, please try again later. | 1088| 16500100 | Failed to obtain the configuration information. | 1089| 16501000 | An internal functional error occurred. | 1090 1091For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). 1092 1093**Example** 1094 1095```ts 1096try { 1097 formHost.getFormsInfo('com.example.ohos.formjsdemo', 'entry', (error, data) => { 1098 if (error) { 1099 console.log('formHost getFormsInfo, error:' + JSON.stringify(error)); 1100 } else { 1101 console.log('formHost getFormsInfo, data:' + JSON.stringify(data)); 1102 } 1103 }); 1104} catch(error) { 1105 console.log(`catch err->${JSON.stringify(error)}`); 1106} 1107``` 1108 1109## getFormsInfo 1110 1111getFormsInfo(bundleName: string, moduleName?: string): Promise<Array<formInfo.FormInfo>> 1112 1113Obtains the widget information provided by a given application on the device. This API uses a promise to return the result. 1114 1115**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 1116 1117**System capability**: SystemCapability.Ability.Form 1118 1119**Parameters** 1120 1121| Name| Type | Mandatory| Description | 1122| ------ | ------ | ---- | ------- | 1123| bundleName | string | Yes| Bundle name of the application.| 1124| moduleName | string | No| Module name.| 1125 1126**Return value** 1127 1128| Type | Description | 1129| :------------ | :---------------------------------- | 1130| Promise<Array<[FormInfo](js-apis-app-form-formInfo.md)>> | Promise used to return the information obtained.| 1131 1132**Error codes** 1133 1134| Error Code ID| Error Message| 1135| -------- | -------- | 1136| 201 | Permissions denied. | 1137| 202 | The application is not a system application. | 1138| 401 | If the input parameter is not valid parameter. | 1139| 16500050 | An IPC connection error happened. | 1140| 16500060 | A service connection error happened, please try again later. | 1141| 16500100 | Failed to obtain the configuration information. | 1142| 16501000 | An internal functional error occurred. | 1143 1144For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). 1145 1146**Example** 1147 1148```ts 1149try { 1150 formHost.getFormsInfo('com.example.ohos.formjsdemo', 'entry').then((data) => { 1151 console.log('formHost getFormsInfo, data:' + JSON.stringify(data)); 1152 }).catch((error) => { 1153 console.log('formHost getFormsInfo, error:' + JSON.stringify(error)); 1154 }); 1155} catch(error) { 1156 console.log(`catch err->${JSON.stringify(error)}`); 1157} 1158``` 1159 1160## deleteInvalidForms 1161 1162deleteInvalidForms(formIds: Array<string>, callback: AsyncCallback<number>): void 1163 1164Deletes invalid widgets from the list. This API uses an asynchronous callback to return the result. 1165 1166**Required permissions**: ohos.permission.REQUIRE_FORM 1167 1168**System capability**: SystemCapability.Ability.Form 1169 1170**Parameters** 1171 1172| Name| Type | Mandatory| Description | 1173| ------ | ------ | ---- | ------- | 1174| formIds | Array<string> | Yes | List of valid widget IDs.| 1175| callback | AsyncCallback<number> | Yes| Callback used to return the result. If the invalid widgets are deleted, **err** is undefined and **data** is the number of widgets deleted; otherwise, **err** is an error object.| 1176 1177**Error codes** 1178 1179| Error Code ID| Error Message| 1180| -------- | -------- | 1181| 201 | Permissions denied. | 1182| 202 | The application is not a system application. | 1183| 401 | If the input parameter is not valid parameter. | 1184| 16500050 | An IPC connection error happened. | 1185| 16500060 | A service connection error happened, please try again later. | 1186| 16501000 | An internal functional error occurred. | 1187 1188For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). 1189 1190**Example** 1191 1192```ts 1193try { 1194 var formIds = new Array('12400633174999288', '12400633174999289'); 1195 formHost.deleteInvalidForms(formIds, (error, data) => { 1196 if (error) { 1197 console.log('formHost deleteInvalidForms, error:' + JSON.stringify(error)); 1198 } else { 1199 console.log('formHost deleteInvalidForms, data:' + JSON.stringify(data)); 1200 } 1201 }); 1202} catch(error) { 1203 console.log(`catch err->${JSON.stringify(error)}`); 1204} 1205``` 1206 1207## deleteInvalidForms 1208 1209deleteInvalidForms(formIds: Array<string>): Promise<number> 1210 1211Deletes invalid widgets from the list. This API uses a promise to return the result. 1212 1213**Required permissions**: ohos.permission.REQUIRE_FORM 1214 1215**System capability**: SystemCapability.Ability.Form 1216 1217**Parameters** 1218 1219| Name| Type | Mandatory| Description | 1220| ------ | ------ | ---- | ------- | 1221| formIds | Array<string> | Yes | List of valid widget IDs.| 1222 1223**Return value** 1224 1225| Type | Description | 1226| :------------ | :---------------------------------- | 1227| Promise<number> | Promise used to return the number of widgets deleted.| 1228 1229**Error codes** 1230 1231| Error Code ID| Error Message| 1232| -------- | -------- | 1233| 201 | Permissions denied. | 1234| 202 | The application is not a system application. | 1235| 401 | If the input parameter is not valid parameter. | 1236| 16500050 | An IPC connection error happened. | 1237| 16500060 | A service connection error happened, please try again later. | 1238| 16501000 | An internal functional error occurred. | 1239 1240For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). 1241 1242**Example** 1243 1244```ts 1245try { 1246 var formIds = new Array('12400633174999288', '12400633174999289'); 1247 formHost.deleteInvalidForms(formIds).then((data) => { 1248 console.log('formHost deleteInvalidForms, data:' + JSON.stringify(data)); 1249 }).catch((error) => { 1250 console.log('formHost deleteInvalidForms, error:' + JSON.stringify(error)); 1251 }); 1252} catch(error) { 1253 console.log(`catch err->${JSON.stringify(error)}`); 1254} 1255``` 1256 1257## acquireFormState 1258 1259acquireFormState(want: Want, callback: AsyncCallback<formInfo.FormStateInfo>): void 1260 1261Obtains the widget state. This API uses an asynchronous callback to return the result. 1262 1263**Required permissions**: ohos.permission.REQUIRE_FORM and ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 1264 1265**System capability**: SystemCapability.Ability.Form 1266 1267**Parameters** 1268 1269| Name| Type | Mandatory| Description | 1270| ------ | ------ | ---- | ------- | 1271| want | [Want](js-apis-application-want.md) | Yes | **Want** information carried to query the widget state.| 1272| callback | AsyncCallback<[FormStateInfo](js-apis-app-form-formInfo.md#formstateinfo)> | Yes| Callback used to return the result. If the widget state is obtained, **err** is undefined and **data** is the widget state obtained; otherwise, **err** is an error object.| 1273 1274**Error codes** 1275 1276| Error Code ID| Error Message| 1277| -------- | -------- | 1278| 201 | Permissions denied. | 1279| 202 | The application is not a system application. | 1280| 401 | If the input parameter is not valid parameter. | 1281| 16500050 | An IPC connection error happened. | 1282| 16500060 | A service connection error happened, please try again later. | 1283| 16500100 | Failed to obtain the configuration information. | 1284| 16501000 | An internal functional error occurred. | 1285 1286For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). 1287 1288**Example** 1289 1290```ts 1291var want = { 1292 'deviceId': '', 1293 'bundleName': 'ohos.samples.FormApplication', 1294 'abilityName': 'FormAbility', 1295 'parameters': { 1296 'ohos.extra.param.key.module_name': 'entry', 1297 'ohos.extra.param.key.form_name': 'widget', 1298 'ohos.extra.param.key.form_dimension': 2 1299 } 1300}; 1301try { 1302 formHost.acquireFormState(want, (error, data) => { 1303 if (error) { 1304 console.log('formHost acquireFormState, error:' + JSON.stringify(error)); 1305 } else { 1306 console.log('formHost acquireFormState, data:' + JSON.stringify(data)); 1307 } 1308 }); 1309} catch(error) { 1310 console.log(`catch err->${JSON.stringify(error)}`); 1311} 1312``` 1313 1314## acquireFormState 1315 1316acquireFormState(want: Want): Promise<formInfo.FormStateInfo> 1317 1318Obtains the widget state. This API uses a promise to return the result. 1319 1320**Required permissions**: ohos.permission.REQUIRE_FORM and ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 1321 1322**System capability**: SystemCapability.Ability.Form 1323 1324**Parameters** 1325 1326| Name| Type | Mandatory| Description | 1327| ------ | ------ | ---- | ------- | 1328| want | [Want](js-apis-application-want.md) | Yes | **Want** information carried to query the widget state.| 1329 1330**Return value** 1331 1332| Type | Description | 1333| :------------ | :---------------------------------- | 1334| Promise<[FormStateInfo](js-apis-app-form-formInfo.md#formstateinfo)> | Promise used to return the widget state obtained.| 1335 1336**Error codes** 1337 1338| Error Code ID| Error Message| 1339| -------- | -------- | 1340| 201 | Permissions denied. | 1341| 202 | The application is not a system application. | 1342| 401 | If the input parameter is not valid parameter. | 1343| 16500050 | An IPC connection error happened. | 1344| 16500060 | A service connection error happened, please try again later. | 1345| 16500100 | Failed to obtain the configuration information. | 1346| 16501000 | An internal functional error occurred. | 1347 1348For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). 1349 1350**Example** 1351 1352```ts 1353var want = { 1354 'deviceId': '', 1355 'bundleName': 'ohos.samples.FormApplication', 1356 'abilityName': 'FormAbility', 1357 'parameters': { 1358 'ohos.extra.param.key.module_name': 'entry', 1359 'ohos.extra.param.key.form_name': 'widget', 1360 'ohos.extra.param.key.form_dimension': 2 1361 } 1362}; 1363try { 1364 formHost.acquireFormState(want).then((data) => { 1365 console.log('formHost acquireFormState, data:' + JSON.stringify(data)); 1366 }).catch((error) => { 1367 console.log('formHost acquireFormState, error:' + JSON.stringify(error)); 1368 }); 1369} catch(error) { 1370 console.log(`catch err->${JSON.stringify(error)}`); 1371} 1372``` 1373 1374## on('formUninstall') 1375 1376on(type: 'formUninstall', callback: Callback<string>): void 1377 1378Subscribes to widget uninstall events. This API uses an asynchronous callback to return the result. 1379 1380**System capability**: SystemCapability.Ability.Form 1381 1382**Parameters** 1383 1384| Name| Type | Mandatory| Description | 1385| ------ | ------ | ---- | ------- | 1386| type | string | Yes | Event type. The value **'formUninstall'** indicates a widget uninstall event.| 1387| callback | Callback<string> | Yes| Callback used to return the widget ID.| 1388 1389**Error codes** 1390 1391| Error Code ID| Error Message| 1392| -------- | -------- | 1393| 202 | The application is not a system application. | 1394| 401 | If the input parameter is not valid parameter. | 1395 1396For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). 1397 1398**Example** 1399 1400```ts 1401let callback = function(formId) { 1402 console.log('formHost on formUninstall, formId:' + formId); 1403} 1404formHost.on('formUninstall', callback); 1405``` 1406 1407## off('formUninstall') 1408 1409off(type: 'formUninstall', callback?: Callback<string>): void 1410 1411Unsubscribes from widget uninstall events. This API uses an asynchronous callback to return the result. 1412 1413**System capability**: SystemCapability.Ability.Form 1414 1415**Parameters** 1416 1417| Name| Type | Mandatory| Description | 1418| ------ | ------ | ---- | ------- | 1419| type | string | Yes | Event type. The value **'formUninstall'** indicates a widget uninstall event.| 1420| 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.| 1421 1422**Error codes** 1423 1424| Error Code ID| Error Message| 1425| -------- | -------- | 1426| 202 | The application is not a system application. | 1427| 401 | If the input parameter is not valid parameter. | 1428 1429For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). 1430 1431**Example** 1432 1433```ts 1434let callback = function(formId) { 1435 console.log('formHost on formUninstall, formId:' + formId); 1436} 1437formHost.off('formUninstall', callback); 1438``` 1439 1440## notifyFormsVisible 1441 1442notifyFormsVisible(formIds: Array<string>, isVisible: boolean, callback: AsyncCallback<void>): void 1443 1444Instructs the widgets to make themselves visible. This API uses an asynchronous callback to return the result. 1445 1446**Required permissions**: ohos.permission.REQUIRE_FORM 1447 1448**System capability**: SystemCapability.Ability.Form 1449 1450**Parameters** 1451 1452| Name| Type | Mandatory| Description | 1453| ------ | ------ | ---- | ------- | 1454| formIds | Array<string> | Yes | List of widget IDs.| 1455| isVisible | boolean | Yes | Whether to make the widgets visible.| 1456| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the notification is sent, **err** is undefined; otherwise, **err** is an error object.| 1457 1458**Error codes** 1459 1460| Error Code ID| Error Message| 1461| -------- | -------- | 1462| 201 | Permissions denied. | 1463| 202 | The application is not a system application. | 1464| 401 | If the input parameter is not valid parameter. | 1465| 16500050 | An IPC connection error happened. | 1466| 16500060 | A service connection error happened, please try again later. | 1467| 16501000 | An internal functional error occurred. | 1468| 16501003 | The form can not be operated by the current application. | 1469 1470For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). 1471 1472**Example** 1473 1474```ts 1475var formIds = new Array('12400633174999288', '12400633174999289'); 1476try { 1477 formHost.notifyFormsVisible(formIds, true, (error, data) => { 1478 if (error) { 1479 console.log('formHost notifyFormsVisible, error:' + JSON.stringify(error)); 1480 } 1481 }); 1482} catch(error) { 1483 console.log(`catch err->${JSON.stringify(error)}`); 1484} 1485``` 1486 1487## notifyFormsVisible 1488 1489notifyFormsVisible(formIds: Array<string>, isVisible: boolean): Promise<void> 1490 1491Instructs the widgets to make themselves visible. This API uses a promise to return the result. 1492 1493**Required permissions**: ohos.permission.REQUIRE_FORM 1494 1495**System capability**: SystemCapability.Ability.Form 1496 1497**Parameters** 1498 1499| Name| Type | Mandatory| Description | 1500| ------ | ------ | ---- | ------- | 1501| formIds | Array<string> | Yes | List of widget IDs.| 1502| isVisible | boolean | Yes | Whether to make the widgets visible.| 1503 1504**Return value** 1505 1506| Type| Description| 1507| -------- | -------- | 1508| Promise<void> | Promise that returns no value.| 1509 1510**Error codes** 1511 1512| Error Code ID| Error Message| 1513| -------- | -------- | 1514| 201 | Permissions denied. | 1515| 202 | The application is not a system application. | 1516| 401 | If the input parameter is not valid parameter. | 1517| 16500050 | An IPC connection error happened. | 1518| 16500060 | A service connection error happened, please try again later. | 1519| 16501000 | An internal functional error occurred. | 1520| 16501003 | The form can not be operated by the current application. | 1521 1522For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). 1523 1524**Example** 1525 1526```ts 1527var formIds = new Array('12400633174999288', '12400633174999289'); 1528try { 1529 formHost.notifyFormsVisible(formIds, true).then(() => { 1530 console.log('formHost notifyFormsVisible success'); 1531 }).catch((error) => { 1532 console.log('formHost notifyFormsVisible, error:' + JSON.stringify(error)); 1533 }); 1534} catch(error) { 1535 console.log(`catch err->${JSON.stringify(error)}`); 1536} 1537``` 1538 1539## notifyFormsEnableUpdate 1540 1541notifyFormsEnableUpdate(formIds: Array<string>, isEnableUpdate: boolean, callback: AsyncCallback<void>): void 1542 1543Instructs the widgets to enable or disable updates. This API uses an asynchronous callback to return the result. 1544 1545**Required permissions**: ohos.permission.REQUIRE_FORM 1546 1547**System capability**: SystemCapability.Ability.Form 1548 1549**Parameters** 1550 1551| Name| Type | Mandatory| Description | 1552| ------ | ------ | ---- | ------- | 1553| formIds | Array<string> | Yes | List of widget IDs.| 1554| isEnableUpdate | boolean | Yes | Whether to make the widgets updatable.| 1555| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the notification is sent, **err** is undefined; otherwise, **err** is an error object.| 1556 1557**Error codes** 1558 1559| Error Code ID| Error Message| 1560| -------- | -------- | 1561| 201 | Permissions denied. | 1562| 202 | The application is not a system application. | 1563| 401 | If the input parameter is not valid parameter. | 1564| 16500050 | An IPC connection error happened. | 1565| 16500060 | A service connection error happened, please try again later. | 1566| 16501000 | An internal functional error occurred. | 1567| 16501003 | The form can not be operated by the current application. | 1568 1569For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). 1570 1571**Example** 1572 1573```ts 1574var formIds = new Array('12400633174999288', '12400633174999289'); 1575try { 1576 formHost.notifyFormsEnableUpdate(formIds, true, (error, data) => { 1577 if (error) { 1578 console.log('formHost notifyFormsEnableUpdate, error:' + JSON.stringify(error)); 1579 } 1580 }); 1581} catch(error) { 1582 console.log(`catch err->${JSON.stringify(error)}`); 1583} 1584``` 1585 1586## notifyFormsEnableUpdate 1587 1588notifyFormsEnableUpdate(formIds: Array<string>, isEnableUpdate: boolean): Promise<void> 1589 1590Instructs the widgets to enable or disable updates. This API uses a promise to return the result. 1591 1592**Required permissions**: ohos.permission.REQUIRE_FORM 1593 1594**System capability**: SystemCapability.Ability.Form 1595 1596**Parameters** 1597 1598| Name| Type | Mandatory| Description | 1599| ------ | ------ | ---- | ------- | 1600| formIds | Array<string> | Yes | List of widget IDs.| 1601| isEnableUpdate | boolean | Yes | Whether to make the widgets updatable.| 1602 1603**Return value** 1604 1605| Type| Description| 1606| -------- | -------- | 1607| Promise<void> | Promise that returns no value.| 1608 1609**Error codes** 1610 1611| Error Code ID| Error Message| 1612| -------- | -------- | 1613| 201 | Permissions denied. | 1614| 202 | The application is not a system application. | 1615| 401 | If the input parameter is not valid parameter. | 1616| 16500050 | An IPC connection error happened. | 1617| 16500060 | A service connection error happened, please try again later. | 1618| 16501000 | An internal functional error occurred. | 1619| 16501003 | The form can not be operated by the current application. | 1620 1621For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). 1622 1623**Example** 1624 1625```ts 1626var formIds = new Array('12400633174999288', '12400633174999289'); 1627try { 1628 formHost.notifyFormsEnableUpdate(formIds, true).then(() => { 1629 console.log('formHost notifyFormsEnableUpdate success'); 1630 }).catch((error) => { 1631 console.log('formHost notifyFormsEnableUpdate, error:' + JSON.stringify(error)); 1632 }); 1633} catch(error) { 1634 console.log(`catch err->${JSON.stringify(error)}`); 1635} 1636``` 1637## shareForm 1638 1639shareForm(formId: string, deviceId: string, callback: AsyncCallback<void>): void 1640 1641Shares a specified widget with a remote device. This API uses an asynchronous callback to return the result. 1642 1643**Required permissions**: ohos.permission.REQUIRE_FORM and ohos.permission.DISTRIBUTED_DATASYNC 1644 1645**System capability**: SystemCapability.Ability.Form 1646 1647**Parameters** 1648 1649| Name| Type | Mandatory| Description | 1650| ------ | ------ | ---- | ------- | 1651| formId | string | Yes | Widget ID.| 1652| deviceId | string | Yes | Remote device ID.| 1653| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the widget is shared, **err** is undefined; otherwise, **err** is an error object.| 1654 1655**Error codes** 1656 1657| Error Code ID| Error Message| 1658| -------- | -------- | 1659| 201 | Permissions denied. | 1660| 202 | The application is not a system application. | 1661| 401 | If the input parameter is not valid parameter. | 1662| 16500050 | An IPC connection error happened. | 1663| 16501000 | An internal functional error occurred. | 1664| 16501001 | The ID of the form to be operated does not exist. | 1665| 16501003 | The form can not be operated by the current application. | 1666 1667For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). 1668 1669**Example** 1670 1671```ts 1672var formId = '12400633174999288'; 1673var deviceId = 'EFC11C0C53628D8CC2F8CB5052477E130D075917034613B9884C55CD22B3DEF2'; 1674try { 1675 formHost.shareForm(formId, deviceId, (error, data) => { 1676 if (error) { 1677 console.log('formHost shareForm, error:' + JSON.stringify(error)); 1678 } 1679 }); 1680} catch(error) { 1681 console.log(`catch err->${JSON.stringify(error)}`); 1682} 1683``` 1684 1685## shareForm 1686 1687shareForm(formId: string, deviceId: string): Promise<void> 1688 1689Shares a specified widget with a remote device. This API uses a promise to return the result. 1690 1691**Required permissions**: ohos.permission.REQUIRE_FORM and ohos.permission.DISTRIBUTED_DATASYNC 1692 1693**System capability**: SystemCapability.Ability.Form 1694 1695**Parameters** 1696 1697| Name| Type | Mandatory| Description | 1698| ------ | ------ | ---- | ------- | 1699| formId | string | Yes | Widget ID.| 1700| deviceId | string | Yes | Remote device ID.| 1701 1702**Return value** 1703 1704| Type| Description| 1705| -------- | -------- | 1706| Promise<void> | Promise that returns no value.| 1707 1708**Error codes** 1709 1710| Error Code ID| Error Message| 1711| -------- | -------- | 1712| 201 | Permissions denied. | 1713| 202 | The application is not a system application. | 1714| 401 | If the input parameter is not valid parameter. | 1715| 16500050 | An IPC connection error happened. | 1716| 16501000 | An internal functional error occurred. | 1717| 16501001 | The ID of the form to be operated does not exist. | 1718| 16501003 | The form can not be operated by the current application. | 1719 1720For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). 1721 1722**Example** 1723 1724```ts 1725var formId = '12400633174999288'; 1726var deviceId = 'EFC11C0C53628D8CC2F8CB5052477E130D075917034613B9884C55CD22B3DEF2'; 1727try { 1728 formHost.shareForm(formId, deviceId).then(() => { 1729 console.log('formHost shareForm success'); 1730 }).catch((error) => { 1731 console.log('formHost shareForm, error:' + JSON.stringify(error)); 1732 }); 1733} catch(error) { 1734 console.log(`catch err->${JSON.stringify(error)}`); 1735} 1736``` 1737 1738## notifyFormsPrivacyProtected 1739 1740notifyFormsPrivacyProtected(formIds: Array\<string>, isProtected: boolean, callback: AsyncCallback\<void>): void 1741 1742**Required permissions**: ohos.permission.REQUIRE_FORM 1743 1744**System capability**: SystemCapability.Ability.Form 1745 1746**Parameters** 1747 1748| Name| Type | Mandatory| Description | 1749| ------ | ------ | ---- | ------- | 1750| formIds | Array\<string\> | Yes | ID of the widgets.| 1751| isProtected | boolean | Yes | Whether privacy protection is enabled.| 1752| callback | AsyncCallback\<void> | Yes| Callback used to return the result. If privacy protection is set successfully, **error** is undefined; otherwise, **error** is an error object.| 1753 1754**Error codes** 1755 1756| Error Code ID| Error Message| 1757| -------- | -------- | 1758| 201 | Permissions denied. | 1759| 202 | The application is not a system application. | 1760| 401 | If the input parameter is not valid parameter. | 1761| 16500050 | An IPC connection error happened. | 1762| 16500060 | A service connection error happened, please try again later. | 1763| 16501000 | An internal functional error occurred. | 1764 1765For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). 1766 1767**Example** 1768 1769```ts 1770import formHost from '@ohos.app.form.formHost'; 1771 1772let formIds = new Array('12400633174999288', '12400633174999289'); 1773try { 1774 formHost.notifyFormsPrivacyProtected(formIds, true, (error) => { 1775 if (error) { 1776 console.error(`error, code: ${error.code}, message: ${error.message}`); 1777 } 1778 }); 1779} catch(error) { 1780 console.error(`catch error, code: ${error.code}, message: ${error.message}`); 1781} 1782``` 1783 1784## notifyFormsPrivacyProtected 1785 1786notifyFormsPrivacyProtected(formIds: Array\<string\>, isProtected: boolean): Promise\<void\>; 1787 1788Notifies that the privacy protection status of the specified widgets changes. This API uses a promise to return the result. 1789 1790**Required permissions**: ohos.permission.REQUIRE_FORM 1791 1792**System capability**: SystemCapability.Ability.Form 1793 1794**Parameters** 1795 1796| Name | Type | Mandatory| Description | 1797| ----------- | --------------- | ---- | -------------------------------- | 1798| formIds | Array\<string\> | Yes | ID of the widgets.| 1799| isProtected | boolean | Yes | Whether privacy protection is enabled. | 1800 1801**Return value** 1802 1803| Type | Description | 1804| ------------------- | ------------------------- | 1805| Promise<void> | Promise that returns no value.| 1806 1807**Error codes** 1808 1809| Error Code ID| Error Message| 1810| -------- | -------- | 1811| 201 | Permissions denied. | 1812| 202 | The application is not a system application. | 1813| 401 | If the input parameter is not valid parameter. | 1814| 16500050 | An IPC connection error happened. | 1815| 16500060 | A service connection error happened, please try again later. | 1816| 16501000 | An internal functional error occurred. | 1817 1818For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). 1819 1820```ts 1821import formHost from '@ohos.app.form.formHost'; 1822 1823let formIds = new Array('12400633174999288', '12400633174999289'); 1824try { 1825 formHost.notifyFormsPrivacyProtected(formIds, true).then(() => { 1826 console.log('formHost shareForm success'); 1827 }).catch((error) => { 1828 console.log('formHost shareForm, error:' + JSON.stringify(error)); 1829 }); 1830} catch(error) { 1831 console.log(`catch err->${JSON.stringify(error)}`); 1832} 1833``` 1834