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