1# @ohos.app.form.formHost (formHost) (System API) 2 3<!--Kit: Form Kit--> 4<!--Subsystem: Ability--> 5<!--Owner: @cx983299475--> 6<!--Designer: @xueyulong--> 7<!--Tester: @chenmingze--> 8<!--Adviser: @Brilliantry_Rui--> 9The **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. 10 11> **NOTE** 12> 13> 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. 14> The APIs provided by this module are system APIs. 15 16## Modules to Import 17 18```ts 19import { formHost } from '@kit.FormKit'; 20``` 21 22## deleteForm 23 24deleteForm(formId: string, callback: AsyncCallback<void>): void 25 26Deletes 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. 27 28**Required permissions**: ohos.permission.REQUIRE_FORM 29 30**System capability**: SystemCapability.Ability.Form 31 32**Parameters** 33 34| Name| Type | Mandatory| Description | 35| ------ | ------ | ---- | ------- | 36| formId | string | Yes | Widget ID.| 37| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the widget is deleted, **error** is undefined; otherwise, **error** is an error object.| 38 39**Error codes** 40 41For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 42 43| Error Code ID| Error Message| 44| -------- | -------- | 45| 201 | Permissions denied. | 46| 202 | The application is not a system application. | 47| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 48| 16500050 | IPC connection error. | 49| 16500060 | Service connection error. | 50| 16501000 | An internal functional error occurred. | 51| 16501001 | The ID of the form to be operated does not exist. | 52| 16501003 | The form cannot be operated by the current application. | 53 54**Example** 55 56```ts 57import { formHost } from '@kit.FormKit'; 58import { BusinessError } from '@kit.BasicServicesKit'; 59 60try { 61 let formId: string = '12400633174999288'; 62 formHost.deleteForm(formId, (error: BusinessError) => { 63 if (error) { 64 console.error(`error, code: ${error.code}, message: ${error.message}`); 65 } else { 66 console.log('formHost deleteForm success'); 67 } 68 }); 69} catch (error) { 70 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 71} 72``` 73 74## deleteForm 75 76deleteForm(formId: string): Promise<void> 77 78Deletes 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. 79 80**Required permissions**: ohos.permission.REQUIRE_FORM 81 82**System capability**: SystemCapability.Ability.Form 83 84**Parameters** 85 86| Name| Type | Mandatory| Description | 87| ------ | ------ | ---- | ------- | 88| formId | string | Yes | Widget ID.| 89 90**Return value** 91 92| Type| Description| 93| -------- | -------- | 94| Promise<void> | Promise that returns no value.| 95 96 97**Error codes** 98 99For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 100 101| Error Code ID| Error Message| 102| -------- | -------- | 103| 201 | Permissions denied. | 104| 202 | The application is not a system application. | 105| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 106| 16500050 | IPC connection error. | 107| 16500060 | Service connection error. | 108| 16501000 | An internal functional error occurred. | 109| 16501001 | The ID of the form to be operated does not exist. | 110| 16501003 | The form cannot be operated by the current application. | 111 112**Example** 113 114```ts 115import { formHost } from '@kit.FormKit'; 116import { BusinessError } from '@kit.BasicServicesKit'; 117 118try { 119 let formId: string = '12400633174999288'; 120 formHost.deleteForm(formId).then(() => { 121 console.log('formHost deleteForm success'); 122 }).catch((error: BusinessError) => { 123 console.error(`formHost deleteForm, error: ${JSON.stringify(error)}`); 124 }); 125} catch (error) { 126 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 127} 128``` 129 130## releaseForm 131 132releaseForm(formId: string, callback: AsyncCallback<void>): void 133 134Releases 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. 135 136**Required permissions**: ohos.permission.REQUIRE_FORM 137 138**System capability**: SystemCapability.Ability.Form 139 140**Parameters** 141 142| Name| Type | Mandatory| Description | 143| ------ | ------ | ---- | ------- | 144| formId | string | Yes | Widget ID.| 145| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the widget is released, **error** is undefined; otherwise, **error** is an error object.| 146 147**Error codes** 148 149For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 150 151| Error Code ID| Error Message| 152| -------- | -------- | 153| 201 | Permissions denied. | 154| 202 | The application is not a system application. | 155| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 156| 16500050 | IPC connection error. | 157| 16500060 | Service connection error. | 158| 16501000 | An internal functional error occurred. | 159| 16501001 | The ID of the form to be operated does not exist. | 160| 16501003 | The form cannot be operated by the current application. | 161 162**Example** 163 164```ts 165import { formHost } from '@kit.FormKit'; 166import { BusinessError } from '@kit.BasicServicesKit'; 167 168try { 169 let formId: string = '12400633174999288'; 170 formHost.releaseForm(formId, (error: BusinessError) => { 171 if (error) { 172 console.error(`error, code: ${error.code}, message: ${error.message}`); 173 } 174 }); 175} catch (error) { 176 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 177} 178``` 179 180## releaseForm 181 182releaseForm(formId: string, isReleaseCache: boolean, callback: AsyncCallback<void>): void 183 184Releases 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. 185 186**Required permissions**: ohos.permission.REQUIRE_FORM 187 188**System capability**: SystemCapability.Ability.Form 189 190**Parameters** 191 192| Name | Type | Mandatory| Description | 193| -------------- | ------ | ---- | ----------- | 194| formId | string | Yes | Widget ID. | 195| isReleaseCache | boolean | Yes | Whether to release the cache.<br>**true**: Release the cache.<br>**false**: Not release the cache.| 196| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the widget is released, **error** is undefined; otherwise, **error** is an error object.| 197 198**Error codes** 199 200For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 201 202| Error Code ID| Error Message| 203| -------- | -------- | 204| 201 | Permissions denied. | 205| 202 | The application is not a system application. | 206| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 207| 16500050 | IPC connection error. | 208| 16500060 | Service connection error. | 209| 16501000 | An internal functional error occurred. | 210| 16501001 | The ID of the form to be operated does not exist. | 211| 16501003 | The form cannot be operated by the current application. | 212 213**Example** 214 215```ts 216import { formHost } from '@kit.FormKit'; 217import { BusinessError } from '@kit.BasicServicesKit'; 218 219try { 220 let formId: string = '12400633174999288'; 221 formHost.releaseForm(formId, true, (error: BusinessError) => { 222 if (error) { 223 console.error(`error, code: ${error.code}, message: ${error.message}`); 224 } 225 }); 226} catch(error) { 227 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 228} 229``` 230 231## releaseForm 232 233releaseForm(formId: string, isReleaseCache?: boolean): Promise<void> 234 235Releases 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. 236 237**Required permissions**: ohos.permission.REQUIRE_FORM 238 239**System capability**: SystemCapability.Ability.Form 240 241**Parameters** 242 243| Name | Type | Mandatory| Description | 244| -------------- | ------ | ---- | ----------- | 245| formId | string | Yes | Widget ID. | 246| isReleaseCache | boolean | No | Whether to release the cache. The default value is **false**.<br>**true**: Release the cache.<br>**false**: Not release the cache. | 247 248**Return value** 249 250| Type| Description| 251| -------- | -------- | 252| Promise<void> | Promise that returns no value.| 253 254**Error codes** 255 256For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 257 258| Error Code ID| Error Message| 259| -------- | -------- | 260| 201 | Permissions denied. | 261| 202 | The application is not a system application. | 262| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 263| 16500050 | IPC connection error. | 264| 16500060 | Service connection error. | 265| 16501000 | An internal functional error occurred. | 266| 16501001 | The ID of the form to be operated does not exist. | 267| 16501003 | The form cannot be operated by the current application. | 268 269**Example** 270 271```ts 272import { formHost } from '@kit.FormKit'; 273import { BusinessError } from '@kit.BasicServicesKit'; 274 275try { 276 let formId: string = '12400633174999288'; 277 formHost.releaseForm(formId, true).then(() => { 278 console.log('formHost releaseForm success'); 279 }).catch((error: BusinessError) => { 280 console.error(`error, code: ${error.code}, message: ${error.message}`); 281 }); 282} catch(error) { 283 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 284} 285``` 286 287## requestForm 288 289requestForm(formId: string, callback: AsyncCallback<void>): void 290 291Requests a widget update. This API uses an asynchronous callback to return the result. 292 293**Required permissions**: ohos.permission.REQUIRE_FORM 294 295**System capability**: SystemCapability.Ability.Form 296 297**Parameters** 298 299| Name| Type | Mandatory| Description | 300| ------ | ------ | ---- | ------- | 301| formId | string | Yes | Widget ID.| 302| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the widget is updated, **error** is undefined; otherwise, **error** is an error object.| 303 304**Error codes** 305 306For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 307 308| Error Code ID| Error Message| 309| -------- | -------- | 310| 201 | Permissions denied. | 311| 202 | The application is not a system application. | 312| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 313| 16500050 | IPC connection error. | 314| 16500060 | Service connection error. | 315| 16501000 | An internal functional error occurred. | 316| 16501001 | The ID of the form to be operated does not exist. | 317| 16501003 | The form cannot be operated by the current application. | 318 319**Example** 320 321```ts 322import { formHost } from '@kit.FormKit'; 323import { BusinessError } from '@kit.BasicServicesKit'; 324 325try { 326 let formId: string = '12400633174999288'; 327 formHost.requestForm(formId, (error: BusinessError) => { 328 if (error) { 329 console.error(`error, code: ${error.code}, message: ${error.message}`); 330 } 331 }); 332} catch(error) { 333 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 334} 335``` 336 337## requestForm 338 339requestForm(formId: string): Promise<void> 340 341Requests a widget update. This API uses a promise to return the result. 342 343**Required permissions**: ohos.permission.REQUIRE_FORM 344 345**System capability**: SystemCapability.Ability.Form 346 347**Parameters** 348 349| Name| Type | Mandatory| Description | 350| ------ | ------ | ---- | ------- | 351| formId | string | Yes | Widget ID.| 352 353**Return value** 354 355| Type| Description| 356| -------- | -------- | 357| Promise<void> | Promise that returns no value.| 358 359**Error codes** 360 361For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 362 363| Error Code ID| Error Message| 364| -------- | -------- | 365| 201 | Permissions denied. | 366| 202 | The application is not a system application. | 367| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 368| 16500050 | IPC connection error. | 369| 16500060 | Service connection error. | 370| 16501000 | An internal functional error occurred. | 371| 16501001 | The ID of the form to be operated does not exist. | 372| 16501003 | The form cannot be operated by the current application. | 373 374**Example** 375 376```ts 377import { formHost } from '@kit.FormKit'; 378import { BusinessError } from '@kit.BasicServicesKit'; 379 380try { 381 let formId: string = '12400633174999288'; 382 formHost.requestForm(formId).then(() => { 383 console.log('formHost requestForm success'); 384 }).catch((error: BusinessError) => { 385 console.error(`error, code: ${error.code}, message: ${error.message}`); 386 }); 387} catch(error) { 388 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 389} 390``` 391 392## requestFormWithParams<sup>12+</sup> 393 394requestFormWithParams(formId: string, wantParams?: Record<string, Object>): Promise<void> 395 396Carries parameters to request a widget update. This API uses a promise to return the result. 397 398**Required permissions**: ohos.permission.REQUIRE_FORM 399 400**System capability**: SystemCapability.Ability.Form 401 402**Parameters** 403 404| Name| Type | Mandatory| Description | 405| ------ | ------ | ---- | ------- | 406| formId | string | Yes | Widget ID.| 407| wantParams | Record<string, Object> | No | Parameters used for the update.| 408 409**Return value** 410 411| Type| Description| 412| -------- | -------- | 413| Promise<void> | Promise that returns no value.| 414 415**Error codes** 416 417For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 418 419| Error Code ID| Error Message| 420| -------- | -------- | 421| 201 | Permissions denied. | 422| 202 | The application is not a system application. | 423| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 424| 16500050 | IPC connection error. | 425| 16500060 | Service connection error. | 426| 16501000 | An internal functional error occurred. | 427| 16501001 | The ID of the form to be operated does not exist. | 428| 16501003 | The form cannot be operated by the current application. | 429 430**Example** 431 432```ts 433import { formHost } from '@kit.FormKit'; 434import { BusinessError } from '@kit.BasicServicesKit'; 435 436try { 437 let formId: string = '12400633174999288'; 438 let params: Record<string, Object> = { 439 'ohos.extra.param.key.host_bg_inverse_color': '#ff000000' as Object 440 }; 441 formHost.requestFormWithParams(formId, params).then(() => { 442 console.log('formHost requestFormWithParams success'); 443 }).catch((error: BusinessError) => { 444 console.error(`error, code: ${error.code}, message: ${error.message}`); 445 }); 446} catch(error) { 447 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 448} 449``` 450 451## castToNormalForm 452 453castToNormalForm(formId: string, callback: AsyncCallback<void>): void 454 455Converts a temporary widget to a normal one. This API uses an asynchronous callback to return the result. 456 457**Required permissions**: ohos.permission.REQUIRE_FORM 458 459**System capability**: SystemCapability.Ability.Form 460 461**Parameters** 462 463| Name| Type | Mandatory| Description | 464| ------ | ------ | ---- | ------- | 465| formId | string | Yes | Widget ID.| 466| 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.| 467 468**Error codes** 469 470For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 471 472| Error Code ID| Error Message| 473| -------- | -------- | 474| 201 | Permissions denied. | 475| 202 | The application is not a system application. | 476| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 477| 16500050 | IPC connection error. | 478| 16501000 | An internal functional error occurred. | 479| 16501001 | The ID of the form to be operated does not exist. | 480| 16501002 | The number of forms exceeds the maximum allowed. | 481| 16501003 | The form cannot be operated by the current application. | 482 483**Example** 484 485```ts 486import { formHost } from '@kit.FormKit'; 487import { BusinessError } from '@kit.BasicServicesKit'; 488 489try { 490 let formId: string = '12400633174999288'; 491 formHost.castToNormalForm(formId, (error: BusinessError) => { 492 if (error) { 493 console.error(`error, code: ${error.code}, message: ${error.message}`); 494 } 495 }); 496} catch(error) { 497 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 498} 499``` 500 501## castToNormalForm 502 503castToNormalForm(formId: string): Promise<void> 504 505Converts a temporary widget to a normal one. This API uses a promise to return the result. 506 507**Required permissions**: ohos.permission.REQUIRE_FORM 508 509**System capability**: SystemCapability.Ability.Form 510 511**Parameters** 512 513| Name| Type | Mandatory| Description | 514| ------ | ------ | ---- | ------- | 515| formId | string | Yes | Widget ID.| 516 517**Return value** 518 519| Type| Description| 520| -------- | -------- | 521| Promise<void> | Promise that returns no value.| 522 523**Error codes** 524 525For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 526 527| Error Code ID| Error Message| 528| -------- | -------- | 529| 201 | Permissions denied. | 530| 202 | The application is not a system application. | 531| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 532| 16500050 | IPC connection error. | 533| 16501000 | An internal functional error occurred. | 534| 16501001 | The ID of the form to be operated does not exist. | 535| 16501002 | The number of forms exceeds the maximum allowed. | 536| 16501003 | The form cannot be operated by the current application. | 537 538**Example** 539 540```ts 541import { formHost } from '@kit.FormKit'; 542import { BusinessError } from '@kit.BasicServicesKit'; 543 544try { 545 let formId: string = '12400633174999288'; 546 formHost.castToNormalForm(formId).then(() => { 547 console.log('formHost castTempForm success'); 548 }).catch((error: BusinessError) => { 549 console.error(`error, code: ${error.code}, message: ${error.message}`); 550 }); 551} catch(error) { 552 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 553} 554``` 555 556## notifyVisibleForms 557 558notifyVisibleForms(formIds: Array<string>, callback: AsyncCallback<void>): void 559 560Instructs 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. 561 562**Required permissions**: ohos.permission.REQUIRE_FORM 563 564**System capability**: SystemCapability.Ability.Form 565 566**Parameters** 567 568| Name| Type | Mandatory| Description | 569| ------ | ------ | ---- | ------- | 570| formIds | Array<string> | Yes | List of widget IDs. | 571| 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.| 572 573**Error codes** 574 575For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 576 577| Error Code ID| Error Message| 578| -------- | -------- | 579| 201 | Permissions denied. | 580| 202 | The application is not a system application. | 581| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 582| 16500050 | IPC connection error. | 583| 16500060 | Service connection error. | 584| 16501000 | An internal functional error occurred. | 585 586**Example** 587 588```ts 589import { formHost } from '@kit.FormKit'; 590import { BusinessError } from '@kit.BasicServicesKit'; 591 592try { 593 let formId: string[] = ['12400633174999288']; 594 formHost.notifyVisibleForms(formId, (error: BusinessError) => { 595 if (error) { 596 console.error(`error, code: ${error.code}, message: ${error.message}`); 597 } 598 }); 599} catch (error) { 600 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 601} 602``` 603 604## notifyVisibleForms 605 606notifyVisibleForms(formIds: Array<string>): Promise<void> 607 608Instructs 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. 609 610**Required permissions**: ohos.permission.REQUIRE_FORM 611 612**System capability**: SystemCapability.Ability.Form 613 614**Parameters** 615 616| Name| Type | Mandatory| Description | 617| ------ | ------ | ---- | ------- | 618| formIds | Array<string> | Yes | List of widget IDs.| 619 620**Return value** 621 622| Type| Description| 623| -------- | -------- | 624| Promise<void> | Promise that returns no value.| 625 626**Error codes** 627 628For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 629 630| Error Code ID| Error Message| 631| -------- | -------- | 632| 201 | Permissions denied. | 633| 202 | The application is not a system application. | 634| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 635| 16500050 | IPC connection error. | 636| 16500060 | Service connection error. | 637| 16501000 | An internal functional error occurred. | 638 639**Example** 640 641```ts 642import { formHost } from '@kit.FormKit'; 643import { BusinessError } from '@kit.BasicServicesKit'; 644 645try { 646 let formId: string[] = ['12400633174999288']; 647 formHost.notifyVisibleForms(formId).then(() => { 648 console.log('formHost notifyVisibleForms success'); 649 }).catch((error: BusinessError) => { 650 console.error(`error, code: ${error.code}, message: ${error.message}`); 651 }); 652} catch(error) { 653 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 654} 655``` 656 657## notifyInvisibleForms 658 659notifyInvisibleForms(formIds: Array<string>, callback: AsyncCallback<void>): void 660 661Instructs 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. 662 663**Required permissions**: ohos.permission.REQUIRE_FORM 664 665**System capability**: SystemCapability.Ability.Form 666 667**Parameters** 668 669| Name| Type | Mandatory| Description | 670| ------ | ------ | ---- | ------- | 671| formIds | Array<string> | Yes | List of widget IDs.| 672| 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.| 673 674**Error codes** 675 676For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 677 678| Error Code ID| Error Message| 679| -------- | -------- | 680| 201 | Permissions denied. | 681| 202 | The application is not a system application. | 682| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 683| 16500050 | IPC connection error. | 684| 16500060 | Service connection error. | 685| 16501000 | An internal functional error occurred. | 686 687**Example** 688 689```ts 690import { formHost } from '@kit.FormKit'; 691import { BusinessError } from '@kit.BasicServicesKit'; 692 693try { 694 let formId: string[] = ['12400633174999288']; 695 formHost.notifyInvisibleForms(formId, (error: BusinessError) => { 696 if (error) { 697 console.error(`error, code: ${error.code}, message: ${error.message}`); 698 } 699 }); 700} catch(error) { 701 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 702} 703``` 704 705## notifyInvisibleForms 706 707notifyInvisibleForms(formIds: Array<string>): Promise<void> 708 709Instructs 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. 710 711**Required permissions**: ohos.permission.REQUIRE_FORM 712 713**System capability**: SystemCapability.Ability.Form 714 715**Parameters** 716 717| Name| Type | Mandatory| Description | 718| ------ | ------ | ---- | ------- | 719| formIds | Array<string> | Yes | List of widget IDs.| 720 721**Return value** 722 723| Type| Description| 724| -------- | -------- | 725| Promise<void> | Promise that returns no value.| 726 727**Error codes** 728 729For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 730 731| Error Code ID| Error Message| 732| -------- | -------- | 733| 201 | Permissions denied. | 734| 202 | The application is not a system application. | 735| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 736| 16500050 | IPC connection error. | 737| 16500060 | Service connection error. | 738| 16501000 | An internal functional error occurred. | 739 740**Example** 741 742```ts 743import { formHost } from '@kit.FormKit'; 744import { BusinessError } from '@kit.BasicServicesKit'; 745 746try { 747 let formId: string[] = ['12400633174999288']; 748 formHost.notifyInvisibleForms(formId).then(() => { 749 console.log('formHost notifyInvisibleForms success'); 750 }).catch((error: BusinessError) => { 751 console.error(`error, code: ${error.code}, message: ${error.message}`); 752 }); 753} catch(error) { 754 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 755} 756``` 757 758## enableFormsUpdate 759 760enableFormsUpdate(formIds: Array<string>, callback: AsyncCallback<void>): void 761 762Instructs 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. 763 764**Required permissions**: ohos.permission.REQUIRE_FORM 765 766**System capability**: SystemCapability.Ability.Form 767 768**Parameters** 769 770| Name| Type | Mandatory| Description | 771| ------ | ------ | ---- | ------- | 772| formIds | Array<string> | Yes | List of widget IDs. | 773| 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.| 774 775**Error codes** 776 777For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 778 779| Error Code ID| Error Message| 780| -------- | -------- | 781| 201 | Permissions denied. | 782| 202 | The application is not a system application. | 783| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 784| 16500050 | IPC connection error. | 785| 16500060 | Service connection error. | 786| 16501000 | An internal functional error occurred. | 787| 16501003 | The form cannot be operated by the current application. | 788 789**Example** 790 791```ts 792import { formHost } from '@kit.FormKit'; 793import { BusinessError } from '@kit.BasicServicesKit'; 794 795try { 796 let formId: string[] = ['12400633174999288']; 797 formHost.enableFormsUpdate(formId, (error: BusinessError) => { 798 if (error) { 799 console.error(`error, code: ${error.code}, message: ${error.message}`); 800 } 801 }); 802} catch(error) { 803 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 804} 805``` 806 807## enableFormsUpdate 808 809enableFormsUpdate(formIds: Array<string>): Promise<void> 810 811Instructs 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. 812 813**Required permissions**: ohos.permission.REQUIRE_FORM 814 815**System capability**: SystemCapability.Ability.Form 816 817**Parameters** 818 819| Name| Type | Mandatory| Description | 820| ------ | ------ | ---- | ------- | 821| formIds | Array<string> | Yes | List of widget IDs.| 822 823**Return value** 824 825| Type| Description| 826| -------- | -------- | 827| Promise<void> | Promise that returns no value.| 828 829**Error codes** 830 831For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 832 833| Error Code ID| Error Message| 834| -------- | -------- | 835| 201 | Permissions denied. | 836| 202 | The application is not a system application. | 837| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 838| 16500050 | IPC connection error. | 839| 16500060 | Service connection error. | 840| 16501000 | An internal functional error occurred. | 841| 16501003 | The form cannot be operated by the current application. | 842 843**Example** 844 845```ts 846import { formHost } from '@kit.FormKit'; 847import { BusinessError } from '@kit.BasicServicesKit'; 848 849try { 850 let formId: string[] = ['12400633174999288']; 851 formHost.enableFormsUpdate(formId).then(() => { 852 console.log('formHost enableFormsUpdate success'); 853 }).catch((error: BusinessError) => { 854 console.error(`error, code: ${error.code}, message: ${error.message}`); 855 }); 856} catch(error) { 857 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 858} 859``` 860 861## disableFormsUpdate 862 863disableFormsUpdate(formIds: Array<string>, callback: AsyncCallback<void>): void 864 865Instructs 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. 866 867**Required permissions**: ohos.permission.REQUIRE_FORM 868 869**System capability**: SystemCapability.Ability.Form 870 871**Parameters** 872 873| Name| Type | Mandatory| Description | 874| ------ | ------ | ---- | ------- | 875| formIds | Array<string> | Yes | List of widget IDs. | 876| 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.| 877 878**Error codes** 879 880For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 881 882| Error Code ID| Error Message| 883| -------- | -------- | 884| 201 | Permissions denied. | 885| 202 | The application is not a system application. | 886| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 887| 16500050 | IPC connection error. | 888| 16500060 | Service connection error. | 889| 16501000 | An internal functional error occurred. | 890| 16501001 | The ID of the form to be operated does not exist. | 891| 16501003 | The form cannot be operated by the current application. | 892 893**Example** 894 895```ts 896import { formHost } from '@kit.FormKit'; 897import { BusinessError } from '@kit.BasicServicesKit'; 898 899try { 900 let formId: string[] = ['12400633174999288']; 901 formHost.disableFormsUpdate(formId, (error: BusinessError) => { 902 if (error) { 903 console.error(`error, code: ${error.code}, message: ${error.message}`); 904 } 905 }); 906} catch(error) { 907 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 908} 909``` 910 911## disableFormsUpdate 912 913disableFormsUpdate(formIds: Array<string>): Promise<void> 914 915Instructs 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. 916 917**Required permissions**: ohos.permission.REQUIRE_FORM 918 919**System capability**: SystemCapability.Ability.Form 920 921**Parameters** 922 923| Name| Type | Mandatory| Description | 924| ------ | ------ | ---- | ------- | 925| formIds | Array<string> | Yes | List of widget IDs.| 926 927**Return value** 928 929| Type| Description| 930| -------- | -------- | 931| Promise<void> | Promise that returns no value.| 932 933**Error codes** 934 935For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 936 937| Error Code ID| Error Message| 938| -------- | -------- | 939| 201 | Permissions denied. | 940| 202 | The application is not a system application. | 941| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 942| 16500050 | IPC connection error. | 943| 16500060 | Service connection error. | 944| 16501000 | An internal functional error occurred. | 945| 16501001 | The ID of the form to be operated does not exist. | 946| 16501003 | The form cannot be operated by the current application. | 947 948**Example** 949 950```ts 951import { formHost } from '@kit.FormKit'; 952import { BusinessError } from '@kit.BasicServicesKit'; 953 954try { 955 let formId: string[] = ['12400633174999288']; 956 formHost.disableFormsUpdate(formId).then(() => { 957 console.log('formHost disableFormsUpdate success'); 958 }).catch((error: BusinessError) => { 959 console.error(`error, code: ${error.code}, message: ${error.message}`); 960 }); 961} catch(error) { 962 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 963} 964``` 965 966## isSystemReady 967 968isSystemReady(callback: AsyncCallback<void>): void 969 970Checks whether the system is ready. This API uses an asynchronous callback to return the result. 971 972**System capability**: SystemCapability.Ability.Form 973 974**Parameters** 975 976| Name| Type | Mandatory| Description | 977| ------ | ------ | ---- | ------- | 978| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the check is successful, **error** is undefined; otherwise, **error** is an error object.| 979 980**Error codes** 981 982For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 983 984| Error Code ID| Error Message| 985| -------- | -------- | 986| 202 | The application is not a system application. | 987| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 988 989**Example** 990 991```ts 992import { formHost } from '@kit.FormKit'; 993import { BusinessError } from '@kit.BasicServicesKit'; 994 995try { 996 formHost.isSystemReady((error: BusinessError) => { 997 if (error) { 998 console.error(`error, code: ${error.code}, message: ${error.message}`); 999 } 1000 }); 1001} catch(error) { 1002 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 1003} 1004``` 1005 1006## isSystemReady 1007 1008isSystemReady(): Promise<void> 1009 1010Checks whether the system is ready. This API uses a promise to return the result. 1011 1012**System capability**: SystemCapability.Ability.Form 1013 1014**Return value** 1015 1016| Type| Description| 1017| -------- | -------- | 1018| Promise<void> | Promise that returns no value.| 1019 1020**Error codes** 1021 1022For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1023 1024| Error Code ID| Error Message| 1025| -------- | -------- | 1026| 202 | The application is not a system application. | 1027 1028**Example** 1029 1030```ts 1031import { formHost } from '@kit.FormKit'; 1032import { BusinessError } from '@kit.BasicServicesKit'; 1033 1034try { 1035 formHost.isSystemReady().then(() => { 1036 console.log('formHost isSystemReady success'); 1037 }).catch((error: BusinessError) => { 1038 console.error(`error, code: ${error.code}, message: ${error.message}`); 1039 }); 1040} catch(error) { 1041 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 1042} 1043``` 1044 1045## getAllFormsInfo 1046 1047getAllFormsInfo(callback: AsyncCallback<Array<formInfo.FormInfo>>): void 1048 1049Obtains the widget information provided by all applications on the device. This API uses an asynchronous callback to return the result. 1050 1051**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 1052 1053**System capability**: SystemCapability.Ability.Form 1054 1055**Parameters** 1056 1057| Name| Type | Mandatory| Description | 1058| ------ |----------------------------------------------------------------------------------------------| ---- | ------- | 1059| 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.| 1060 1061**Error codes** 1062 1063For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 1064 1065| Error Code ID| Error Message| 1066| -------- | -------- | 1067| 201 | Permissions denied. | 1068| 202 | The application is not a system application. | 1069| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1070| 16500050 | IPC connection error. | 1071| 16500060 | Service connection error. | 1072| 16501000 | An internal functional error occurred. | 1073 1074**Example** 1075 1076```ts 1077import { formHost, formInfo } from '@kit.FormKit'; 1078import { BusinessError } from '@kit.BasicServicesKit'; 1079 1080try { 1081 formHost.getAllFormsInfo((error: BusinessError, data: formInfo.FormInfo[]) => { 1082 if (error) { 1083 console.error(`error, code: ${error.code}, message: ${error.message}`); 1084 } else { 1085 console.log(`formHost getAllFormsInfo, data: ${JSON.stringify(data)}`); 1086 } 1087 }); 1088} catch(error) { 1089 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 1090} 1091``` 1092 1093## getAllFormsInfo 1094 1095getAllFormsInfo(): Promise<Array<formInfo.FormInfo>> 1096 1097Obtains the widget information provided by all applications on the device. This API uses a promise to return the result. 1098 1099**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 1100 1101**System capability**: SystemCapability.Ability.Form 1102 1103**Return value** 1104 1105| Type | Description | 1106|:---------------------------------------------------------------------------------------|:----------------------| 1107| Promise<Array<[formInfo.FormInfo](js-apis-app-form-formInfo.md#forminfo)>> | Promise used to return the information obtained.| 1108 1109**Error codes** 1110 1111For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 1112 1113| Error Code ID| Error Message| 1114| -------- | -------- | 1115| 201 | Permissions denied. | 1116| 202 | The application is not a system application. | 1117| 16500050 | IPC connection error. | 1118| 16500060 | Service connection error. | 1119| 16501000 | An internal functional error occurred. | 1120 1121**Example** 1122 1123```ts 1124import { formHost, formInfo } from '@kit.FormKit'; 1125import { BusinessError } from '@kit.BasicServicesKit'; 1126 1127try { 1128 formHost.getAllFormsInfo().then((data: formInfo.FormInfo[]) => { 1129 console.log(`formHost getAllFormsInfo data: ${JSON.stringify(data)}`); 1130 }).catch((error: BusinessError) => { 1131 console.error(`error, code: ${error.code}, message: ${error.message}`); 1132 }); 1133} catch(error) { 1134 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 1135} 1136``` 1137 1138## getFormsInfo 1139 1140getFormsInfo(bundleName: string, callback: AsyncCallback<Array<formInfo.FormInfo>>): void 1141 1142Obtains the widget information provided by a given application on the device. This API uses an asynchronous callback to return the result. 1143 1144**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 1145 1146**System capability**: SystemCapability.Ability.Form 1147 1148**Parameters** 1149 1150| Name| Type | Mandatory| Description | 1151| ------ |----------------------------------------------------------------------------------------------| ---- | ------- | 1152| bundleName | string | Yes| Bundle name of the application.| 1153| 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.| 1154 1155**Error codes** 1156 1157For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 1158 1159| Error Code ID| Error Message| 1160| -------- | -------- | 1161| 201 | Permissions denied. | 1162| 202 | The application is not a system application. | 1163| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1164| 16500050 | IPC connection error. | 1165| 16500060 | Service connection error. | 1166| 16500100 | Failed to obtain the configuration information. | 1167| 16501000 | An internal functional error occurred. | 1168 1169**Example** 1170 1171```ts 1172import { formHost, formInfo } from '@kit.FormKit'; 1173import { BusinessError } from '@kit.BasicServicesKit'; 1174 1175try { 1176 formHost.getFormsInfo('com.example.ohos.formjsdemo', (error: BusinessError, data: formInfo.FormInfo[]) => { 1177 if (error) { 1178 console.error(`error, code: ${error.code}, message: ${error.message}`); 1179 } else { 1180 console.log(`formHost getFormsInfo, data: ${JSON.stringify(data)}`); 1181 } 1182 }); 1183} catch(error) { 1184 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 1185} 1186``` 1187 1188## getFormsInfo 1189 1190getFormsInfo(bundleName: string, moduleName: string, callback: AsyncCallback<Array<formInfo.FormInfo>>): void 1191 1192Obtains the widget information provided by a given application on the device. This API uses an asynchronous callback to return the result. 1193 1194**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 1195 1196**System capability**: SystemCapability.Ability.Form 1197 1198**Parameters** 1199 1200| Name| Type | Mandatory| Description | 1201| ------ |----------------------------------------------------------------------------------------------| ---- | ------- | 1202| bundleName | string | Yes| Bundle name of the application.| 1203| moduleName | string | Yes| Module name.| 1204| 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.| 1205 1206**Error codes** 1207 1208For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 1209 1210| Error Code ID| Error Message| 1211| -------- | -------- | 1212| 201 | Permissions denied. | 1213| 202 | The application is not a system application. | 1214| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1215| 16500050 | IPC connection error. | 1216| 16500060 | Service connection error. | 1217| 16500100 | Failed to obtain the configuration information. | 1218| 16501000 | An internal functional error occurred. | 1219 1220**Example** 1221 1222```ts 1223import { formHost, formInfo } from '@kit.FormKit'; 1224import { BusinessError } from '@kit.BasicServicesKit'; 1225 1226try { 1227 formHost.getFormsInfo('com.example.ohos.formjsdemo', 'entry', (error: BusinessError, data: formInfo.FormInfo[]) => { 1228 if (error) { 1229 console.error(`error, code: ${error.code}, message: ${error.message}`); 1230 } else { 1231 console.log(`formHost getFormsInfo, data: ${JSON.stringify(data)}`); 1232 } 1233 }); 1234} catch(error) { 1235 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 1236} 1237``` 1238 1239## getFormsInfo 1240 1241getFormsInfo(bundleName: string, moduleName?: string): Promise<Array<formInfo.FormInfo>> 1242 1243Obtains the widget information provided by a given application on the device. This API uses a promise to return the result. 1244 1245**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 1246 1247**System capability**: SystemCapability.Ability.Form 1248 1249**Parameters** 1250 1251| Name| Type | Mandatory| Description | 1252| ------ | ------ | ---- | ------- | 1253| bundleName | string | Yes| Bundle name of the application.| 1254| moduleName | string | No| Module name. By default, no value is passed.| 1255 1256**Return value** 1257 1258| Type | Description | 1259|:---------------------------------------------------------------------------------------| :---------------------------------- | 1260| Promise<Array<[formInfo.FormInfo](js-apis-app-form-formInfo.md#forminfo)>> | Promise used to return the information obtained.| 1261 1262**Error codes** 1263 1264For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 1265 1266| Error Code ID| Error Message| 1267| -------- | -------- | 1268| 201 | Permissions denied. | 1269| 202 | The application is not a system application. | 1270| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1271| 16500050 | IPC connection error. | 1272| 16500060 | Service connection error. | 1273| 16500100 | Failed to obtain the configuration information. | 1274| 16501000 | An internal functional error occurred. | 1275 1276**Example** 1277 1278```ts 1279import { formHost, formInfo } from '@kit.FormKit'; 1280import { BusinessError } from '@kit.BasicServicesKit'; 1281 1282try { 1283 formHost.getFormsInfo('com.example.ohos.formjsdemo', 'entry').then((data: formInfo.FormInfo[]) => { 1284 console.log(`formHost getFormsInfo, data: ${JSON.stringify(data)}`); 1285 }).catch((error: BusinessError) => { 1286 console.error(`error, code: ${error.code}, message: ${error.message}`); 1287 }); 1288} catch(error) { 1289 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 1290} 1291``` 1292 1293## getFormsInfo<sup>12+</sup> 1294 1295getFormsInfo(filter: formInfo.FormInfoFilter): Promise<Array<formInfo.FormInfo>> 1296 1297Obtains the widget information provided by a given application on the device. This API uses a promise to return the result. 1298 1299**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 1300 1301**System capability**: SystemCapability.Ability.Form 1302 1303**Parameters** 1304 1305| Name| Type | Mandatory| Description | 1306| ------ | ------ | ---- | ------- | 1307| filter | [formInfo.FormInfoFilter](js-apis-app-form-formInfo.md#forminfofilter) | Yes| Filter criterion.| 1308 1309**Return value** 1310 1311| Type | Description | 1312| :------------ | :---------------------------------- | 1313| Promise<Array<[formInfo.FormInfo](js-apis-app-form-formInfo.md)>> | Promise used to return the information obtained.| 1314 1315**Error codes** 1316 1317For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 1318 1319| Error Code ID| Error Message| 1320| -------- | -------- | 1321| 201 | Permissions denied. | 1322| 202 | The application is not a system application. | 1323| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1324| 16500050 | IPC connection error. | 1325| 16500060 | Service connection error. | 1326| 16500100 | Failed to obtain the configuration information. | 1327| 16501000 | An internal functional error occurred. | 1328 1329**Example** 1330 1331```ts 1332import { formHost, formInfo } from '@kit.FormKit'; 1333import { BusinessError } from '@kit.BasicServicesKit'; 1334 1335const filter: formInfo.FormInfoFilter = { 1336 bundleName: 'ohos.samples.FormApplication', 1337 moduleName: 'entry', 1338 supportedDimensions: [FormDimension.Dimension_1_2, FormDimension.Dimension_2_2, FormDimension.Dimension_2_4] 1339}; 1340try { 1341 formHost.getFormsInfo(filter).then((data: formInfo.FormInfo[]) => { 1342 console.log(`formHost getFormsInfo, data: ${JSON.stringify(data)}`); 1343 }).catch((error: BusinessError) => { 1344 console.error(`promise error, code: ${error.code}, message: ${error.message})`); 1345 }); 1346} catch (error) { 1347 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`); 1348} 1349``` 1350 1351## deleteInvalidForms 1352 1353deleteInvalidForms(formIds: Array<string>, callback: AsyncCallback<number>): void 1354 1355Deletes invalid widgets from the list. This API uses an asynchronous callback to return the result. 1356 1357**Required permissions**: ohos.permission.REQUIRE_FORM 1358 1359**System capability**: SystemCapability.Ability.Form 1360 1361**Parameters** 1362 1363| Name| Type | Mandatory| Description | 1364| ------ | ------ | ---- | ------- | 1365| formIds | Array<string> | Yes | List of valid widget IDs.| 1366| 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.| 1367 1368**Error codes** 1369 1370For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 1371 1372| Error Code ID| Error Message| 1373| -------- | -------- | 1374| 201 | Permissions denied. | 1375| 202 | The application is not a system application. | 1376| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1377| 16500050 | IPC connection error. | 1378| 16500060 | Service connection error. | 1379| 16501000 | An internal functional error occurred. | 1380 1381**Example** 1382 1383```ts 1384import { formHost } from '@kit.FormKit'; 1385import { BusinessError } from '@kit.BasicServicesKit'; 1386 1387try { 1388 let formIds: string[] = new Array('12400633174999288', '12400633174999289'); 1389 formHost.deleteInvalidForms(formIds, (error: BusinessError, data: number) => { 1390 if (error) { 1391 console.error(`error, code: ${error.code}, message: ${error.message}`); 1392 } else { 1393 console.log(`formHost deleteInvalidForms, data: ${JSON.stringify(data)}`); 1394 } 1395 }); 1396} catch(error) { 1397 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 1398} 1399``` 1400 1401## deleteInvalidForms 1402 1403deleteInvalidForms(formIds: Array<string>): Promise<number> 1404 1405Deletes invalid widgets from the list. This API uses a promise to return the result. 1406 1407**Required permissions**: ohos.permission.REQUIRE_FORM 1408 1409**System capability**: SystemCapability.Ability.Form 1410 1411**Parameters** 1412 1413| Name| Type | Mandatory| Description | 1414| ------ | ------ | ---- | ------- | 1415| formIds | Array<string> | Yes | List of valid widget IDs.| 1416 1417**Return value** 1418 1419| Type | Description | 1420| :------------ | :---------------------------------- | 1421| Promise<number> | Promise used to return the number of widgets deleted.| 1422 1423**Error codes** 1424 1425For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 1426 1427| Error Code ID| Error Message| 1428| -------- | -------- | 1429| 201 | Permissions denied. | 1430| 202 | The application is not a system application. | 1431| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1432| 16500050 | IPC connection error. | 1433| 16500060 | Service connection error. | 1434| 16501000 | An internal functional error occurred. | 1435 1436**Example** 1437 1438```ts 1439import { formHost } from '@kit.FormKit'; 1440import { BusinessError } from '@kit.BasicServicesKit'; 1441 1442try { 1443 let formIds: string[] = new Array('12400633174999288', '12400633174999289'); 1444 formHost.deleteInvalidForms(formIds).then((data: number) => { 1445 console.log(`formHost deleteInvalidForms, data: ${JSON.stringify(data)}`); 1446 }).catch((error: BusinessError) => { 1447 console.error(`error, code: ${error.code}, message: ${error.message}`); 1448 }); 1449} catch(error) { 1450 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 1451} 1452``` 1453 1454## acquireFormState 1455 1456acquireFormState(want: Want, callback: AsyncCallback<formInfo.FormStateInfo>): void 1457 1458Obtains the widget state. This API uses an asynchronous callback to return the result. 1459 1460**Required permissions**: ohos.permission.REQUIRE_FORM and ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 1461 1462**System capability**: SystemCapability.Ability.Form 1463 1464**Parameters** 1465 1466| Name| Type | Mandatory| Description | 1467| ------ | ------ | ---- | ------- | 1468| want | [Want](../apis-ability-kit/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.| 1469| 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.| 1470 1471**Error codes** 1472 1473For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 1474 1475| Error Code ID| Error Message| 1476| -------- | -------- | 1477| 201 | Permissions denied. | 1478| 202 | The application is not a system application. | 1479| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1480| 16500050 | IPC connection error. | 1481| 16500060 | Service connection error. | 1482| 16500100 | Failed to obtain the configuration information. | 1483| 16501000 | An internal functional error occurred. | 1484 1485**Example** 1486 1487```ts 1488import { formHost, formInfo } from '@kit.FormKit'; 1489import { Want } from '@kit.AbilityKit'; 1490import { BusinessError } from '@kit.BasicServicesKit'; 1491 1492let want: Want = { 1493 'deviceId': '', 1494 'bundleName': 'ohos.samples.FormApplication', 1495 'abilityName': 'FormAbility', 1496 'parameters': { 1497 'ohos.extra.param.key.module_name': 'entry', 1498 'ohos.extra.param.key.form_name': 'widget', 1499 'ohos.extra.param.key.form_dimension': 2 1500 } 1501}; 1502try { 1503 formHost.acquireFormState(want, (error: BusinessError, data: formInfo.FormStateInfo) => { 1504 if (error) { 1505 console.error(`error, code: ${error.code}, message: ${error.message}`); 1506 } else { 1507 console.log(`formHost acquireFormState, data: ${JSON.stringify(data)}`); 1508 } 1509 }); 1510} catch (error) { 1511 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 1512} 1513``` 1514 1515## acquireFormState 1516 1517acquireFormState(want: Want): Promise<formInfo.FormStateInfo> 1518 1519Obtains the widget state. This API uses a promise to return the result. 1520 1521**Required permissions**: ohos.permission.REQUIRE_FORM and ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 1522 1523**System capability**: SystemCapability.Ability.Form 1524 1525**Parameters** 1526 1527| Name| Type | Mandatory| Description | 1528| ------ | ------ | ---- | ------- | 1529| want | [Want](../apis-ability-kit/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.| 1530 1531**Return value** 1532 1533| Type | Description | 1534| :------------ | :---------------------------------- | 1535| Promise<[formInfo.FormStateInfo](js-apis-app-form-formInfo.md#formstateinfo)> | Promise used to return the widget state obtained.| 1536 1537**Error codes** 1538 1539For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 1540 1541| Error Code ID| Error Message| 1542| -------- | -------- | 1543| 201 | Permissions denied. | 1544| 202 | The application is not a system application. | 1545| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1546| 16500050 | IPC connection error. | 1547| 16500060 | Service connection error. | 1548| 16500100 | Failed to obtain the configuration information. | 1549| 16501000 | An internal functional error occurred. | 1550 1551**Example** 1552 1553```ts 1554import { formHost, formInfo } from '@kit.FormKit'; 1555import { Want } from '@kit.AbilityKit'; 1556import { BusinessError } from '@kit.BasicServicesKit'; 1557 1558let want: Want = { 1559 'deviceId': '', 1560 'bundleName': 'ohos.samples.FormApplication', 1561 'abilityName': 'FormAbility', 1562 'parameters': { 1563 'ohos.extra.param.key.module_name': 'entry', 1564 'ohos.extra.param.key.form_name': 'widget', 1565 'ohos.extra.param.key.form_dimension': 2 1566 } 1567}; 1568try { 1569 formHost.acquireFormState(want).then((data: formInfo.FormStateInfo) => { 1570 console.log(`formHost acquireFormState, data: ${JSON.stringify(data)}`); 1571 }).catch((error: BusinessError) => { 1572 console.error(`error, code: ${error.code}, message: ${error.message}`); 1573 }); 1574} catch(error) { 1575 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 1576} 1577``` 1578 1579## on('formUninstall') 1580 1581on(type: 'formUninstall', callback: Callback<string>): void 1582 1583Subscribes to widget uninstall events. This API uses an asynchronous callback to return the result. 1584 1585> **NOTE** 1586> 1587> Widget uninstall is different from widget removal. When an application is uninstalled, the corresponding widget is automatically uninstalled. 1588 1589**System capability**: SystemCapability.Ability.Form 1590 1591**Parameters** 1592 1593| Name| Type | Mandatory| Description | 1594| ------ | ------ | ---- | ------- | 1595| type | string | Yes | Event type. The value **'formUninstall'** indicates a widget uninstall event.| 1596| callback | Callback<string> | Yes| Callback used to return the widget ID.| 1597 1598**Error codes** 1599 1600For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1601 1602| Error Code ID| Error Message| 1603| -------- | -------- | 1604| 202 | The application is not a system application. | 1605| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1606 1607**Example** 1608 1609```ts 1610import { formHost } from '@kit.FormKit'; 1611 1612formHost.on('formUninstall', (formId: string) => { 1613 console.log(`formHost on formUninstall, formId: ${formId}`); 1614}); 1615``` 1616 1617## off('formUninstall') 1618 1619off(type: 'formUninstall', callback?: Callback<string>): void 1620 1621Unsubscribes from widget uninstall events. This API uses an asynchronous callback to return the result. 1622 1623> **NOTE** 1624> 1625> Widget uninstall is different from widget removal. When an application is uninstalled, the corresponding widget is automatically uninstalled. 1626 1627**System capability**: SystemCapability.Ability.Form 1628 1629**Parameters** 1630 1631| Name| Type | Mandatory| Description | 1632| ------ | ------ | ---- | ------- | 1633| type | string | Yes | Event type. The value **'formUninstall'** indicates a widget uninstall event.| 1634| 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')**.| 1635 1636**Error codes** 1637 1638For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1639 1640| Error Code ID| Error Message| 1641| -------- | -------- | 1642| 202 | The application is not a system application. | 1643| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1644 1645**Example** 1646 1647```ts 1648import { formHost } from '@kit.FormKit'; 1649 1650formHost.off('formUninstall', (formId: string) => { 1651 console.log(`formHost on formUninstall, formId: ${formId}`); 1652}); 1653``` 1654 1655## notifyFormsVisible 1656 1657notifyFormsVisible(formIds: Array<string>, isVisible: boolean, callback: AsyncCallback<void>): void 1658 1659Instructs the widgets to make themselves visible. This API uses an asynchronous callback to return the result. 1660 1661**Required permissions**: ohos.permission.REQUIRE_FORM 1662 1663**System capability**: SystemCapability.Ability.Form 1664 1665**Parameters** 1666 1667| Name| Type | Mandatory| Description | 1668| ------ | ------ | ---- | ------- | 1669| formIds | Array<string> | Yes | List of widget IDs.| 1670| isVisible | boolean | Yes | Whether the widget is visible.<br>**true**: The widget is visible.<br>**false**: The widget is invisible.| 1671| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the notification is sent, **error** is undefined; otherwise, **error** is an error object.| 1672 1673**Error codes** 1674 1675For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 1676 1677| Error Code ID| Error Message| 1678| -------- | -------- | 1679| 201 | Permissions denied. | 1680| 202 | The application is not a system application. | 1681| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1682| 16500050 | IPC connection error. | 1683| 16500060 | Service connection error. | 1684| 16501000 | An internal functional error occurred. | 1685| 16501003 | The form cannot be operated by the current application. | 1686 1687**Example** 1688 1689```ts 1690import { formHost } from '@kit.FormKit'; 1691import { BusinessError } from '@kit.BasicServicesKit'; 1692 1693let formIds: string[] = new Array('12400633174999288', '12400633174999289'); 1694try { 1695 formHost.notifyFormsVisible(formIds, true, (error: BusinessError) => { 1696 if (error) { 1697 console.error(`error, code: ${error.code}, message: ${error.message}`); 1698 } 1699 }); 1700} catch (error) { 1701 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 1702} 1703``` 1704 1705## notifyFormsVisible 1706 1707notifyFormsVisible(formIds: Array<string>, isVisible: boolean): Promise<void> 1708 1709Instructs the widgets to make themselves visible. This API uses a promise to return the result. 1710 1711**Required permissions**: ohos.permission.REQUIRE_FORM 1712 1713**System capability**: SystemCapability.Ability.Form 1714 1715**Parameters** 1716 1717| Name| Type | Mandatory| Description | 1718| ------ | ------ | ---- | ------- | 1719| formIds | Array<string> | Yes | List of widget IDs.| 1720| isVisible | boolean | Yes | Whether the widget is visible.<br>**true**: The widget is visible.<br>**false**: The widget is invisible.| 1721 1722**Return value** 1723 1724| Type| Description| 1725| -------- | -------- | 1726| Promise<void> | Promise that returns no value.| 1727 1728**Error codes** 1729 1730For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 1731 1732| Error Code ID| Error Message| 1733| -------- | -------- | 1734| 201 | Permissions denied. | 1735| 202 | The application is not a system application. | 1736| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1737| 16500050 | IPC connection error. | 1738| 16500060 | Service connection error. | 1739| 16501000 | An internal functional error occurred. | 1740| 16501003 | The form cannot be operated by the current application. | 1741 1742**Example** 1743 1744```ts 1745import { formHost } from '@kit.FormKit'; 1746import { BusinessError } from '@kit.BasicServicesKit'; 1747 1748let formIds: string[] = new Array('12400633174999288', '12400633174999289'); 1749try { 1750 formHost.notifyFormsVisible(formIds, true).then(() => { 1751 console.log('formHost notifyFormsVisible success'); 1752 }).catch((error: BusinessError) => { 1753 console.error(`error, code: ${error.code}, message: ${error.message}`); 1754 }); 1755} catch(error) { 1756 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 1757} 1758``` 1759 1760## notifyFormsEnableUpdate 1761 1762notifyFormsEnableUpdate(formIds: Array<string>, isEnableUpdate: boolean, callback: AsyncCallback<void>): void 1763 1764Instructs the widgets to enable or disable updates. This API uses an asynchronous callback to return the result. 1765 1766**Required permissions**: ohos.permission.REQUIRE_FORM 1767 1768**System capability**: SystemCapability.Ability.Form 1769 1770**Parameters** 1771 1772| Name| Type | Mandatory| Description | 1773| ------ | ------ | ---- | ------- | 1774| formIds | Array<string> | Yes | List of widget IDs.| 1775| isEnableUpdate | boolean | Yes | Whether the widget can be updated.<br>**true**: The widget can be updated. **false**: The widget cannot be updated.| 1776| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the notification is sent, **error** is undefined; otherwise, **error** is an error object.| 1777 1778**Error codes** 1779 1780For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 1781 1782| Error Code ID| Error Message| 1783| -------- | -------- | 1784| 201 | Permissions denied. | 1785| 202 | The application is not a system application. | 1786| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1787| 16500050 | IPC connection error. | 1788| 16500060 | Service connection error. | 1789| 16501000 | An internal functional error occurred. | 1790| 16501003 | The form cannot be operated by the current application. | 1791 1792**Example** 1793 1794```ts 1795import { formHost } from '@kit.FormKit'; 1796import { BusinessError } from '@kit.BasicServicesKit'; 1797 1798let formIds: string[] = new Array('12400633174999288', '12400633174999289'); 1799try { 1800 formHost.notifyFormsEnableUpdate(formIds, true, (error: BusinessError) => { 1801 if (error) { 1802 console.error(`error, code: ${error.code}, message: ${error.message}`); 1803 } 1804 }); 1805} catch(error) { 1806 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 1807} 1808``` 1809 1810## notifyFormsEnableUpdate 1811 1812notifyFormsEnableUpdate(formIds: Array<string>, isEnableUpdate: boolean): Promise<void> 1813 1814Instructs the widgets to enable or disable updates. This API uses a promise to return the result. 1815 1816**Required permissions**: ohos.permission.REQUIRE_FORM 1817 1818**System capability**: SystemCapability.Ability.Form 1819 1820**Parameters** 1821 1822| Name| Type | Mandatory| Description | 1823| ------ | ------ | ---- | ------- | 1824| formIds | Array<string> | Yes | List of widget IDs.| 1825| isEnableUpdate | boolean | Yes | Whether the widget can be updated.<br>**true**: The widget can be updated.<br>**false**: The widget cannot be updated.| 1826 1827**Return value** 1828 1829| Type| Description| 1830| -------- | -------- | 1831| Promise<void> | Promise that returns no value.| 1832 1833**Error codes** 1834 1835For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 1836 1837| Error Code ID| Error Message| 1838| -------- | -------- | 1839| 201 | Permissions denied. | 1840| 202 | The application is not a system application. | 1841| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1842| 16500050 | IPC connection error. | 1843| 16500060 | Service connection error. | 1844| 16501000 | An internal functional error occurred. | 1845| 16501003 | The form cannot be operated by the current application. | 1846 1847**Example** 1848 1849```ts 1850import { formHost } from '@kit.FormKit'; 1851import { BusinessError } from '@kit.BasicServicesKit'; 1852 1853let formIds: string[] = new Array('12400633174999288', '12400633174999289'); 1854try { 1855 formHost.notifyFormsEnableUpdate(formIds, true).then(() => { 1856 console.log('formHost notifyFormsEnableUpdate success'); 1857 }).catch((error: BusinessError) => { 1858 console.error(`error, code: ${error.code}, message: ${error.message}`); 1859 }); 1860} catch(error) { 1861 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 1862} 1863``` 1864## shareForm 1865 1866shareForm(formId: string, deviceId: string, callback: AsyncCallback<void>): void 1867 1868Shares a specified widget with a remote device. This API uses an asynchronous callback to return the result. 1869 1870**Required permissions**: ohos.permission.REQUIRE_FORM and ohos.permission.DISTRIBUTED_DATASYNC 1871 1872**System capability**: SystemCapability.Ability.Form 1873 1874**Parameters** 1875 1876| Name| Type | Mandatory| Description | 1877| ------ | ------ | ---- | ------- | 1878| formId | string | Yes | Widget ID.| 1879| deviceId | string | Yes | Remote device ID.| 1880| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the widget is shared, **error** is undefined; otherwise, **error** is an error object.| 1881 1882**Error codes** 1883 1884For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 1885 1886| Error Code ID| Error Message| 1887| -------- | -------- | 1888| 201 | Permissions denied. | 1889| 202 | The application is not a system application. | 1890| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1891| 16500050 | IPC connection error. | 1892| 16501000 | An internal functional error occurred. | 1893| 16501001 | The ID of the form to be operated does not exist. | 1894| 16501003 | The form cannot be operated by the current application. | 1895 1896**Example** 1897 1898```ts 1899import { formHost } from '@kit.FormKit'; 1900import { BusinessError } from '@kit.BasicServicesKit'; 1901 1902let formId: string = '12400633174999288'; 1903let deviceId: string = 'EFC11C0C53628D8CC2F8CB5052477E130D075917034613B9884C55CD22B3DEF2'; 1904try { 1905 formHost.shareForm(formId, deviceId, (error: BusinessError) => { 1906 if (error) { 1907 console.error(`error, code: ${error.code}, message: ${error.message}`); 1908 } 1909 }); 1910} catch(error) { 1911 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 1912} 1913``` 1914 1915## shareForm 1916 1917shareForm(formId: string, deviceId: string): Promise<void> 1918 1919Shares a specified widget with a remote device. This API uses a promise to return the result. 1920 1921**Required permissions**: ohos.permission.REQUIRE_FORM and ohos.permission.DISTRIBUTED_DATASYNC 1922 1923**System capability**: SystemCapability.Ability.Form 1924 1925**Parameters** 1926 1927| Name| Type | Mandatory| Description | 1928| ------ | ------ | ---- | ------- | 1929| formId | string | Yes | Widget ID.| 1930| deviceId | string | Yes | Remote device ID.| 1931 1932**Return value** 1933 1934| Type| Description| 1935| -------- | -------- | 1936| Promise<void> | Promise that returns no value.| 1937 1938**Error codes** 1939 1940For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 1941 1942| Error Code ID| Error Message| 1943| -------- | -------- | 1944| 201 | Permissions denied. | 1945| 202 | The application is not a system application. | 1946| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1947| 16500050 | IPC connection error. | 1948| 16501000 | An internal functional error occurred. | 1949| 16501001 | The ID of the form to be operated does not exist. | 1950| 16501003 | The form cannot be operated by the current application. | 1951 1952**Example** 1953 1954```ts 1955import { formHost } from '@kit.FormKit'; 1956import { BusinessError } from '@kit.BasicServicesKit'; 1957 1958let formId: string = '12400633174999288'; 1959let deviceId: string = 'EFC11C0C53628D8CC2F8CB5052477E130D075917034613B9884C55CD22B3DEF2'; 1960try { 1961 formHost.shareForm(formId, deviceId).then(() => { 1962 console.log('formHost shareForm success'); 1963 }).catch((error: BusinessError) => { 1964 console.error(`error, code: ${error.code}, message: ${error.message}`); 1965 }); 1966} catch(error) { 1967 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 1968} 1969``` 1970 1971## notifyFormsPrivacyProtected 1972 1973notifyFormsPrivacyProtected(formIds: Array\<string>, isProtected: boolean, callback: AsyncCallback\<void>): void 1974 1975Notifies that the privacy protection status of the specified widgets changes. This API uses an asynchronous callback to return the result. 1976 1977**Required permissions**: ohos.permission.REQUIRE_FORM 1978 1979**System capability**: SystemCapability.Ability.Form 1980 1981**Parameters** 1982 1983| Name| Type | Mandatory| Description | 1984| ------ | ------ | ---- | ------- | 1985| formIds | Array\<string\> | Yes | ID of the widgets.| 1986| isProtected | boolean | Yes | Whether a widget requires privacy protection.<br>**true**: The widget requires privacy protection.<br>**false**: The widget does not require privacy protection.| 1987| 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.| 1988 1989**Error codes** 1990 1991For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 1992 1993| Error Code ID| Error Message| 1994| -------- | -------- | 1995| 201 | Permissions denied. | 1996| 202 | The application is not a system application. | 1997| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1998| 16500050 | IPC connection error. | 1999| 16500060 | Service connection error. | 2000| 16501000 | An internal functional error occurred. | 2001 2002**Example** 2003 2004```ts 2005import { formHost } from '@kit.FormKit'; 2006import { BusinessError } from '@kit.BasicServicesKit'; 2007 2008let formIds: string[] = new Array('12400633174999288', '12400633174999289'); 2009try { 2010 formHost.notifyFormsPrivacyProtected(formIds, true, (error: BusinessError) => { 2011 if (error) { 2012 console.error(`error, code: ${error.code}, message: ${error.message}`); 2013 } 2014 }); 2015} catch(error) { 2016 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 2017} 2018``` 2019 2020## notifyFormsPrivacyProtected 2021 2022notifyFormsPrivacyProtected(formIds: Array\<string\>, isProtected: boolean): Promise\<void\> 2023 2024Notifies that the privacy protection status of the specified widgets changes. This API uses a promise to return the result. 2025 2026**Required permissions**: ohos.permission.REQUIRE_FORM 2027 2028**System capability**: SystemCapability.Ability.Form 2029 2030**Parameters** 2031 2032| Name | Type | Mandatory| Description | 2033| ----------- | --------------- | ---- | -------------------------------- | 2034| formIds | Array\<string\> | Yes | ID of the widgets.| 2035| isProtected | boolean | Yes | Whether a widget requires privacy protection.<br>**true**: The widget requires privacy protection.<br>**false**: The widget does not require privacy protection.| 2036 2037**Return value** 2038 2039| Type | Description | 2040| ------------------- | ------------------------- | 2041| Promise<void> | Promise that returns no value.| 2042 2043**Error codes** 2044 2045For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 2046 2047| Error Code ID| Error Message| 2048| -------- | -------- | 2049| 201 | Permissions denied. | 2050| 202 | The application is not a system application. | 2051| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 2052| 16500050 | IPC connection error. | 2053| 16500060 | Service connection error. | 2054| 16501000 | An internal functional error occurred. | 2055 2056```ts 2057import { formHost } from '@kit.FormKit'; 2058import { BusinessError } from '@kit.BasicServicesKit'; 2059 2060let formIds: string[] = new Array('12400633174999288', '12400633174999289'); 2061try { 2062 formHost.notifyFormsPrivacyProtected(formIds, true).then(() => { 2063 console.log('formHost notifyFormsPrivacyProtected success'); 2064 }).catch((error: BusinessError) => { 2065 console.error(`error, code: ${error.code}, message: ${error.message}`); 2066 }); 2067} catch(error) { 2068 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 2069} 2070``` 2071 2072## acquireFormData<sup>10+</sup> 2073 2074acquireFormData(formId: string, callback: AsyncCallback\<Record\<string, Object>>): void 2075 2076Requests data from the widget provider. This API uses an asynchronous callback to return the result. 2077 2078**Model restriction**: This API can be used only in the stage model. 2079 2080**Required permissions**: ohos.permission.REQUIRE_FORM 2081 2082**System capability**: SystemCapability.Ability.Form 2083 2084**Parameters** 2085 2086| Name| Type | Mandatory| Description | 2087| ------ | ------ | ---- | ------- | 2088| formId | string | Yes | Widget ID.| 2089| callback | AsyncCallback\<Record\<string, Object> | Yes | Callback used to return the API call result and the shared data.| 2090 2091**Error codes** 2092 2093For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 2094 2095| Error Code ID| Error Message| 2096| -------- | -------- | 2097| 201 | Permissions denied. | 2098| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 2099| 16500050 | IPC connection error. | 2100| 16500060 | Service connection error. | 2101| 16500100 | Failed to obtain the configuration information. | 2102| 16501000 | An internal functional error occurred. | 2103 2104**Example** 2105 2106```ts 2107import { formHost } from '@kit.FormKit'; 2108import { BusinessError } from '@kit.BasicServicesKit'; 2109 2110let formId: string = '12400633174999288'; 2111try { 2112 formHost.acquireFormData(formId, (error, data) => { 2113 if (error) { 2114 console.error(`error, code: ${error.code}, message: ${error.message}`); 2115 } else { 2116 console.log(`formHost acquireFormData, data: ${JSON.stringify(data)}`); 2117 } 2118 }); 2119} catch(error) { 2120 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 2121} 2122``` 2123 2124## acquireFormData<sup>10+</sup> 2125 2126acquireFormData(formId: string): Promise\<Record\<string, Object>> 2127 2128Requests data from the widget provider. This API uses a promise to return the result. 2129 2130**Model restriction**: This API can be used only in the stage model. 2131 2132**Required permissions**: ohos.permission.REQUIRE_FORM 2133 2134**System capability**: SystemCapability.Ability.Form 2135 2136**Parameters** 2137 2138| Name | Type | Mandatory| Description | 2139| ----------- | --------------- | ---- | -------------------------------- | 2140| formId | string | Yes | Widget ID.| 2141 2142**Return value** 2143 2144| Type | Description | 2145| ------------------- | ------------------------- | 2146| Promise\<Record\<string, Object>>| Promise used to return the API call result and the shared data.| 2147 2148**Error codes** 2149 2150For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 2151 2152| Error Code ID| Error Message| 2153| -------- | -------- | 2154| 201 | Permissions denied. | 2155| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 2156| 16500050 | IPC connection error. | 2157| 16500060 | Service connection error. | 2158| 16500100 | Failed to obtain the configuration information. | 2159| 16501000 | An internal functional error occurred. | 2160 2161**Example** 2162 2163```ts 2164import { formHost } from '@kit.FormKit'; 2165import { BusinessError } from '@kit.BasicServicesKit'; 2166 2167let formId: string = '12400633174999288'; 2168try { 2169 formHost.acquireFormData(formId).then((data) => { 2170 console.log('formHost acquireFormData success' + data); 2171 }).catch((error: BusinessError) => { 2172 console.error(`error, code: ${error.code}, message: ${error.message}`); 2173 }); 2174} catch (e) { 2175 console.error(`catch error, code: ${e.code}, message: ${e.message}`); 2176} 2177``` 2178 2179## setRouterProxy<sup>11+</sup> 2180 2181setRouterProxy(formIds: Array<string>, proxy: Callback<Want>, callback: AsyncCallback<void>): void 2182 2183Sets a router proxy for widgets and obtains the Want information required for redirection. This API uses an asynchronous callback to return the result. 2184 2185 2186 2187> **NOTE** 2188> 2189>- Generally, for a widget added to the home screen, in the case of router-based redirection, the widget framework checks whether the destination is proper and whether the widget has the redirection permission, and then triggers redirection accordingly. For a widget that is added to a widget host and has a router proxy configured, in the case of router-based redirection, the widget framework does not trigger redirection for the widget. Instead, it returns the **want** parameter containing the destination to the widget host. Therefore, if the widget host wants to use the Want information for redirection, it must have the application redirection permission. For details, see 2190[UIAbilityContext.startAbility()](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#startability). 2191> 2192>- Only one router proxy can be set for a widget. If multiple proxies are set, only the last proxy takes effect. 2193 2194**Required permissions**: ohos.permission.REQUIRE_FORM 2195 2196**System capability**: SystemCapability.Ability.Form 2197 2198**Parameters** 2199 2200| Name | Type | Mandatory| Description | 2201| -------- | ------------------------- | ---- | ------------------------------------------------------------ | 2202| formIds | Array<string> | Yes | Array of widget IDs. | 2203| proxy | Callback<Want> | Yes | Callback used to return the Want information required for redirection. | 2204| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the router proxy is set, **error** is **undefined**; otherwise, an exception is thrown.| 2205 2206**Error codes** 2207 2208For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 2209 2210| Error Code ID| Error Message | 2211| -------- | ------------------------------------------------------------ | 2212| 201 | Permissions denied. | 2213| 202 | The application is not a system application. | 2214| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 2215| 16500050 | IPC connection error. | 2216| 16500060 | Service connection error. | 2217| 16501000 | An internal functional error occurred. | 2218| 16501003 | The form cannot be operated by the current application. | 2219 2220**Example** 2221 2222```ts 2223import { common, Want } from '@kit.AbilityKit'; 2224import { formHost } from '@kit.FormKit'; 2225import { BusinessError } from '@kit.BasicServicesKit'; 2226 2227@Entry 2228@Component 2229struct CardExample { 2230 private context = this.getUIContext().getHostContext() as common.UIAbilityContext; 2231 @State formId: number = 0; 2232 @State fwidth: number = 420; 2233 @State fheight: number = 280; 2234 2235 build() { 2236 Column() { 2237 FormComponent({ 2238 id: this.formId, 2239 name: "widget", 2240 bundle: "com.example.cardprovider", 2241 ability: "EntryFormAbility", 2242 module: "entry", 2243 dimension: FormDimension.Dimension_2_2, 2244 temporary: false, 2245 }) 2246 .allowUpdate(true) 2247 .size({ width: this.fwidth, height: this.fheight }) 2248 .visibility(Visibility.Visible) 2249 .onAcquired((form) => { 2250 console.log(`testTag form info : ${JSON.stringify(form)}`); 2251 this.formId = form.id; 2252 try { 2253 let formIds: string[] = [this.formId.toString()]; 2254 formHost.setRouterProxy(formIds, (want: Want) => { 2255 console.info(`formHost recv router event, want: ${JSON.stringify(want)}`); 2256 // The widget host processes the redirection. 2257 this.context.startAbility(want, (err: BusinessError) => { 2258 console.info(`formHost startAbility error, code: ${err.code}, message: ${err.message}`); 2259 }); 2260 }, (err: BusinessError) => { 2261 console.error(`set router proxy error, code: ${err.code}, message: ${err.message}`); 2262 }) 2263 } catch (e) { 2264 console.log('formHost setRouterProxy catch exception: ' + JSON.stringify(e)); 2265 } 2266 }) 2267 } 2268 .width('100%') 2269 .height('100%') 2270 } 2271} 2272``` 2273 2274## setRouterProxy<sup>11+</sup> 2275 2276setRouterProxy(formIds: Array<string>, proxy: Callback<Want>): Promise<void> 2277 2278Sets a router proxy for widgets and obtains the Want information required for redirection. This API uses a promise to return the result. 2279 2280> **NOTE** 2281> 2282>- Generally, for a widget added to the home screen, in the case of router-based redirection, the widget framework checks whether the destination is proper and whether the widget has the redirection permission, and then triggers redirection accordingly. For a widget that is added to a widget host and has a router proxy configured, in the case of router-based redirection, the widget framework does not trigger redirection for the widget. Instead, it returns the **want** parameter containing the destination to the widget host. Therefore, if the widget host wants to use the Want information for redirection, it must have the application redirection permission. For details, see [UIAbilityContext.startAbility()](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md#startability). 2283> 2284>- Only one router proxy can be set for a widget. If multiple proxies are set, only the last proxy takes effect. 2285 2286 2287 2288**Required permissions**: ohos.permission.REQUIRE_FORM 2289 2290**System capability**: SystemCapability.Ability.Form 2291 2292**Parameters** 2293 2294| Name | Type | Mandatory| Description | 2295| ------- | -------------------- | ---- | ------------------------------------ | 2296| formIds | Array<string> | Yes | Array of widget IDs. | 2297| proxy | Callback<Want> | Yes | Callback used to return the Want information required for redirection.| 2298 2299**Return value** 2300 2301| Type | Description | 2302| ------------------- | ------------------------- | 2303| Promise<void> | Promise that returns no value.| 2304 2305**Error codes** 2306 2307For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 2308 2309| Error Code ID| Error Message | 2310| -------- | ------------------------------------------------------------ | 2311| 201 | Permissions denied. | 2312| 202 | The application is not a system application. | 2313| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 2314| 16500050 | IPC connection error. | 2315| 16500060 | Service connection error. | 2316| 16501000 | An internal functional error occurred. | 2317| 16501003 | The form cannot be operated by the current application. | 2318 2319**Example** 2320 2321```ts 2322import { formHost } from '@kit.FormKit'; 2323import { common, Want } from '@kit.AbilityKit'; 2324import { BusinessError } from '@kit.BasicServicesKit'; 2325 2326@Entry 2327@Component 2328struct CardExample { 2329 private context = this.getUIContext().getHostContext() as common.UIAbilityContext; 2330 @State formId: number = 0; 2331 @State fwidth: number = 420; 2332 @State fheight: number = 280; 2333 2334 build() { 2335 Column() { 2336 FormComponent({ 2337 id: this.formId, 2338 name: "widget", 2339 bundle: "com.example.cardprovider", 2340 ability: "EntryFormAbility", 2341 module: "entry", 2342 dimension: FormDimension.Dimension_2_2, 2343 temporary: false, 2344 }) 2345 .allowUpdate(true) 2346 .size({ width: this.fwidth, height: this.fheight }) 2347 .visibility(Visibility.Visible) 2348 .onAcquired((form) => { 2349 console.log(`testTag form info : ${JSON.stringify(form)}`); 2350 this.formId = form.id; 2351 try { 2352 let formIds: string[] = [this.formId.toString()]; 2353 formHost.setRouterProxy(formIds, (want: Want) => { 2354 console.info(`formHost recv router event, want: ${JSON.stringify(want)}`); 2355 // The widget host processes the redirection. 2356 this.context.startAbility(want, (err: BusinessError) => { 2357 console.info(`formHost startAbility error, code: ${err.code}, message: ${err.message}`); 2358 }); 2359 }).then(() => { 2360 console.info('formHost set router proxy success'); 2361 }).catch((err: BusinessError) => { 2362 console.error(`set router proxy error, code: ${err.code}, message: ${err.message}`); 2363 }) 2364 } catch (e) { 2365 console.log('formHost setRouterProxy catch exception: ' + JSON.stringify(e)); 2366 } 2367 }) 2368 } 2369 .width('100%') 2370 .height('100%') 2371 } 2372} 2373``` 2374 2375## clearRouterProxy<sup>11+</sup> 2376 2377clearRouterProxy(formIds:Array<string>, callback: AsyncCallback<void>): void 2378 2379Clears the router proxy set for widgets. This API uses an asynchronous callback to return the result. 2380 2381**Required permissions**: ohos.permission.REQUIRE_FORM 2382 2383**System capability**: SystemCapability.Ability.Form 2384 2385**Parameters** 2386 2387| Name | Type | Mandatory| Description | 2388| -------- | ------------------------- | ---- | ------------------------------------------------------------ | 2389| formIds | Array<string>; | Yes | Array of widget IDs. | 2390| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the router proxy is cleared, **error** is **undefined**; otherwise, an exception is thrown.| 2391 2392**Error codes** 2393 2394For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 2395 2396| Error Code ID| Error Message | 2397| -------- | ------------------------------------------------------------ | 2398| 201 | Permissions denied. | 2399| 202 | The application is not a system application. | 2400| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 2401| 16500050 | IPC connection error. | 2402| 16500060 | Service connection error. | 2403| 16501000 | An internal functional error occurred. | 2404| 16501003 | The form cannot be operated by the current application. | 2405 2406**Example** 2407 2408```ts 2409import { formHost } from '@kit.FormKit'; 2410import { BusinessError } from '@kit.BasicServicesKit'; 2411 2412try { 2413 let formIds: string[] = ['12400633174999288']; 2414 formHost.clearRouterProxy(formIds, (err: BusinessError) => { 2415 if (err) { 2416 console.error(`formHost clear router proxy error, code: ${err.code}, message: ${err.message}`); 2417 } 2418 }); 2419} catch (error) { 2420 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 2421} 2422``` 2423 2424## clearRouterProxy<sup>11+</sup> 2425 2426clearRouterProxy(formIds:Array<string>): Promise<void> 2427 2428Clears the router proxy set for widgets. This API uses a promise to return the result. 2429 2430**Required permissions**: ohos.permission.REQUIRE_FORM 2431 2432**System capability**: SystemCapability.Ability.Form 2433 2434**Parameters** 2435 2436| Name | Type | Mandatory| Description | 2437| ------- | ------------------- | ---- | -------------- | 2438| formIds | Array<string> | Yes | Array of widget IDs.| 2439 2440**Return value** 2441 2442| Type | Description | 2443| ------------------- | ------------------------- | 2444| Promise<void> | Promise that returns no value.| 2445 2446**Error codes** 2447 2448For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 2449 2450| Error Code ID| Error Message | 2451| -------- | ------------------------------------------------------------ | 2452| 201 | Permissions denied. | 2453| 202 | The application is not a system application. | 2454| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 2455| 16500050 | IPC connection error. | 2456| 16500060 | Service connection error. | 2457| 16501000 | An internal functional error occurred. | 2458| 16501003 | The form cannot be operated by the current application. | 2459 2460**Example** 2461 2462```ts 2463import { formHost } from '@kit.FormKit'; 2464import { BusinessError } from '@kit.BasicServicesKit'; 2465 2466try { 2467 let formIds: string[] = ['12400633174999288']; 2468 formHost.clearRouterProxy(formIds).then(() => { 2469 console.log('formHost clear rourter proxy success'); 2470 }).catch((err: BusinessError) => { 2471 console.error(`formHost clear router proxy error, code: ${err.code}, message: ${err.message}`); 2472 }); 2473} catch (error) { 2474 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 2475} 2476``` 2477## setFormsRecyclable<sup>11+</sup> 2478 2479setFormsRecyclable(formIds:Array<string>, callback: AsyncCallback<void>): void 2480 2481Sets widgets to be recyclable. This API uses an asynchronous callback to return the result. 2482 2483**Model restriction**: This API can be used only in the stage model. 2484 2485**Required permissions**: ohos.permission.REQUIRE_FORM 2486 2487**System capability**: SystemCapability.Ability.Form 2488 2489**Parameters** 2490 2491| Name | Type | Mandatory| Description | 2492| -------- | ------------------------- | ---- | ------------------------------------------------------------ | 2493| formIds | Array<string>; | Yes | Array of widget IDs. | 2494| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the widgets are set to be recyclable, **error** is **undefined**; otherwise, an exception is thrown.| 2495 2496**Error codes** 2497 2498For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 2499 2500| Error Code ID| Error Message | 2501| -------- | ------------------------------------------------------------ | 2502| 201 | Permissions denied. | 2503| 202 | The application is not a system application. | 2504| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 2505| 16500050 | IPC connection error. | 2506| 16500060 | Service connection error. | 2507| 16501000 | An internal functional error occurred. | 2508 2509**Example** 2510 2511```ts 2512import { formHost } from '@kit.FormKit'; 2513import { BusinessError } from '@kit.BasicServicesKit'; 2514 2515try { 2516 let formIds: string[] = ['12400633174999288']; 2517 formHost.setFormsRecyclable(formIds, (err: BusinessError) => { 2518 if (err) { 2519 console.error(`setFormsRecyclable error, code: ${err.code}, message: ${err.message}`); 2520 } 2521 }); 2522} catch (error) { 2523 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 2524} 2525``` 2526 2527## setFormsRecyclable<sup>11+</sup> 2528 2529setFormsRecyclable(formIds:Array<string>): Promise<void> 2530 2531Sets widgets to be recyclable. This API uses a promise to return the result. 2532 2533**Model restriction**: This API can be used only in the stage model. 2534 2535**Required permissions**: ohos.permission.REQUIRE_FORM 2536 2537**System capability**: SystemCapability.Ability.Form 2538 2539**Parameters** 2540 2541| Name | Type | Mandatory| Description | 2542| ------- | ------------------- | ---- | -------------- | 2543| formIds | Array<string> | Yes | Array of widget IDs.| 2544 2545**Return value** 2546 2547| Type | Description | 2548| ------------------- | ------------------------- | 2549| Promise<void> | Promise that returns no value.| 2550 2551**Error codes** 2552 2553For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 2554 2555| Error Code ID| Error Message | 2556| -------- | ------------------------------------------------------------ | 2557| 201 | Permissions denied. | 2558| 202 | The application is not a system application. | 2559| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 2560| 16500050 | IPC connection error. | 2561| 16500060 | Service connection error. | 2562| 16501000 | An internal functional error occurred. | 2563 2564**Example** 2565 2566```ts 2567import { formHost } from '@kit.FormKit'; 2568import { BusinessError } from '@kit.BasicServicesKit'; 2569 2570try { 2571 let formIds: string[] = ['12400633174999288']; 2572 formHost.setFormsRecyclable(formIds).then(() => { 2573 console.log('setFormsRecyclable success'); 2574 }).catch((err: BusinessError) => { 2575 console.error(`setFormsRecyclable error, code: ${err.code}, message: ${err.message}`); 2576 }); 2577} catch (error) { 2578 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 2579} 2580``` 2581## recoverForms<sup>11+</sup> 2582 2583recoverForms(formIds:Array<string>, callback: AsyncCallback<void>): void 2584 2585Recovers widgets. This API uses an asynchronous callback to return the result. 2586 2587**Model restriction**: This API can be used only in the stage model. 2588 2589**Required permissions**: ohos.permission.REQUIRE_FORM 2590 2591**System capability**: SystemCapability.Ability.Form 2592 2593**Parameters** 2594 2595| Name | Type | Mandatory| Description | 2596| -------- | ------------------------- | ---- | ------------------------------------------------------------ | 2597| formIds | Array<string>; | Yes | Array of widget IDs. | 2598| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the widgets are recovered, **error** is **undefined**; otherwise, an exception is thrown.| 2599 2600**Error codes** 2601 2602For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 2603 2604| Error Code ID| Error Message | 2605| -------- | ------------------------------------------------------------ | 2606| 201 | Permissions denied. | 2607| 202 | The application is not a system application. | 2608| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 2609| 16500050 | IPC connection error. | 2610| 16500060 | Service connection error. | 2611| 16501000 | An internal functional error occurred. | 2612 2613**Example** 2614 2615```ts 2616import { formHost } from '@kit.FormKit'; 2617import { BusinessError } from '@kit.BasicServicesKit'; 2618 2619try { 2620 let formIds: string[] = ['12400633174999288']; 2621 formHost.recoverForms(formIds, (err: BusinessError) => { 2622 if (err) { 2623 console.error(`recoverForms error, code: ${err.code}, message: ${err.message}`); 2624 } 2625 }); 2626} catch (error) { 2627 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 2628} 2629``` 2630## recoverForms<sup>11+</sup> 2631 2632recoverForms(formIds: Array<string>): Promise<void> 2633 2634Recovers recycled widgets and updates their status to non-recyclable, or updates the status of widgets to non-recyclable if the widgets are not recycled. This API uses a promise to return the result. 2635 2636**Model restriction**: This API can be used only in the stage model. 2637 2638**Required permissions**: ohos.permission.REQUIRE_FORM 2639 2640**System capability**: SystemCapability.Ability.Form 2641 2642**Parameters** 2643 2644| Name | Type | Mandatory| Description | 2645| ------- | ------------------- | ---- | -------------- | 2646| formIds | Array<string> | Yes | Array of widget IDs.| 2647 2648**Return value** 2649 2650| Type | Description | 2651| ------------------- | ------------------------- | 2652| Promise<void> | Promise that returns no value.| 2653 2654 2655**Error codes** 2656 2657For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 2658 2659| Error Code ID| Error Message | 2660| -------- | ------------------------------------------------------------ | 2661| 201 | Permissions denied. | 2662| 202 | The application is not a system application. | 2663| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 2664| 16500050 | IPC connection error. | 2665| 16500060 | Service connection error. | 2666| 16501000 | An internal functional error occurred. | 2667 2668**Example** 2669 2670```ts 2671import { formHost } from '@kit.FormKit'; 2672import { BusinessError } from '@kit.BasicServicesKit'; 2673 2674try { 2675 let formIds: string[] = ['12400633174999288']; 2676 formHost.recoverForms(formIds).then(() => { 2677 console.info('recover forms success'); 2678 }).catch((err: BusinessError) => { 2679 console.error(`formHost recover forms error, code: ${err.code}, message: ${err.message}`); 2680 }); 2681} catch (e) { 2682 console.info(`catch error, code: ${e.code}, message: ${e.message}`); 2683} 2684``` 2685## recycleForms<sup>12+</sup> 2686 2687recycleForms(formIds: Array<string>): Promise<void> 2688 2689Recycles widgets, that is, reclaiming widget memory. This API uses a promise to return the result. 2690 2691**Model restriction**: This API can be used only in the stage model. 2692 2693**Required permissions**: ohos.permission.REQUIRE_FORM 2694 2695**System capability**: SystemCapability.Ability.Form 2696 2697**Parameters** 2698 2699| Name | Type | Mandatory| Description | 2700| ------- | ------------------- | ---- | -------------- | 2701| formIds | Array<string> | Yes | Array of widget IDs.| 2702 2703**Return value** 2704 2705| Type | Description | 2706| ------------------- | ------------------------- | 2707| Promise<void> | Promise that returns no value.| 2708 2709 2710**Error codes** 2711 2712For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 2713 2714| Error Code ID| Error Message | 2715| -------- | ------------------------------------------------------------ | 2716| 201 | Permissions denied. | 2717| 202 | The application is not a system application. | 2718| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 2719| 16500050 | IPC connection error. | 2720| 16500060 | Service connection error. | 2721| 16501000 | An internal functional error occurred. | 2722 2723**Example** 2724 2725```ts 2726import { formHost } from '@kit.FormKit'; 2727import { BusinessError } from '@kit.BasicServicesKit'; 2728 2729try { 2730 let formIds: string[] = ['12400633174999288']; 2731 formHost.recycleForms(formIds).then(() => { 2732 console.info('recycle forms success'); 2733 }).catch((err: BusinessError) => { 2734 console.error(`formHost recycle forms error, code: ${err.code}, message: ${err.message}`); 2735 }); 2736} catch (e) { 2737 console.error(`catch error, code: ${e.code}, message: ${e.message}`); 2738} 2739``` 2740 2741## updateFormLocation<sup>12+</sup> 2742updateFormLocation(formId: string, location: formInfo.FormLocation): void; 2743 2744Updates the widget location. 2745 2746**Model restriction**: This API can be used only in the stage model. 2747 2748**Required permissions**: ohos.permission.REQUIRE_FORM 2749 2750**System capability**: SystemCapability.Ability.Form 2751 2752**Parameters** 2753 2754| Name| Type | Mandatory| Description | 2755| ------ | ------ | ---- | ------- | 2756| formId | string | Yes | Widget ID.| 2757| location |[formInfo.FormLocation](js-apis-app-form-formInfo-sys.md#formlocation12) | Yes| Widget location.| 2758 2759**Error codes** 2760 2761For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 2762 2763| Error Code ID| Error Message | 2764| -------- | ------------------------------------------------------------ | 2765| 201 | Permissions denied. | 2766| 202 | The application is not a system application. | 2767| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 2768| 16500050 | IPC connection error. | 2769| 16500060 | Service connection error. | 2770| 16501000 | An internal functional error occurred. | 2771| 16501001 | The ID of the form to be operated does not exist. | 2772| 16501003 | The form cannot be operated by the current application. | 2773 2774**Example** 2775 2776```ts 2777import { formHost, formInfo } from '@kit.FormKit'; 2778import { BusinessError } from '@kit.BasicServicesKit'; 2779 2780try { 2781 let formId: string = '12400633174999288'; 2782 formHost.updateFormLocation(formId, formInfo.FormLocation.SCREEN_LOCK); 2783} catch (error) { 2784 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 2785} 2786``` 2787 2788## setPublishFormResult<sup>12+</sup> 2789 2790setPublishFormResult(formId: string, result: formInfo.PublishFormResult): void; 2791 2792Sets the result for the operation of adding a widget to the home screen. 2793 2794**Model restriction**: This API can be used only in the stage model. 2795 2796**Required permissions**: ohos.permission.REQUIRE_FORM 2797 2798**System capability**: SystemCapability.Ability.Form 2799 2800**Parameters** 2801 2802| Name| Type | Mandatory| Description | 2803| ------ | ------------------------------------------------------------ | ---- | ------------------ | 2804| formId | string | Yes | Widget ID. | 2805| result | [formInfo.PublishFormResult](js-apis-app-form-formInfo-sys.md#publishformresult12) | Yes | Result of the operation.| 2806 2807**Error codes** 2808 2809For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 2810 2811| Error Code ID| Error Message | 2812| -------- | ------------------------------------------------------------ | 2813| 201 | Permissions denied. | 2814| 202 | The application is not a system application. | 2815| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 2816| 16500050 | IPC connection error. | 2817| 16500060 | Service connection error. | 2818| 16501000 | An internal functional error occurred. | 2819| 16501001 | The ID of the form to be operated does not exist. | 2820 2821**Example** 2822 2823```ts 2824import { formHost, formInfo } from '@kit.FormKit'; 2825import { BusinessError } from '@kit.BasicServicesKit'; 2826 2827try { 2828 let formId: string = '12400633174999288'; 2829 let res: formInfo.PublishFormResult = {code: formInfo.PublishFormErrorCode.SUCCESS, message: ''}; 2830 formHost.setPublishFormResult(formId, res); 2831} catch (error) { 2832 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 2833} 2834``` 2835 2836## updateFormLockedState<sup>18+</sup> 2837 2838updateFormLockedState(formId: string, isLocked: boolean): Promise<void> 2839 2840Notifies the update of the widget lock state. 2841 2842If an application is locked, its widget will also be locked and masked in a locked style. To use the widget, you need to enter the password set for the widget. 2843 2844**Model restriction**: This API can be used only in the stage model. 2845 2846**Required permissions**: ohos.permission.REQUIRE_FORM 2847 2848**System capability**: SystemCapability.Ability.Form 2849 2850**Parameters** 2851 2852| Name| Type| Mandatory| Description| 2853|-------|------|------|-----| 2854| formId | string | Yes| Widget ID.| 2855| isLocked | boolean | Yes| A Boolean value indicates whether a widget is in the locked state. The value **true** indicates that the widget is in the locked state, and the value **false** indicates the opposite.| 2856 2857**Return value** 2858| Type | Description | 2859| ------------------- | ------------------------- | 2860| Promise<void> | Promise that returns no value.| 2861 2862**Error codes** 2863 2864For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 2865 2866| Error Code ID| Error Message | 2867| -------- | ------------------------------------------------------------ | 2868| 201 | Permissions denied. | 2869| 202 | caller is not a system app. | 2870| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 2871| 16500050 | IPC connection error. | 2872| 16500060 | Service connection error. | 2873| 16501000 | An internal functional error occurred. | 2874| 16501001 | The ID of the form to be operated does not exist. | 2875| 16501003 | The form cannot be operated by the current application. | 2876 2877**Example** 2878 2879```ts 2880import { formHost } from '@kit.FormKit'; 2881import { BusinessError } from '@kit.BasicServicesKit'; 2882 2883let formId: string = '12400633174999288'; 2884let isLocked: boolean = true; 2885 2886try { 2887 formHost.updateFormLockedState(this.formId, this.isLocked).then(() => { 2888 console.log(`formHost updateFormLockedState success`); 2889 }); 2890} catch (error) { 2891 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 2892} 2893 2894``` 2895 2896## formHost.on('formOverflow')<sup>20+</sup> 2897 2898on(type: 'formOverflow', callback: Callback<formInfo.OverflowRequest>): void 2899 2900Subscribes to the interactive widget animation request event. 2901 2902**System capability**: SystemCapability.Ability.Form 2903 2904**System API**: This is a system API. 2905 2906**Parameters** 2907 2908| Name| Type | Mandatory| Description| 2909|----------|--------|---|---------------------------------------| 2910| type | string | Yes| Event type. Only **'formOverflow'** is supported, indicating the interactive widget animation request.| 2911| callback | Callback<[formInfo.OverflowRequest](js-apis-app-form-formInfo-sys.md#overflowrequest20)> | Yes| Callback used by the widget host to process the animation request.| 2912 2913**Error codes** 2914 2915For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 2916 2917| Error Code ID| Error Message | 2918|-------|-----------------------------------------------------------------------------------------------------------| 2919| 202 | The application is not a system application. | 2920 2921**Example** 2922 2923```ts 2924import { formHost, formInfo } from '@kit.FormKit'; 2925import { BusinessError } from '@kit.BasicServicesKit'; 2926 2927try { 2928 formHost.on('formOverflow', (request: formInfo.OverflowRequest) => { 2929 console.log(`formHost on formOverflow, formId is ${request.formId}`); 2930 }); 2931} catch (error) { 2932 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 2933} 2934``` 2935 2936## formHost.off('formOverflow')<sup>20+</sup> 2937 2938off(type: 'formOverflow', callback?: Callback<formInfo.OverflowRequest>): void 2939 2940Unsubscribes from the interactive widget animation request event. 2941 2942**System capability**: SystemCapability.Ability.Form 2943 2944**System API**: This is a system API. 2945 2946**Parameters** 2947 2948| Name| Type | Mandatory| Description | 2949| ------ | ------ |----|----------------------------------------| 2950| type | string | Yes | Event type. Only **'formOverflow'** is supported, indicating the interactive widget animation request.| 2951| callback |Callback<[formInfo.OverflowRequest](js-apis-app-form-formInfo-sys.md#overflowrequest20)> | No | Callback function, which corresponds to the subscribed interactive widget animation request. By default, all registered interactive widget animation request events are deregistered.| 2952 2953**Error codes** 2954 2955For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 2956 2957| Error Code ID| Error Message | 2958| --- |-----------------------------------------------------------------------------------------------------------| 2959| 202 | The application is not a system application. | 2960 2961**Example** 2962 2963```ts 2964import { formHost, formInfo } from '@kit.FormKit'; 2965import { BusinessError } from '@kit.BasicServicesKit'; 2966 2967try { 2968 formHost.off('formOverflow', (request: formInfo.OverflowRequest) => { 2969 console.log(`formHost off formOverflow, formId is ${request.formId}`); 2970 }); 2971} catch (error) { 2972 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 2973} 2974``` 2975 2976## formHost.on('changeSceneAnimationState')<sup>20+</sup> 2977 2978on(type: 'changeSceneAnimationState', callback: Callback<formInfo.ChangeSceneAnimationStateRequest>): void 2979 2980Subscribes to the event of switching the interactive widget state. An interactive widget can be in the active or inactive state. In the inactive state, the interactive widget is the same as a common widget. In the active state, the interactive widget can start the **LiveFormExtensionAbility** process developed by the widget host to implement interactive widget animations. 2981 2982**System capability**: SystemCapability.Ability.Form 2983 2984**System API**: This is a system API. 2985 2986**Parameters** 2987 2988| Name| Type | Mandatory| Description | 2989| ------ | ------ | ---- |------------------------------------------------------| 2990| type | string | Yes | Event type. The event **'changeSceneAnimationState'** is triggered when the interactive widget state is switched.| 2991| callback |Callback<[formInfo.ChangeSceneAnimationStateRequest](js-apis-app-form-formInfo-sys.md#changesceneanimationstaterequest20)> | Yes| Callback function, which is used by the widget host to process the state switching request.| 2992 2993**Error codes** 2994 2995For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 2996 2997| Error Code ID| Error Message | 2998|-------|-----------------------------------------------------------------------------------------------------------| 2999| 202 | The application is not a system application. | 3000 3001**Example** 3002 3003```ts 3004import { formHost, formInfo } from '@kit.FormKit'; 3005import { BusinessError } from '@kit.BasicServicesKit'; 3006 3007try { 3008 formHost.on('changeSceneAnimationState', (request: formInfo.ChangeSceneAnimationStateRequest): void => { 3009 console.log(`formHost on changeSceneAnimationState, formId is ${request.formId}`); 3010 }); 3011} catch (error) { 3012 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 3013} 3014``` 3015 3016## formHost.off('changeSceneAnimationState')<sup>20+</sup> 3017 3018off(type: 'changeSceneAnimationState', callback: Callback<formInfo.changeSceneAnimationState>): void 3019 3020Unsubscribes from the event of switching the interactive widget state. An interactive widget can be in the active or inactive state. In the inactive state, the interactive widget is the same as a common widget. In the active state, the interactive widget can start the **LiveFormExtensionAbility** process developed by the widget host to implement interactive widget animations. 3021 3022**System capability**: SystemCapability.Ability.Form 3023 3024**System API**: This is a system API. 3025 3026**Parameters** 3027 3028| Name| Type | Mandatory| Description | 3029| ------ | ------ |----| ------- | 3030| type | string | Yes | Event type. The event **'changeSceneAnimationState'** is triggered when the interactive widget state is switched.| 3031| callback |Callback<[formInfo.ChangeSceneAnimationStateRequest](js-apis-app-form-formInfo-sys.md#changesceneanimationstaterequest20)> | No | Callback function, which corresponds to the request for switching the state of a subscribed interactive widget. By default, all registered interactive widget state switching events are deregistered.| 3032 3033**Error codes** 3034 3035For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3036 3037| Error Code ID| Error Message| 3038| -------- | -------- | 3039| 202 | The application is not a system application. | 3040 3041**Example** 3042 3043```ts 3044import { formHost, formInfo } from '@kit.FormKit'; 3045import { BusinessError } from '@kit.BasicServicesKit'; 3046 3047try { 3048 formHost.off('changeSceneAnimationState', (request: formInfo.ChangeSceneAnimationStateRequest): void => { 3049 console.log(`formHost off changeSceneAnimationState, formId is ${request.formId}`); 3050 }); 3051} catch (error) { 3052 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 3053} 3054``` 3055 3056## formHost.on('getFormRect')<sup>20+</sup> 3057 3058on(type: 'getFormRect', callback: formInfo.GetFormRectInfoCallback): void 3059 3060Subscribes to the event of requesting widget position and dimension. 3061 3062**System capability**: SystemCapability.Ability.Form 3063 3064**System API**: This is a system API. 3065 3066**Parameters** 3067 3068| Name| Type | Mandatory| Description | 3069| ------ | ------ | ---- |------------------------------------------------------| 3070| type | string | Yes | Event callback type. The supported event is **'getFormRect'**, indicating requesting widget position and dimension.| 3071| callback |[formInfo.GetFormRectInfoCallback](js-apis-app-form-formInfo-sys.md#getformrectinfocallback20) | Yes| Callback function used by the widget host to process the request and return the position and dimension of the widget relative to the upper left corner of the screen. The unit is vp.| 3072 3073**Error codes** 3074 3075For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3076 3077| Error Code ID| Error Message | 3078|-------|-----------------------------------------------------------------------------------------------------------| 3079| 202 | The application is not a system application. | 3080 3081**Example** 3082 3083```ts 3084import { formHost, formInfo } from '@kit.FormKit'; 3085import { BusinessError } from '@kit.BasicServicesKit'; 3086 3087try { 3088 formHost.on('getFormRect', (formId: string): Promise<formInfo.Rect> => { 3089 // The widget host needs to process the request, and calculate and return the widget dimension and position information. 3090 return new Promise<formInfo.Rect>((resolve: Function) => { 3091 console.log(`formHost on getFormRect, formId is ${formId}`); 3092 let formRect: formInfo.Rect = {left: 0, top: 0, width: 0, height: 0}; 3093 resolve(formRect); 3094 }) 3095 }); 3096} catch (error) { 3097 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 3098} 3099``` 3100 3101## formHost.off('getFormRect')<sup>20+</sup> 3102 3103off(type: 'getFormRect', callback?: formInfo.GetFormRectInfoCallback): void 3104 3105Unsubscribes from the event of requesting widget position and dimension. 3106 3107**System capability**: SystemCapability.Ability.Form 3108 3109**System API**: This is a system API. 3110 3111**Parameters** 3112 3113| Name| Type | Mandatory| Description | 3114| ------ | ------ |----| ------- | 3115| type | string | Yes | Event callback type. The supported event is **'getFormRect'**, indicating requesting widget position and dimension.| 3116| callback |[formInfo.GetFormRectInfoCallback](js-apis-app-form-formInfo-sys.md#getformrectinfocallback20) | No | Callback function, corresponding to the subscribed widget position and dimension request. By default, all registered widget position and dimension request event callbacks are deregistered.| 3117 3118**Error codes** 3119 3120For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3121 3122| Error Code ID| Error Message| 3123| -------- | -------- | 3124| 202 | The application is not a system application. | 3125 3126**Example** 3127 3128```ts 3129import { formHost } from '@kit.FormKit'; 3130import { BusinessError } from '@kit.BasicServicesKit'; 3131 3132try { 3133 formHost.off('getFormRect'); 3134} catch (error) { 3135 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 3136} 3137``` 3138 3139## formHost.updateFormSize<sup>20+</sup> 3140 3141updateFormSize(formId: string, newDimension: formInfo.FormDimension, newRect: formInfo.Rect): void 3142 3143Updates the size of the widget. 3144 3145**Required permissions**: ohos.permission.REQUIRE_FORM 3146 3147**System capability**: SystemCapability.Ability.Form 3148 3149**System API**: This is a system API. 3150 3151**Parameters** 3152 3153| Name| Type | Mandatory| Description | 3154| ------ | ------ | ---- | ------- | 3155| formId | string | Yes | Widget ID.| 3156| newDimension | [formInfo.FormDimension](js-apis-app-form-formInfo.md#formdimension) | Yes| Widget dimension. For example, **Dimension_1_2** indicates a 1 x 2 widget.| 3157| newRect | [formInfo.Rect](js-apis-app-form-formInfo.md#rect20) | Yes| Widget position information, including the X and Y coordinates of the widget's top-left corner, as well as its width and height.| 3158 3159**Error codes** 3160 3161For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Form Error Codes](errorcode-form.md). 3162 3163| Error Code ID| Error Message| 3164| -------- | -------- | 3165| 201 | Permissions denied. | 3166| 202 | Permissions denied.Called by non-system application. | 3167| 16501000 | An internal functional error occurred. | 3168| 16501001 | The ID of the form to be operated does not exist. | 3169| 16501012 | The dimension parameter is incorrect. | 3170 3171**Example** 3172 3173```ts 3174import { formHost, formInfo } from '@kit.FormKit'; 3175import { BusinessError } from '@kit.BasicServicesKit'; 3176 3177try { 3178 let formId: string = '12400633174999288'; 3179 let newDimension = formInfo.FormDimension.Dimension_1_2; 3180 let newRect: formInfo.Rect = {left: 1, top: 2, width: 100, height: 100}; 3181 formHost.updateFormSize(formId, newDimension, newRect); 3182} catch (error) { 3183 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 3184} 3185``` 3186