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