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