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 35| Error Code ID | Error Message | 36| -------- | -------- | 37| 201 | Permissions denied. | 38| 202 | The application is not a system application. | 39| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 40| 16500050 | IPC connection error. | 41| 16500060 | Service connection error. | 42| 16501000 | An internal functional error occurred. | 43| 16501001 | The ID of the form to be operated does not exist. | 44| 16501003 | The form cannot be operated by the current application. | 45 46For details about the error codes, see [Form Error Codes](errorcode-form.md). 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 93| Error Code ID | Error Message | 94| -------- | -------- | 95| 201 | Permissions denied. | 96| 202 | The application is not a system application. | 97| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 98| 16500050 | IPC connection error. | 99| 16500060 | Service connection error. | 100| 16501000 | An internal functional error occurred. | 101| 16501001 | The ID of the form to be operated does not exist. | 102| 16501003 | The form cannot be operated by the current application. | 103 104For details about the error codes, see [Form Error Codes](errorcode-form.md). 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 143| Error Code ID | Error Message | 144| -------- | -------- | 145| 201 | Permissions denied. | 146| 202 | The application is not a system application. | 147| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 148| 16500050 | IPC connection error. | 149| 16500060 | Service connection error. | 150| 16501000 | An internal functional error occurred. | 151| 16501001 | The ID of the form to be operated does not exist. | 152| 16501003 | The form cannot be operated by the current application. | 153 154For details about the error codes, see [Form Error Codes](errorcode-form.md). 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 194| Error Code ID | Error Message | 195| -------- | -------- | 196| 201 | Permissions denied. | 197| 202 | The application is not a system application. | 198| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 199| 16500050 | IPC connection error. | 200| 16500060 | Service connection error. | 201| 16501000 | An internal functional error occurred. | 202| 16501001 | The ID of the form to be operated does not exist. | 203| 16501003 | The form cannot be operated by the current application. | 204 205For details about the error codes, see [Form Error Codes](errorcode-form.md). 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 250| Error Code ID | Error Message | 251| -------- | -------- | 252| 201 | Permissions denied. | 253| 202 | The application is not a system application. | 254| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 255| 16500050 | IPC connection error. | 256| 16500060 | Service connection error. | 257| 16501000 | An internal functional error occurred. | 258| 16501001 | The ID of the form to be operated does not exist. | 259| 16501003 | The form cannot be operated by the current application. | 260 261For details about the error codes, see [Form Error Codes](errorcode-form.md). 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 300| Error Code ID | Error Message | 301| -------- | -------- | 302| 201 | Permissions denied. | 303| 202 | The application is not a system application. | 304| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 305| 16500050 | IPC connection error. | 306| 16500060 | Service connection error. | 307| 16501000 | An internal functional error occurred. | 308| 16501001 | The ID of the form to be operated does not exist. | 309| 16501003 | The form cannot be operated by the current application. | 310 311For details about the error codes, see [Form Error Codes](errorcode-form.md). 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 355| Error Code ID | Error Message | 356| -------- | -------- | 357| 201 | Permissions denied. | 358| 202 | The application is not a system application. | 359| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 360| 16500050 | IPC connection error. | 361| 16500060 | Service connection error. | 362| 16501000 | An internal functional error occurred. | 363| 16501001 | The ID of the form to be operated does not exist. | 364| 16501003 | The form cannot be operated by the current application. | 365 366For details about the error codes, see [Form Error Codes](errorcode-form.md). 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 411| Error Code ID | Error Message | 412| -------- | -------- | 413| 201 | Permissions denied. | 414| 202 | The application is not a system application. | 415| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 416| 16500050 | IPC connection error. | 417| 16500060 | Service connection error. | 418| 16501000 | An internal functional error occurred. | 419| 16501001 | The ID of the form to be operated does not exist. | 420| 16501003 | The form cannot be operated by the current application. | 421 422For details about the error codes, see [Form Error Codes](errorcode-form.md). 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 464| Error Code ID | Error Message | 465| -------- | -------- | 466| 201 | Permissions denied. | 467| 202 | The application is not a system application. | 468| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 469| 16500050 | IPC connection error. | 470| 16501000 | An internal functional error occurred. | 471| 16501001 | The ID of the form to be operated does not exist. | 472| 16501002 | The number of forms exceeds the maximum allowed. | 473| 16501003 | The form cannot be operated by the current application. | 474 475For details about the error codes, see [Form Error Codes](errorcode-form.md). 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 519| Error Code ID | Error Message | 520| -------- | -------- | 521| 201 | Permissions denied. | 522| 202 | The application is not a system application. | 523| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 524| 16500050 | IPC connection error. | 525| 16501000 | An internal functional error occurred. | 526| 16501001 | The ID of the form to be operated does not exist. | 527| 16501002 | The number of forms exceeds the maximum allowed. | 528| 16501003 | The form cannot be operated by the current application. | 529 530For details about the error codes, see [Form Error Codes](errorcode-form.md). 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 569| Error Code ID | Error Message | 570| -------- | -------- | 571| 201 | Permissions denied. | 572| 202 | The application is not a system application. | 573| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 574| 16500050 | IPC connection error. | 575| 16500060 | Service connection error. | 576| 16501000 | An internal functional error occurred. | 577 578For details about the error codes, see [Form Error Codes](errorcode-form.md). 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 622| Error Code ID | Error Message | 623| -------- | -------- | 624| 201 | Permissions denied. | 625| 202 | The application is not a system application. | 626| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 627| 16500050 | IPC connection error. | 628| 16500060 | Service connection error. | 629| 16501000 | An internal functional error occurred. | 630 631For details about the error codes, see [Form Error Codes](errorcode-form.md). 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 670| Error Code ID | Error Message | 671| -------- | -------- | 672| 201 | Permissions denied. | 673| 202 | The application is not a system application. | 674| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 675| 16500050 | IPC connection error. | 676| 16500060 | Service connection error. | 677| 16501000 | An internal functional error occurred. | 678 679For details about the error codes, see [Form Error Codes](errorcode-form.md). 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 723| Error Code ID | Error Message | 724| -------- | -------- | 725| 201 | Permissions denied. | 726| 202 | The application is not a system application. | 727| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 728| 16500050 | IPC connection error. | 729| 16500060 | Service connection error. | 730| 16501000 | An internal functional error occurred. | 731 732For details about the error codes, see [Form Error Codes](errorcode-form.md). 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 771| Error Code ID | Error Message | 772| -------- | -------- | 773| 201 | Permissions denied. | 774| 202 | The application is not a system application. | 775| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 776| 16500050 | IPC connection error. | 777| 16500060 | Service connection error. | 778| 16501000 | An internal functional error occurred. | 779| 16501003 | The form cannot be operated by the current application. | 780 781For details about the error codes, see [Form Error Codes](errorcode-form.md). 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 825| Error Code ID | Error Message | 826| -------- | -------- | 827| 201 | Permissions denied. | 828| 202 | The application is not a system application. | 829| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 830| 16500050 | IPC connection error. | 831| 16500060 | Service connection error. | 832| 16501000 | An internal functional error occurred. | 833| 16501003 | The form cannot be operated by the current application. | 834 835For details about the error codes, see [Form Error Codes](errorcode-form.md). 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 874| Error Code ID | Error Message | 875| -------- | -------- | 876| 201 | Permissions denied. | 877| 202 | The application is not a system application. | 878| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 879| 16500050 | IPC connection error. | 880| 16500060 | Service connection error. | 881| 16501000 | An internal functional error occurred. | 882| 16501001 | The ID of the form to be operated does not exist. | 883| 16501003 | The form cannot be operated by the current application. | 884 885For details about the error codes, see [Form Error Codes](errorcode-form.md). 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 929| Error Code ID | Error Message | 930| -------- | -------- | 931| 201 | Permissions denied. | 932| 202 | The application is not a system application. | 933| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 934| 16500050 | IPC connection error. | 935| 16500060 | Service connection error. | 936| 16501000 | An internal functional error occurred. | 937| 16501001 | The ID of the form to be operated does not exist. | 938| 16501003 | The form cannot be operated by the current application. | 939 940For details about the error codes, see [Form Error Codes](errorcode-form.md). 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 976| Error Code ID | Error Message | 977| -------- | -------- | 978| 202 | The application is not a system application. | 979| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 980 981For details about the error codes, see [Form Error Codes](errorcode-form.md). 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 1016| Error Code ID | Error Message | 1017| -------- | -------- | 1018| 202 | The application is not a system application. | 1019 1020For details about the error codes, see [Form Error Codes](errorcode-form.md). 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 1057| Error Code ID | Error Message | 1058| -------- | -------- | 1059| 201 | Permissions denied. | 1060| 202 | The application is not a system application. | 1061| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1062| 16500050 | IPC connection error. | 1063| 16500060 | Service connection error. | 1064| 16501000 | An internal functional error occurred. | 1065 1066For details about the error codes, see [Form Error Codes](errorcode-form.md). 1067 1068 1069**Example** 1070 1071```ts 1072import { formHost, formInfo } from '@kit.FormKit'; 1073import { BusinessError } from '@kit.BasicServicesKit'; 1074 1075try { 1076 formHost.getAllFormsInfo((error: BusinessError, data: formInfo.FormInfo[]) => { 1077 if (error) { 1078 console.error(`error, code: ${error.code}, message: ${error.message}`); 1079 } else { 1080 console.log(`formHost getAllFormsInfo, data: ${JSON.stringify(data)}`); 1081 } 1082 }); 1083} catch(error) { 1084 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 1085} 1086``` 1087 1088## getAllFormsInfo 1089 1090getAllFormsInfo(): Promise<Array<formInfo.FormInfo>> 1091 1092Obtains the widget information provided by all applications on the device. This API uses a promise to return the result. 1093 1094**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 1095 1096**System capability**: SystemCapability.Ability.Form 1097 1098**Return value** 1099 1100| Type | Description | 1101|:---------------------------------------------------------------------------------------|:----------------------| 1102| Promise<Array<[formInfo.FormInfo](js-apis-app-form-formInfo.md#forminfo)>> | Promise used to return the information obtained. | 1103 1104**Error codes** 1105 1106| Error Code ID | Error Message | 1107| -------- | -------- | 1108| 201 | Permissions denied. | 1109| 202 | The application is not a system application. | 1110| 16500050 | IPC connection error. | 1111| 16500060 | Service connection error. | 1112| 16501000 | An internal functional error occurred. | 1113 1114For details about the error codes, see [Form Error Codes](errorcode-form.md). 1115 1116**Example** 1117 1118```ts 1119import { formHost, formInfo } from '@kit.FormKit'; 1120import { BusinessError } from '@kit.BasicServicesKit'; 1121 1122try { 1123 formHost.getAllFormsInfo().then((data: formInfo.FormInfo[]) => { 1124 console.log(`formHost getAllFormsInfo data: ${JSON.stringify(data)}`); 1125 }).catch((error: BusinessError) => { 1126 console.error(`error, code: ${error.code}, message: ${error.message}`); 1127 }); 1128} catch(error) { 1129 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 1130} 1131``` 1132 1133## getFormsInfo 1134 1135getFormsInfo(bundleName: string, callback: AsyncCallback<Array<formInfo.FormInfo>>): void 1136 1137Obtains the widget information provided by a given application on the device. This API uses an asynchronous callback to return the result. 1138 1139**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 1140 1141**System capability**: SystemCapability.Ability.Form 1142 1143**Parameters** 1144 1145| Name | Type | Mandatory | Description | 1146| ------ |----------------------------------------------------------------------------------------------| ---- | ------- | 1147| bundleName | string | Yes | Bundle name of the application. | 1148| 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. | 1149 1150**Error codes** 1151 1152| Error Code ID | Error Message | 1153| -------- | -------- | 1154| 201 | Permissions denied. | 1155| 202 | The application is not a system application. | 1156| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1157| 16500050 | IPC connection error. | 1158| 16500060 | Service connection error. | 1159| 16500100 | Failed to obtain the configuration information. | 1160| 16501000 | An internal functional error occurred. | 1161 1162For details about the error codes, see [Form Error Codes](errorcode-form.md). 1163 1164**Example** 1165 1166```ts 1167import { formHost, formInfo } from '@kit.FormKit'; 1168import { BusinessError } from '@kit.BasicServicesKit'; 1169 1170try { 1171 formHost.getFormsInfo('com.example.ohos.formjsdemo', (error: BusinessError, data: formInfo.FormInfo[]) => { 1172 if (error) { 1173 console.error(`error, code: ${error.code}, message: ${error.message}`); 1174 } else { 1175 console.log(`formHost getFormsInfo, data: ${JSON.stringify(data)}`); 1176 } 1177 }); 1178} catch(error) { 1179 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 1180} 1181``` 1182 1183## getFormsInfo 1184 1185getFormsInfo(bundleName: string, moduleName: string, callback: AsyncCallback<Array<formInfo.FormInfo>>): void 1186 1187Obtains the widget information provided by a given application on the device. This API uses an asynchronous callback to return the result. 1188 1189**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 1190 1191**System capability**: SystemCapability.Ability.Form 1192 1193**Parameters** 1194 1195| Name | Type | Mandatory | Description | 1196| ------ |----------------------------------------------------------------------------------------------| ---- | ------- | 1197| bundleName | string | Yes | Bundle name of the application. | 1198| moduleName | string | Yes | Module name. | 1199| 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. | 1200 1201**Error codes** 1202 1203| Error Code ID | Error Message | 1204| -------- | -------- | 1205| 201 | Permissions denied. | 1206| 202 | The application is not a system application. | 1207| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1208| 16500050 | IPC connection error. | 1209| 16500060 | Service connection error. | 1210| 16500100 | Failed to obtain the configuration information. | 1211| 16501000 | An internal functional error occurred. | 1212 1213For details about the error codes, see [Form Error Codes](errorcode-form.md). 1214 1215**Example** 1216 1217```ts 1218import { formHost, formInfo } from '@kit.FormKit'; 1219import { BusinessError } from '@kit.BasicServicesKit'; 1220 1221try { 1222 formHost.getFormsInfo('com.example.ohos.formjsdemo', 'entry', (error: BusinessError, data: formInfo.FormInfo[]) => { 1223 if (error) { 1224 console.error(`error, code: ${error.code}, message: ${error.message}`); 1225 } else { 1226 console.log(`formHost getFormsInfo, data: ${JSON.stringify(data)}`); 1227 } 1228 }); 1229} catch(error) { 1230 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 1231} 1232``` 1233 1234## getFormsInfo 1235 1236getFormsInfo(bundleName: string, moduleName?: string): Promise<Array<formInfo.FormInfo>> 1237 1238Obtains the widget information provided by a given application on the device. This API uses a promise to return the result. 1239 1240**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 1241 1242**System capability**: SystemCapability.Ability.Form 1243 1244**Parameters** 1245 1246| Name | Type | Mandatory | Description | 1247| ------ | ------ | ---- | ------- | 1248| bundleName | string | Yes | Bundle name of the application. | 1249| moduleName | string | No | Module name. By default, no value is passed. | 1250 1251**Return value** 1252 1253| Type | Description | 1254|:---------------------------------------------------------------------------------------| :---------------------------------- | 1255| Promise<Array<[formInfo.FormInfo](js-apis-app-form-formInfo.md#forminfo)>> | Promise used to return the information obtained. | 1256 1257**Error codes** 1258 1259| Error Code ID | Error Message | 1260| -------- | -------- | 1261| 201 | Permissions denied. | 1262| 202 | The application is not a system application. | 1263| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1264| 16500050 | IPC connection error. | 1265| 16500060 | Service connection error. | 1266| 16500100 | Failed to obtain the configuration information. | 1267| 16501000 | An internal functional error occurred. | 1268 1269For details about the error codes, see [Form Error Codes](errorcode-form.md). 1270 1271**Example** 1272 1273```ts 1274import { formHost, formInfo } from '@kit.FormKit'; 1275import { BusinessError } from '@kit.BasicServicesKit'; 1276 1277try { 1278 formHost.getFormsInfo('com.example.ohos.formjsdemo', 'entry').then((data: formInfo.FormInfo[]) => { 1279 console.log(`formHost getFormsInfo, data: ${JSON.stringify(data)}`); 1280 }).catch((error: BusinessError) => { 1281 console.error(`error, code: ${error.code}, message: ${error.message}`); 1282 }); 1283} catch(error) { 1284 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 1285} 1286``` 1287 1288## getFormsInfo<sup>12+</sup> 1289 1290getFormsInfo(filter: formInfo.FormInfoFilter): Promise<Array<formInfo.FormInfo>> 1291 1292Obtains the widget information provided by a given application on the device. This API uses a promise to return the result. 1293 1294**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 1295 1296**System capability**: SystemCapability.Ability.Form 1297 1298**Parameters** 1299 1300| Name | Type | Mandatory | Description | 1301| ------ | ------ | ---- | ------- | 1302| filter | [formInfo.FormInfoFilter](js-apis-app-form-formInfo.md#forminfofilter) | Yes | Filter criterion. | 1303 1304**Return value** 1305 1306| Type | Description | 1307| :------------ | :---------------------------------- | 1308| Promise<Array<[formInfo.FormInfo](js-apis-app-form-formInfo.md)>> | Promise used to return the information obtained. | 1309 1310**Error codes** 1311 1312| Error Code ID | Error Message | 1313| -------- | -------- | 1314| 201 | Permissions denied. | 1315| 202 | The application is not a system application. | 1316| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1317| 16500050 | IPC connection error. | 1318| 16500060 | Service connection error. | 1319| 16500100 | Failed to obtain the configuration information. | 1320| 16501000 | An internal functional error occurred. | 1321 1322For details about the error codes, see [Form Error Codes](errorcode-form.md). 1323 1324**Example** 1325 1326```ts 1327import { formHost, formInfo } from '@kit.FormKit'; 1328import { BusinessError } from '@kit.BasicServicesKit'; 1329 1330const filter: formInfo.FormInfoFilter = { 1331 bundleName: 'ohos.samples.FormApplication', 1332 moduleName: 'entry', 1333 supportedDimensions: [FormDimension.Dimension_1_2, FormDimension.Dimension_2_2, FormDimension.Dimension_2_4] 1334}; 1335try { 1336 formHost.getFormsInfo(filter).then((data: formInfo.FormInfo[]) => { 1337 console.log(`formHost getFormsInfo, data: ${JSON.stringify(data)}`); 1338 }).catch((error: BusinessError) => { 1339 console.error(`promise error, code: ${error.code}, message: ${error.message})`); 1340 }); 1341} catch (error) { 1342 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message})`); 1343} 1344``` 1345 1346## deleteInvalidForms 1347 1348deleteInvalidForms(formIds: Array<string>, callback: AsyncCallback<number>): void 1349 1350Deletes invalid widgets from the list. This API uses an asynchronous callback to return the result. 1351 1352**Required permissions**: ohos.permission.REQUIRE_FORM 1353 1354**System capability**: SystemCapability.Ability.Form 1355 1356**Parameters** 1357 1358| Name | Type | Mandatory | Description | 1359| ------ | ------ | ---- | ------- | 1360| formIds | Array<string> | Yes | List of valid widget IDs. | 1361| 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. | 1362 1363**Error codes** 1364 1365| Error Code ID | Error Message | 1366| -------- | -------- | 1367| 201 | Permissions denied. | 1368| 202 | The application is not a system application. | 1369| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1370| 16500050 | IPC connection error. | 1371| 16500060 | Service connection error. | 1372| 16501000 | An internal functional error occurred. | 1373 1374For details about the error codes, see [Form Error Codes](errorcode-form.md). 1375 1376**Example** 1377 1378```ts 1379import { formHost } from '@kit.FormKit'; 1380import { BusinessError } from '@kit.BasicServicesKit'; 1381 1382try { 1383 let formIds: string[] = new Array('12400633174999288', '12400633174999289'); 1384 formHost.deleteInvalidForms(formIds, (error: BusinessError, data: number) => { 1385 if (error) { 1386 console.error(`error, code: ${error.code}, message: ${error.message}`); 1387 } else { 1388 console.log(`formHost deleteInvalidForms, data: ${JSON.stringify(data)}`); 1389 } 1390 }); 1391} catch(error) { 1392 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 1393} 1394``` 1395 1396## deleteInvalidForms 1397 1398deleteInvalidForms(formIds: Array<string>): Promise<number> 1399 1400Deletes invalid widgets from the list. This API uses a promise to return the result. 1401 1402**Required permissions**: ohos.permission.REQUIRE_FORM 1403 1404**System capability**: SystemCapability.Ability.Form 1405 1406**Parameters** 1407 1408| Name | Type | Mandatory | Description | 1409| ------ | ------ | ---- | ------- | 1410| formIds | Array<string> | Yes | List of valid widget IDs. | 1411 1412**Return value** 1413 1414| Type | Description | 1415| :------------ | :---------------------------------- | 1416| Promise<number> | Promise used to return the number of widgets deleted. | 1417 1418**Error codes** 1419 1420| Error Code ID | Error Message | 1421| -------- | -------- | 1422| 201 | Permissions denied. | 1423| 202 | The application is not a system application. | 1424| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1425| 16500050 | IPC connection error. | 1426| 16500060 | Service connection error. | 1427| 16501000 | An internal functional error occurred. | 1428 1429For details about the error codes, see [Form Error Codes](errorcode-form.md). 1430 1431**Example** 1432 1433```ts 1434import { formHost } from '@kit.FormKit'; 1435import { BusinessError } from '@kit.BasicServicesKit'; 1436 1437try { 1438 let formIds: string[] = new Array('12400633174999288', '12400633174999289'); 1439 formHost.deleteInvalidForms(formIds).then((data: number) => { 1440 console.log(`formHost deleteInvalidForms, data: ${JSON.stringify(data)}`); 1441 }).catch((error: BusinessError) => { 1442 console.error(`error, code: ${error.code}, message: ${error.message}`); 1443 }); 1444} catch(error) { 1445 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 1446} 1447``` 1448 1449## acquireFormState 1450 1451acquireFormState(want: Want, callback: AsyncCallback<formInfo.FormStateInfo>): void 1452 1453Obtains the widget state. This API uses an asynchronous callback to return the result. 1454 1455**Required permissions**: ohos.permission.REQUIRE_FORM and ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 1456 1457**System capability**: SystemCapability.Ability.Form 1458 1459**Parameters** 1460 1461| Name | Type | Mandatory | Description | 1462| ------ | ------ | ---- | ------- | 1463| 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. | 1464| 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. | 1465 1466**Error codes** 1467 1468| Error Code ID | Error Message | 1469| -------- | -------- | 1470| 201 | Permissions denied. | 1471| 202 | The application is not a system application. | 1472| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1473| 16500050 | IPC connection error. | 1474| 16500060 | Service connection error. | 1475| 16500100 | Failed to obtain the configuration information. | 1476| 16501000 | An internal functional error occurred. | 1477 1478For details about the error codes, see [Form Error Codes](errorcode-form.md). 1479 1480**Example** 1481 1482```ts 1483import { formHost, formInfo } from '@kit.FormKit'; 1484import { Want } from '@kit.AbilityKit'; 1485import { BusinessError } from '@kit.BasicServicesKit'; 1486 1487let want: Want = { 1488 'deviceId': '', 1489 'bundleName': 'ohos.samples.FormApplication', 1490 'abilityName': 'FormAbility', 1491 'parameters': { 1492 'ohos.extra.param.key.module_name': 'entry', 1493 'ohos.extra.param.key.form_name': 'widget', 1494 'ohos.extra.param.key.form_dimension': 2 1495 } 1496}; 1497try { 1498 formHost.acquireFormState(want, (error: BusinessError, data: formInfo.FormStateInfo) => { 1499 if (error) { 1500 console.error(`error, code: ${error.code}, message: ${error.message}`); 1501 } else { 1502 console.log(`formHost acquireFormState, data: ${JSON.stringify(data)}`); 1503 } 1504 }); 1505} catch (error) { 1506 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 1507} 1508``` 1509 1510## acquireFormState 1511 1512acquireFormState(want: Want): Promise<formInfo.FormStateInfo> 1513 1514Obtains the widget state. This API uses a promise to return the result. 1515 1516**Required permissions**: ohos.permission.REQUIRE_FORM and ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 1517 1518**System capability**: SystemCapability.Ability.Form 1519 1520**Parameters** 1521 1522| Name | Type | Mandatory | Description | 1523| ------ | ------ | ---- | ------- | 1524| 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. | 1525 1526**Return value** 1527 1528| Type | Description | 1529| :------------ | :---------------------------------- | 1530| Promise<[formInfo.FormStateInfo](js-apis-app-form-formInfo.md#formstateinfo)> | Promise used to return the widget state obtained. | 1531 1532**Error codes** 1533 1534| Error Code ID | Error Message | 1535| -------- | -------- | 1536| 201 | Permissions denied. | 1537| 202 | The application is not a system application. | 1538| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1539| 16500050 | IPC connection error. | 1540| 16500060 | Service connection error. | 1541| 16500100 | Failed to obtain the configuration information. | 1542| 16501000 | An internal functional error occurred. | 1543 1544For details about the error codes, see [Form Error Codes](errorcode-form.md). 1545 1546**Example** 1547 1548```ts 1549import { formHost, formInfo } from '@kit.FormKit'; 1550import { Want } from '@kit.AbilityKit'; 1551import { BusinessError } from '@kit.BasicServicesKit'; 1552 1553let want: Want = { 1554 'deviceId': '', 1555 'bundleName': 'ohos.samples.FormApplication', 1556 'abilityName': 'FormAbility', 1557 'parameters': { 1558 'ohos.extra.param.key.module_name': 'entry', 1559 'ohos.extra.param.key.form_name': 'widget', 1560 'ohos.extra.param.key.form_dimension': 2 1561 } 1562}; 1563try { 1564 formHost.acquireFormState(want).then((data: formInfo.FormStateInfo) => { 1565 console.log(`formHost acquireFormState, data: ${JSON.stringify(data)}`); 1566 }).catch((error: BusinessError) => { 1567 console.error(`error, code: ${error.code}, message: ${error.message}`); 1568 }); 1569} catch(error) { 1570 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 1571} 1572``` 1573 1574## on('formUninstall') 1575 1576on(type: 'formUninstall', callback: Callback<string>): void 1577 1578Subscribes to widget uninstall events. This API uses an asynchronous callback to return the result. 1579 1580> **NOTE** 1581> 1582> Widget uninstall is different from widget removal. When an application is uninstalled, the corresponding widget is automatically uninstalled. 1583 1584**System capability**: SystemCapability.Ability.Form 1585 1586**Parameters** 1587 1588| Name | Type | Mandatory | Description | 1589| ------ | ------ | ---- | ------- | 1590| type | string | Yes | Event type. The value **'formUninstall'** indicates a widget uninstall event. | 1591| callback | Callback<string> | Yes | Callback used to return the widget ID. | 1592 1593**Error codes** 1594 1595| Error Code ID | Error Message | 1596| -------- | -------- | 1597| 202 | The application is not a system application. | 1598| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1599 1600For details about the error codes, see [Form Error Codes](errorcode-form.md). 1601 1602**Example** 1603 1604```ts 1605import { formHost } from '@kit.FormKit'; 1606 1607formHost.on('formUninstall', (formId: string) => { 1608 console.log(`formHost on formUninstall, formId: ${formId}`); 1609}); 1610``` 1611 1612## off('formUninstall') 1613 1614off(type: 'formUninstall', callback?: Callback<string>): void 1615 1616Unsubscribes from widget uninstall events. This API uses an asynchronous callback to return the result. 1617 1618> **NOTE** 1619> 1620> Widget uninstall is different from widget removal. When an application is uninstalled, the corresponding widget is automatically uninstalled. 1621 1622**System capability**: SystemCapability.Ability.Form 1623 1624**Parameters** 1625 1626| Name | Type | Mandatory | Description | 1627| ------ | ------ | ---- | ------- | 1628| type | string | Yes | Event type. The value **'formUninstall'** indicates a widget uninstall event. | 1629| 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')**.| 1630 1631**Error codes** 1632 1633| Error Code ID | Error Message | 1634| -------- | -------- | 1635| 202 | The application is not a system application. | 1636| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1637 1638For details about the error codes, see [Form Error Codes](errorcode-form.md). 1639 1640**Example** 1641 1642```ts 1643import { formHost } from '@kit.FormKit'; 1644 1645formHost.off('formUninstall', (formId: string) => { 1646 console.log(`formHost on formUninstall, formId: ${formId}`); 1647}); 1648``` 1649 1650## notifyFormsVisible 1651 1652notifyFormsVisible(formIds: Array<string>, isVisible: boolean, callback: AsyncCallback<void>): void 1653 1654Instructs the widgets to make themselves visible. This API uses an asynchronous callback to return the result. 1655 1656**Required permissions**: ohos.permission.REQUIRE_FORM 1657 1658**System capability**: SystemCapability.Ability.Form 1659 1660**Parameters** 1661 1662| Name | Type | Mandatory | Description | 1663| ------ | ------ | ---- | ------- | 1664| formIds | Array<string> | Yes | List of widget IDs. | 1665| isVisible | boolean | Yes | Whether to make the widgets visible. | 1666| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the notification is sent, **error** is undefined; otherwise, **error** is an error object. | 1667 1668**Error codes** 1669 1670| Error Code ID | Error Message | 1671| -------- | -------- | 1672| 201 | Permissions denied. | 1673| 202 | The application is not a system application. | 1674| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1675| 16500050 | IPC connection error. | 1676| 16500060 | Service connection error. | 1677| 16501000 | An internal functional error occurred. | 1678| 16501003 | The form cannot be operated by the current application. | 1679 1680For details about the error codes, see [Form Error Codes](errorcode-form.md). 1681 1682**Example** 1683 1684```ts 1685import { formHost } from '@kit.FormKit'; 1686import { BusinessError } from '@kit.BasicServicesKit'; 1687 1688let formIds: string[] = new Array('12400633174999288', '12400633174999289'); 1689try { 1690 formHost.notifyFormsVisible(formIds, true, (error: BusinessError) => { 1691 if (error) { 1692 console.error(`error, code: ${error.code}, message: ${error.message}`); 1693 } 1694 }); 1695} catch (error) { 1696 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 1697} 1698``` 1699 1700## notifyFormsVisible 1701 1702notifyFormsVisible(formIds: Array<string>, isVisible: boolean): Promise<void> 1703 1704Instructs the widgets to make themselves visible. This API uses a promise to return the result. 1705 1706**Required permissions**: ohos.permission.REQUIRE_FORM 1707 1708**System capability**: SystemCapability.Ability.Form 1709 1710**Parameters** 1711 1712| Name | Type | Mandatory | Description | 1713| ------ | ------ | ---- | ------- | 1714| formIds | Array<string> | Yes | List of widget IDs. | 1715| isVisible | boolean | Yes | Whether to make the widgets visible. | 1716 1717**Return value** 1718 1719| Type | Description | 1720| -------- | -------- | 1721| Promise<void> | Promise that returns no value. | 1722 1723**Error codes** 1724 1725| Error Code ID | Error Message | 1726| -------- | -------- | 1727| 201 | Permissions denied. | 1728| 202 | The application is not a system application. | 1729| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1730| 16500050 | IPC connection error. | 1731| 16500060 | Service connection error. | 1732| 16501000 | An internal functional error occurred. | 1733| 16501003 | The form cannot be operated by the current application. | 1734 1735For details about the error codes, see [Form Error Codes](errorcode-form.md). 1736 1737**Example** 1738 1739```ts 1740import { formHost } from '@kit.FormKit'; 1741import { BusinessError } from '@kit.BasicServicesKit'; 1742 1743let formIds: string[] = new Array('12400633174999288', '12400633174999289'); 1744try { 1745 formHost.notifyFormsVisible(formIds, true).then(() => { 1746 console.log('formHost notifyFormsVisible success'); 1747 }).catch((error: BusinessError) => { 1748 console.error(`error, code: ${error.code}, message: ${error.message}`); 1749 }); 1750} catch(error) { 1751 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 1752} 1753``` 1754 1755## notifyFormsEnableUpdate 1756 1757notifyFormsEnableUpdate(formIds: Array<string>, isEnableUpdate: boolean, callback: AsyncCallback<void>): void 1758 1759Instructs the widgets to enable or disable updates. This API uses an asynchronous callback to return the result. 1760 1761**Required permissions**: ohos.permission.REQUIRE_FORM 1762 1763**System capability**: SystemCapability.Ability.Form 1764 1765**Parameters** 1766 1767| Name | Type | Mandatory | Description | 1768| ------ | ------ | ---- | ------- | 1769| formIds | Array<string> | Yes | List of widget IDs. | 1770| isEnableUpdate | boolean | Yes | Whether to make the widgets updatable. | 1771| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the notification is sent, **error** is undefined; otherwise, **error** is an error object. | 1772 1773**Error codes** 1774 1775| Error Code ID | Error Message | 1776| -------- | -------- | 1777| 201 | Permissions denied. | 1778| 202 | The application is not a system application. | 1779| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1780| 16500050 | IPC connection error. | 1781| 16500060 | Service connection error. | 1782| 16501000 | An internal functional error occurred. | 1783| 16501003 | The form cannot be operated by the current application. | 1784 1785For details about the error codes, see [Form Error Codes](errorcode-form.md). 1786 1787**Example** 1788 1789```ts 1790import { formHost } from '@kit.FormKit'; 1791import { BusinessError } from '@kit.BasicServicesKit'; 1792 1793let formIds: string[] = new Array('12400633174999288', '12400633174999289'); 1794try { 1795 formHost.notifyFormsEnableUpdate(formIds, true, (error: BusinessError) => { 1796 if (error) { 1797 console.error(`error, code: ${error.code}, message: ${error.message}`); 1798 } 1799 }); 1800} catch(error) { 1801 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 1802} 1803``` 1804 1805## notifyFormsEnableUpdate 1806 1807notifyFormsEnableUpdate(formIds: Array<string>, isEnableUpdate: boolean): Promise<void> 1808 1809Instructs the widgets to enable or disable updates. This API uses a promise to return the result. 1810 1811**Required permissions**: ohos.permission.REQUIRE_FORM 1812 1813**System capability**: SystemCapability.Ability.Form 1814 1815**Parameters** 1816 1817| Name | Type | Mandatory | Description | 1818| ------ | ------ | ---- | ------- | 1819| formIds | Array<string> | Yes | List of widget IDs. | 1820| isEnableUpdate | boolean | Yes | Whether to make the widgets updatable. | 1821 1822**Return value** 1823 1824| Type | Description | 1825| -------- | -------- | 1826| Promise<void> | Promise that returns no value. | 1827 1828**Error codes** 1829 1830| Error Code ID | Error Message | 1831| -------- | -------- | 1832| 201 | Permissions denied. | 1833| 202 | The application is not a system application. | 1834| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1835| 16500050 | IPC connection error. | 1836| 16500060 | Service connection error. | 1837| 16501000 | An internal functional error occurred. | 1838| 16501003 | The form cannot be operated by the current application. | 1839 1840For details about the error codes, see [Form Error Codes](errorcode-form.md). 1841 1842**Example** 1843 1844```ts 1845import { formHost } from '@kit.FormKit'; 1846import { BusinessError } from '@kit.BasicServicesKit'; 1847 1848let formIds: string[] = new Array('12400633174999288', '12400633174999289'); 1849try { 1850 formHost.notifyFormsEnableUpdate(formIds, true).then(() => { 1851 console.log('formHost notifyFormsEnableUpdate success'); 1852 }).catch((error: BusinessError) => { 1853 console.error(`error, code: ${error.code}, message: ${error.message}`); 1854 }); 1855} catch(error) { 1856 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 1857} 1858``` 1859## shareForm 1860 1861shareForm(formId: string, deviceId: string, callback: AsyncCallback<void>): void 1862 1863Shares a specified widget with a remote device. This API uses an asynchronous callback to return the result. 1864 1865**Required permissions**: ohos.permission.REQUIRE_FORM and ohos.permission.DISTRIBUTED_DATASYNC 1866 1867**System capability**: SystemCapability.Ability.Form 1868 1869**Parameters** 1870 1871| Name | Type | Mandatory | Description | 1872| ------ | ------ | ---- | ------- | 1873| formId | string | Yes | Widget ID. | 1874| deviceId | string | Yes | Remote device ID. | 1875| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the widget is shared, **error** is undefined; otherwise, **error** is an error object. | 1876 1877**Error codes** 1878 1879| Error Code ID | Error Message | 1880| -------- | -------- | 1881| 201 | Permissions denied. | 1882| 202 | The application is not a system application. | 1883| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1884| 16500050 | IPC connection error. | 1885| 16501000 | An internal functional error occurred. | 1886| 16501001 | The ID of the form to be operated does not exist. | 1887| 16501003 | The form cannot be operated by the current application. | 1888 1889For details about the error codes, see [Form Error Codes](errorcode-form.md). 1890 1891**Example** 1892 1893```ts 1894import { formHost } from '@kit.FormKit'; 1895import { BusinessError } from '@kit.BasicServicesKit'; 1896 1897let formId: string = '12400633174999288'; 1898let deviceId: string = 'EFC11C0C53628D8CC2F8CB5052477E130D075917034613B9884C55CD22B3DEF2'; 1899try { 1900 formHost.shareForm(formId, deviceId, (error: BusinessError) => { 1901 if (error) { 1902 console.error(`error, code: ${error.code}, message: ${error.message}`); 1903 } 1904 }); 1905} catch(error) { 1906 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 1907} 1908``` 1909 1910## shareForm 1911 1912shareForm(formId: string, deviceId: string): Promise<void> 1913 1914Shares a specified widget with a remote device. This API uses a promise to return the result. 1915 1916**Required permissions**: ohos.permission.REQUIRE_FORM and ohos.permission.DISTRIBUTED_DATASYNC 1917 1918**System capability**: SystemCapability.Ability.Form 1919 1920**Parameters** 1921 1922| Name | Type | Mandatory | Description | 1923| ------ | ------ | ---- | ------- | 1924| formId | string | Yes | Widget ID. | 1925| deviceId | string | Yes | Remote device ID. | 1926 1927**Return value** 1928 1929| Type | Description | 1930| -------- | -------- | 1931| Promise<void> | Promise that returns no value. | 1932 1933**Error codes** 1934 1935| Error Code ID | Error Message | 1936| -------- | -------- | 1937| 201 | Permissions denied. | 1938| 202 | The application is not a system application. | 1939| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1940| 16500050 | IPC connection error. | 1941| 16501000 | An internal functional error occurred. | 1942| 16501001 | The ID of the form to be operated does not exist. | 1943| 16501003 | The form cannot be operated by the current application. | 1944 1945For details about the error codes, see [Form Error Codes](errorcode-form.md). 1946 1947**Example** 1948 1949```ts 1950import { formHost } from '@kit.FormKit'; 1951import { BusinessError } from '@kit.BasicServicesKit'; 1952 1953let formId: string = '12400633174999288'; 1954let deviceId: string = 'EFC11C0C53628D8CC2F8CB5052477E130D075917034613B9884C55CD22B3DEF2'; 1955try { 1956 formHost.shareForm(formId, deviceId).then(() => { 1957 console.log('formHost shareForm success'); 1958 }).catch((error: BusinessError) => { 1959 console.error(`error, code: ${error.code}, message: ${error.message}`); 1960 }); 1961} catch(error) { 1962 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 1963} 1964``` 1965 1966## notifyFormsPrivacyProtected 1967 1968notifyFormsPrivacyProtected(formIds: Array\<string>, isProtected: boolean, callback: AsyncCallback\<void>): void 1969 1970Notifies that the privacy protection status of the specified widgets changes. This API uses an asynchronous callback to return the result. 1971 1972**Required permissions**: ohos.permission.REQUIRE_FORM 1973 1974**System capability**: SystemCapability.Ability.Form 1975 1976**Parameters** 1977 1978| Name | Type | Mandatory | Description | 1979| ------ | ------ | ---- | ------- | 1980| formIds | Array\<string\> | Yes | ID of the widgets. | 1981| isProtected | boolean | Yes | Whether privacy protection is enabled. | 1982| 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. | 1983 1984**Error codes** 1985 1986| Error Code ID | Error Message | 1987| -------- | -------- | 1988| 201 | Permissions denied. | 1989| 202 | The application is not a system application. | 1990| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 1991| 16500050 | IPC connection error. | 1992| 16500060 | Service connection error. | 1993| 16501000 | An internal functional error occurred. | 1994 1995For details about the error codes, see [Form Error Codes](errorcode-form.md). 1996 1997**Example** 1998 1999```ts 2000import { formHost } from '@kit.FormKit'; 2001import { BusinessError } from '@kit.BasicServicesKit'; 2002 2003let formIds: string[] = new Array('12400633174999288', '12400633174999289'); 2004try { 2005 formHost.notifyFormsPrivacyProtected(formIds, true, (error: BusinessError) => { 2006 if (error) { 2007 console.error(`error, code: ${error.code}, message: ${error.message}`); 2008 } 2009 }); 2010} catch(error) { 2011 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 2012} 2013``` 2014 2015## notifyFormsPrivacyProtected 2016 2017notifyFormsPrivacyProtected(formIds: Array\<string\>, isProtected: boolean): Promise\<void\> 2018 2019Notifies that the privacy protection status of the specified widgets changes. This API uses a promise to return the result. 2020 2021**Required permissions**: ohos.permission.REQUIRE_FORM 2022 2023**System capability**: SystemCapability.Ability.Form 2024 2025**Parameters** 2026 2027| Name | Type | Mandatory | Description | 2028| ----------- | --------------- | ---- | -------------------------------- | 2029| formIds | Array\<string\> | Yes | ID of the widgets. | 2030| isProtected | boolean | Yes | Whether privacy protection is enabled. | 2031 2032**Return value** 2033 2034| Type | Description | 2035| ------------------- | ------------------------- | 2036| Promise<void> | Promise that returns no value. | 2037 2038**Error codes** 2039 2040| Error Code ID | Error Message | 2041| -------- | -------- | 2042| 201 | Permissions denied. | 2043| 202 | The application is not a system application. | 2044| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 2045| 16500050 | IPC connection error. | 2046| 16500060 | Service connection error. | 2047| 16501000 | An internal functional error occurred. | 2048 2049For details about the error codes, see [Form Error Codes](errorcode-form.md). 2050 2051```ts 2052import { formHost } from '@kit.FormKit'; 2053import { BusinessError } from '@kit.BasicServicesKit'; 2054 2055let formIds: string[] = new Array('12400633174999288', '12400633174999289'); 2056try { 2057 formHost.notifyFormsPrivacyProtected(formIds, true).then(() => { 2058 console.log('formHost notifyFormsPrivacyProtected success'); 2059 }).catch((error: BusinessError) => { 2060 console.error(`error, code: ${error.code}, message: ${error.message}`); 2061 }); 2062} catch(error) { 2063 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 2064} 2065``` 2066 2067## acquireFormData<sup>10+</sup> 2068 2069acquireFormData(formId: string, callback: AsyncCallback\<Record\<string, Object>>): void 2070 2071Requests data from the widget provider. This API uses an asynchronous callback to return the result. 2072 2073**Model restriction**: This API can be used only in the stage model. 2074 2075**Required permissions**: ohos.permission.REQUIRE_FORM 2076 2077**System capability**: SystemCapability.Ability.Form 2078 2079**Parameters** 2080 2081| Name | Type | Mandatory | Description | 2082| ------ | ------ | ---- | ------- | 2083| formId | string | Yes | Widget ID. | 2084| callback | AsyncCallback\<Record\<string, Object> | Yes | Callback used to return the API call result and the shared data. | 2085 2086**Error codes** 2087 2088| Error Code ID | Error Message | 2089| -------- | -------- | 2090| 201 | Permissions denied. | 2091| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 2092| 16500050 | IPC connection error. | 2093| 16500060 | Service connection error. | 2094| 16500100 | Failed to obtain the configuration information. | 2095| 16501000 | An internal functional error occurred. | 2096 2097For details about the error codes, see [Form Error Codes](errorcode-form.md). 2098 2099**Example** 2100 2101```ts 2102import { formHost } from '@kit.FormKit'; 2103import { BusinessError } from '@kit.BasicServicesKit'; 2104 2105let formId: string = '12400633174999288'; 2106try { 2107 formHost.acquireFormData(formId, (error, data) => { 2108 if (error) { 2109 console.error(`error, code: ${error.code}, message: ${error.message}`); 2110 } else { 2111 console.log(`formHost acquireFormData, data: ${JSON.stringify(data)}`); 2112 } 2113 }); 2114} catch(error) { 2115 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 2116} 2117``` 2118 2119## acquireFormData<sup>10+</sup> 2120 2121acquireFormData(formId: string): Promise\<Record\<string, Object>> 2122 2123Requests data from the widget provider. This API uses a promise to return the result. 2124 2125**Model restriction**: This API can be used only in the stage model. 2126 2127**Required permissions**: ohos.permission.REQUIRE_FORM 2128 2129**System capability**: SystemCapability.Ability.Form 2130 2131**Parameters** 2132 2133| Name | Type | Mandatory | Description | 2134| ----------- | --------------- | ---- | -------------------------------- | 2135| formId | string | Yes | Widget ID. | 2136 2137**Return value** 2138 2139| Type | Description | 2140| ------------------- | ------------------------- | 2141| Promise\<Record\<string, Object>>| Promise used to return the API call result and the shared data. | 2142 2143**Error codes** 2144 2145| Error Code ID | Error Message | 2146| -------- | -------- | 2147| 201 | Permissions denied. | 2148| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 2149| 16500050 | IPC connection error. | 2150| 16500060 | Service connection error. | 2151| 16500100 | Failed to obtain the configuration information. | 2152| 16501000 | An internal functional error occurred. | 2153 2154For details about the error codes, see [Form Error Codes](errorcode-form.md). 2155 2156```ts 2157import { formHost } from '@kit.FormKit'; 2158import { BusinessError } from '@kit.BasicServicesKit'; 2159 2160let formId: string = '12400633174999288'; 2161try { 2162 formHost.acquireFormData(formId).then((data) => { 2163 console.log('formHost acquireFormData success' + data); 2164 }).catch((error: BusinessError) => { 2165 console.error(`error, code: ${error.code}, message: ${error.message}`); 2166 }); 2167} catch(error) { 2168 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 2169} 2170``` 2171 2172## setRouterProxy<sup>11+</sup> 2173 2174setRouterProxy(formIds: Array<string>, proxy: Callback<Want>, callback: AsyncCallback<void>): void 2175 2176Sets a router proxy for widgets and obtains the Want information required for redirection. This API uses an asynchronous callback to return the result. 2177 2178> **NOTE** 2179> 2180>- 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). 2181> 2182>- Only one router proxy can be set for a widget. If multiple proxies are set, only the last proxy takes effect. 2183 2184**Required permissions**: ohos.permission.REQUIRE_FORM 2185 2186**System capability**: SystemCapability.Ability.Form 2187 2188**Parameters** 2189 2190| Name | Type | Mandatory | Description | 2191| -------- | ------------------------- | ---- | ------------------------------------------------------------ | 2192| formIds | Array<string> | Yes | Array of widget IDs. | 2193| proxy | Callback<Want> | Yes | Callback used to return the Want information required for redirection. | 2194| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the router proxy is set, **error** is **undefined**; otherwise, an exception is thrown. | 2195 2196**Error codes** 2197 2198| Error Code ID | Error Message | 2199| -------- | ------------------------------------------------------------ | 2200| 201 | Permissions denied. | 2201| 202 | The application is not a system application. | 2202| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 2203| 16500050 | IPC connection error. | 2204| 16500060 | Service connection error. | 2205| 16501000 | An internal functional error occurred. | 2206| 16501003 | The form cannot be operated by the current application. | 2207 2208For details about the error codes, see [Form Error Codes](errorcode-form.md). 2209 2210**Example** 2211 2212```ts 2213import { common, Want } from '@kit.AbilityKit'; 2214import { formHost } from '@kit.FormKit'; 2215import { BusinessError } from '@kit.BasicServicesKit'; 2216 2217@Entry 2218@Component 2219struct CardExample { 2220 private context = getContext(this) as common.UIAbilityContext; 2221 @State formId: number = 0; 2222 @State fwidth: number = 420; 2223 @State fheight: number = 280; 2224 2225 build() { 2226 Column() { 2227 FormComponent({ 2228 id: this.formId, 2229 name: "widget", 2230 bundle: "com.example.cardprovider", 2231 ability: "EntryFormAbility", 2232 module: "entry", 2233 dimension: FormDimension.Dimension_2_2, 2234 temporary: false, 2235 }) 2236 .allowUpdate(true) 2237 .size({ width: this.fwidth, height: this.fheight }) 2238 .visibility(Visibility.Visible) 2239 .onAcquired((form) => { 2240 console.log(`testTag form info : ${JSON.stringify(form)}`); 2241 this.formId = form.id; 2242 try { 2243 let formIds: string[] = [this.formId.toString()]; 2244 formHost.setRouterProxy(formIds, (want: Want) => { 2245 console.info(`formHost recv router event, want: ${JSON.stringify(want)}`); 2246 // The widget host processes the redirection. 2247 this.context.startAbility(want, (err: BusinessError) => { 2248 console.info(`formHost startAbility error, code: ${err.code}, message: ${err.message}`); 2249 }); 2250 }, (err: BusinessError) => { 2251 console.error(`set router proxy error, code: ${err.code}, message: ${err.message}`); 2252 }) 2253 } catch (e) { 2254 console.log('formHost setRouterProxy catch exception: ' + JSON.stringify(e)); 2255 } 2256 }) 2257 } 2258 .width('100%') 2259 .height('100%') 2260 } 2261} 2262``` 2263 2264## setRouterProxy<sup>11+</sup> 2265 2266setRouterProxy(formIds: Array<string>, proxy: Callback<Want>): Promise<void> 2267 2268Sets a router proxy for widgets and obtains the Want information required for redirection. This API uses a promise to return the result. 2269 2270> **NOTE** 2271> 2272>- 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). 2273> 2274>- Only one router proxy can be set for a widget. If multiple proxies are set, only the last proxy takes effect. 2275 2276 2277 2278**Required permissions**: ohos.permission.REQUIRE_FORM 2279 2280**System capability**: SystemCapability.Ability.Form 2281 2282**Parameters** 2283 2284| Name | Type | Mandatory | Description | 2285| ------- | -------------------- | ---- | ------------------------------------ | 2286| formIds | Array<string> | Yes | Array of widget IDs. | 2287| proxy | Callback<Want> | Yes | Callback used to return the Want information required for redirection. | 2288 2289**Return value** 2290 2291| Type | Description | 2292| ------------------- | ------------------------- | 2293| Promise<void> | Promise that returns no value. | 2294 2295**Error codes** 2296 2297| Error Code ID | Error Message | 2298| -------- | ------------------------------------------------------------ | 2299| 201 | Permissions denied. | 2300| 202 | The application is not a system application. | 2301| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 2302| 16500050 | IPC connection error. | 2303| 16500060 | Service connection error. | 2304| 16501000 | An internal functional error occurred. | 2305| 16501003 | The form cannot be operated by the current application. | 2306 2307For details about the error codes, see [Form Error Codes](errorcode-form.md). 2308 2309**Example** 2310 2311```ts 2312import { formHost } from '@kit.FormKit'; 2313import { common, Want } from '@kit.AbilityKit'; 2314import { BusinessError } from '@kit.BasicServicesKit'; 2315 2316@Entry 2317@Component 2318struct CardExample { 2319 private context = getContext(this) as common.UIAbilityContext; 2320 @State formId: number = 0; 2321 @State fwidth: number = 420; 2322 @State fheight: number = 280; 2323 2324 build() { 2325 Column() { 2326 FormComponent({ 2327 id: this.formId, 2328 name: "widget", 2329 bundle: "com.example.cardprovider", 2330 ability: "EntryFormAbility", 2331 module: "entry", 2332 dimension: FormDimension.Dimension_2_2, 2333 temporary: false, 2334 }) 2335 .allowUpdate(true) 2336 .size({ width: this.fwidth, height: this.fheight }) 2337 .visibility(Visibility.Visible) 2338 .onAcquired((form) => { 2339 console.log(`testTag form info : ${JSON.stringify(form)}`); 2340 this.formId = form.id; 2341 try { 2342 let formIds: string[] = [this.formId.toString()]; 2343 formHost.setRouterProxy(formIds, (want: Want) => { 2344 console.info(`formHost recv router event, want: ${JSON.stringify(want)}`); 2345 // The widget host processes the redirection. 2346 this.context.startAbility(want, (err: BusinessError) => { 2347 console.info(`formHost startAbility error, code: ${err.code}, message: ${err.message}`); 2348 }); 2349 }).then(() => { 2350 console.info('formHost set router proxy success'); 2351 }).catch((err: BusinessError) => { 2352 console.error(`set router proxy error, code: ${err.code}, message: ${err.message}`); 2353 }) 2354 } catch (e) { 2355 console.log('formHost setRouterProxy catch exception: ' + JSON.stringify(e)); 2356 } 2357 }) 2358 } 2359 .width('100%') 2360 .height('100%') 2361 } 2362} 2363``` 2364 2365## clearRouterProxy<sup>11+</sup> 2366 2367clearRouterProxy(formIds:Array<string>, callback: AsyncCallback<void>): void 2368 2369Clears the router proxy set for widgets. This API uses an asynchronous callback to return the result. 2370 2371**Required permissions**: ohos.permission.REQUIRE_FORM 2372 2373**System capability**: SystemCapability.Ability.Form 2374 2375**Parameters** 2376 2377| Name | Type | Mandatory | Description | 2378| -------- | ------------------------- | ---- | ------------------------------------------------------------ | 2379| formIds | Array<string>; | Yes | Array of widget IDs. | 2380| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the router proxy is cleared, **error** is **undefined**; otherwise, an exception is thrown. | 2381 2382**Error codes** 2383 2384| Error Code ID | Error Message | 2385| -------- | ------------------------------------------------------------ | 2386| 201 | Permissions denied. | 2387| 202 | The application is not a system application. | 2388| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 2389| 16500050 | IPC connection error. | 2390| 16500060 | Service connection error. | 2391| 16501000 | An internal functional error occurred. | 2392| 16501003 | The form cannot be operated by the current application. | 2393 2394For details about the error codes, see [Form Error Codes](errorcode-form.md). 2395 2396**Example** 2397 2398```ts 2399import { formHost } from '@kit.FormKit'; 2400import { BusinessError } from '@kit.BasicServicesKit'; 2401 2402try { 2403 let formIds: string[] = ['12400633174999288']; 2404 formHost.clearRouterProxy(formIds, (err: BusinessError) => { 2405 if (err) { 2406 console.error(`formHost clear router proxy error, code: ${err.code}, message: ${err.message}`); 2407 } 2408 }); 2409} catch (error) { 2410 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 2411} 2412``` 2413 2414## clearRouterProxy<sup>11+</sup> 2415 2416clearRouterProxy(formIds:Array<string>): Promise<void> 2417 2418Clears the router proxy set for widgets. This API uses a promise to return the result. 2419 2420**Required permissions**: ohos.permission.REQUIRE_FORM 2421 2422**System capability**: SystemCapability.Ability.Form 2423 2424**Parameters** 2425 2426| Name | Type | Mandatory | Description | 2427| ------- | ------------------- | ---- | -------------- | 2428| formIds | Array<string> | Yes | Array of widget IDs. | 2429 2430**Return value** 2431 2432| Type | Description | 2433| ------------------- | ------------------------- | 2434| Promise<void> | Promise that returns no value. | 2435 2436**Error codes** 2437 2438| Error Code ID | Error Message | 2439| -------- | ------------------------------------------------------------ | 2440| 201 | Permissions denied. | 2441| 202 | The application is not a system application. | 2442| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 2443| 16500050 | IPC connection error. | 2444| 16500060 | Service connection error. | 2445| 16501000 | An internal functional error occurred. | 2446| 16501003 | The form cannot be operated by the current application. | 2447 2448For details about the error codes, see [Form Error Codes](errorcode-form.md). 2449 2450**Example** 2451 2452```ts 2453import { formHost } from '@kit.FormKit'; 2454import { BusinessError } from '@kit.BasicServicesKit'; 2455 2456try { 2457 let formIds: string[] = ['12400633174999288']; 2458 formHost.clearRouterProxy(formIds).then(() => { 2459 console.log('formHost clear rourter proxy success'); 2460 }).catch((err: BusinessError) => { 2461 console.error(`formHost clear router proxy error, code: ${err.code}, message: ${err.message}`); 2462 }); 2463} catch (error) { 2464 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 2465} 2466``` 2467## setFormsRecyclable<sup>11+</sup> 2468 2469setFormsRecyclable(formIds:Array<string>, callback: AsyncCallback<void>): void 2470 2471Sets widgets to be recyclable. This API uses an asynchronous callback to return the result. 2472 2473**Model restriction**: This API can be used only in the stage model. 2474 2475**Required permissions**: ohos.permission.REQUIRE_FORM 2476 2477**System capability**: SystemCapability.Ability.Form 2478 2479**Parameters** 2480 2481| Name | Type | Mandatory | Description | 2482| -------- | ------------------------- | ---- | ------------------------------------------------------------ | 2483| formIds | Array<string>; | Yes | Array of widget IDs. | 2484| 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. | 2485 2486**Error codes** 2487 2488| Error Code ID | Error Message | 2489| -------- | ------------------------------------------------------------ | 2490| 201 | Permissions denied. | 2491| 202 | The application is not a system application. | 2492| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 2493| 16500050 | IPC connection error. | 2494| 16500060 | Service connection error. | 2495| 16501000 | An internal functional error occurred. | 2496 2497For details about the error codes, see [Form Error Codes](errorcode-form.md). 2498 2499**Example** 2500 2501```ts 2502import { formHost } from '@kit.FormKit'; 2503import { BusinessError } from '@kit.BasicServicesKit'; 2504 2505try { 2506 let formIds: string[] = ['12400633174999288']; 2507 formHost.setFormsRecyclable(formIds, (err: BusinessError) => { 2508 if (err) { 2509 console.error(`setFormsRecyclable error, code: ${err.code}, message: ${err.message}`); 2510 } 2511 }); 2512} catch (error) { 2513 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 2514} 2515``` 2516 2517## setFormsRecyclable<sup>11+</sup> 2518 2519setFormsRecyclable(formIds:Array<string>): Promise<void> 2520 2521Sets widgets to be recyclable. This API uses a promise to return the result. 2522 2523**Model restriction**: This API can be used only in the stage model. 2524 2525**Required permissions**: ohos.permission.REQUIRE_FORM 2526 2527**System capability**: SystemCapability.Ability.Form 2528 2529**Parameters** 2530 2531| Name | Type | Mandatory | Description | 2532| ------- | ------------------- | ---- | -------------- | 2533| formIds | Array<string> | Yes | Array of widget IDs. | 2534 2535**Return value** 2536 2537| Type | Description | 2538| ------------------- | ------------------------- | 2539| Promise<void> | Promise that returns no value. | 2540 2541**Error codes** 2542 2543| Error Code ID | Error Message | 2544| -------- | ------------------------------------------------------------ | 2545| 201 | Permissions denied. | 2546| 202 | The application is not a system application. | 2547| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 2548| 16500050 | IPC connection error. | 2549| 16500060 | Service connection error. | 2550| 16501000 | An internal functional error occurred. | 2551 2552For details about the error codes, see [Form Error Codes](errorcode-form.md). 2553 2554**Example** 2555 2556```ts 2557import { formHost } from '@kit.FormKit'; 2558import { BusinessError } from '@kit.BasicServicesKit'; 2559 2560try { 2561 let formIds: string[] = ['12400633174999288']; 2562 formHost.setFormsRecyclable(formIds).then(() => { 2563 console.log('setFormsRecyclable success'); 2564 }).catch((err: BusinessError) => { 2565 console.error(`setFormsRecyclable error, code: ${err.code}, message: ${err.message}`); 2566 }); 2567} catch (error) { 2568 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 2569} 2570``` 2571## recoverForms<sup>11+</sup> 2572 2573recoverForms(formIds:Array<string>, callback: AsyncCallback<void>): void 2574 2575Recovers widgets. This API uses an asynchronous callback to return the result. 2576 2577**Model restriction**: This API can be used only in the stage model. 2578 2579**Required permissions**: ohos.permission.REQUIRE_FORM 2580 2581**System capability**: SystemCapability.Ability.Form 2582 2583**Parameters** 2584 2585| Name | Type | Mandatory | Description | 2586| -------- | ------------------------- | ---- | ------------------------------------------------------------ | 2587| formIds | Array<string>; | Yes | Array of widget IDs. | 2588| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the widgets are recovered, **error** is **undefined**; otherwise, an exception is thrown. | 2589 2590**Error codes** 2591 2592| Error Code ID | Error Message | 2593| -------- | ------------------------------------------------------------ | 2594| 201 | Permissions denied. | 2595| 202 | The application is not a system application. | 2596| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 2597| 16500050 | IPC connection error. | 2598| 16500060 | Service connection error. | 2599| 16501000 | An internal functional error occurred. | 2600 2601For details about the error codes, see [Form Error Codes](errorcode-form.md). 2602 2603**Example** 2604 2605```ts 2606import { formHost } from '@kit.FormKit'; 2607import { BusinessError } from '@kit.BasicServicesKit'; 2608 2609try { 2610 let formIds: string[] = ['12400633174999288']; 2611 formHost.recoverForms(formIds, (err: BusinessError) => { 2612 if (err) { 2613 console.error(`recoverForms error, code: ${err.code}, message: ${err.message}`); 2614 } 2615 }); 2616} catch (error) { 2617 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 2618} 2619``` 2620## recoverForms<sup>11+</sup> 2621 2622recoverForms(formIds: Array<string>): Promise<void> 2623 2624Recovers 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. 2625 2626**Model restriction**: This API can be used only in the stage model. 2627 2628**Required permissions**: ohos.permission.REQUIRE_FORM 2629 2630**System capability**: SystemCapability.Ability.Form 2631 2632**Parameters** 2633 2634| Name | Type | Mandatory | Description | 2635| ------- | ------------------- | ---- | -------------- | 2636| formIds | Array<string> | Yes | Array of widget IDs. | 2637 2638**Return value** 2639 2640| Type | Description | 2641| ------------------- | ------------------------- | 2642| Promise<void> | Promise that returns no value. | 2643 2644 2645**Error codes** 2646 2647| Error Code ID | Error Message | 2648| -------- | ------------------------------------------------------------ | 2649| 201 | Permissions denied. | 2650| 202 | The application is not a system application. | 2651| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 2652| 16500050 | IPC connection error. | 2653| 16500060 | Service connection error. | 2654| 16501000 | An internal functional error occurred. | 2655 2656For details about the error codes, see [Form Error Codes](errorcode-form.md). 2657 2658**Example** 2659 2660```ts 2661import { formHost } from '@kit.FormKit'; 2662import { BusinessError } from '@kit.BasicServicesKit'; 2663 2664try { 2665 let formIds: string[] = ['12400633174999288']; 2666 formHost.recoverForms(formIds).then(() => { 2667 console.info('recover forms success'); 2668 }).catch((err: BusinessError) => { 2669 console.error(`formHost recover forms error, code: ${err.code}, message: ${err.message}`); 2670 }); 2671} catch (e) { 2672 console.info(`catch error, code: ${e.code}, message: ${e.message}`); 2673} 2674``` 2675## recycleForms<sup>12+</sup> 2676 2677recycleForms(formIds: Array<string>): Promise<void> 2678 2679Recycles widgets, that is, reclaims their memory. This API uses a promise to return the result. 2680 2681**Model restriction**: This API can be used only in the stage model. 2682 2683**Required permissions**: ohos.permission.REQUIRE_FORM 2684 2685**System capability**: SystemCapability.Ability.Form 2686 2687**Parameters** 2688 2689| Name | Type | Mandatory | Description | 2690| ------- | ------------------- | ---- | -------------- | 2691| formIds | Array<string> | Yes | Array of widget IDs. | 2692 2693**Return value** 2694 2695| Type | Description | 2696| ------------------- | ------------------------- | 2697| Promise<void> | Promise that returns no value. | 2698 2699 2700**Error codes** 2701 2702| Error Code ID | Error Message | 2703| -------- | ------------------------------------------------------------ | 2704| 201 | Permissions denied. | 2705| 202 | The application is not a system application. | 2706| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 2707| 16500050 | IPC connection error. | 2708| 16500060 | Service connection error. | 2709| 16501000 | An internal functional error occurred. | 2710 2711For details about the error codes, see [Form Error Codes](errorcode-form.md). 2712 2713**Example** 2714 2715```ts 2716import { formHost } from '@kit.FormKit'; 2717import { BusinessError } from '@kit.BasicServicesKit'; 2718 2719try { 2720 let formIds: string[] = ['12400633174999288']; 2721 formHost.recycleForms(formIds).then(() => { 2722 console.info('recycle forms success'); 2723 }).catch((err: BusinessError) => { 2724 console.error(`formHost recycle forms error, code: ${err.code}, message: ${err.message}`); 2725 }); 2726} catch (e) { 2727 console.error(`catch error, code: ${e.code}, message: ${e.message}`); 2728} 2729``` 2730 2731## updateFormLocation<sup>12+</sup> 2732updateFormLocation(formId: string, location: formInfo.FormLocation): void; 2733 2734Updates the widget location. 2735 2736**Model restriction**: This API can be used only in the stage model. 2737 2738**Required permissions**: ohos.permission.REQUIRE_FORM 2739 2740**System capability**: SystemCapability.Ability.Form 2741 2742**Parameters** 2743 2744| Name | Type | Mandatory | Description | 2745| ------ | ------ | ---- | ------- | 2746| formId | string | Yes | Widget ID. | 2747| location |[formInfo.FormLocation](js-apis-app-form-formInfo-sys.md#formlocation) | Yes | Widget location. | 2748 2749**Error codes** 2750 2751| Error Code ID | Error Message | 2752| -------- | ------------------------------------------------------------ | 2753| 201 | Permissions denied. | 2754| 202 | The application is not a system application. | 2755| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 2756| 16500050 | IPC connection error. | 2757| 16500060 | Service connection error. | 2758| 16501000 | An internal functional error occurred. | 2759| 16501001 | The ID of the form to be operated does not exist. | 2760| 16501003 | The form cannot be operated by the current application. | 2761 2762For details about the error codes, see [Form Error Codes](errorcode-form.md). 2763 2764**Example** 2765 2766```ts 2767import { formHost, formInfo } from '@kit.FormKit'; 2768import { BusinessError } from '@kit.BasicServicesKit'; 2769 2770try { 2771 let formId: string = '12400633174999288'; 2772 formHost.updateFormLocation(formId, formInfo.FormLocation.SCREEN_LOCK); 2773} catch (error) { 2774 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 2775} 2776``` 2777 2778## setPublishFormResult<sup>12+</sup> 2779 2780setPublishFormResult(formId: string, result: formInfo.PublishFormResult): void; 2781 2782Sets the result for the operation of adding a widget to the home screen. 2783 2784**Model restriction**: This API can be used only in the stage model. 2785 2786**Required permissions**: ohos.permission.REQUIRE_FORM 2787 2788**System capability**: SystemCapability.Ability.Form 2789 2790**Parameters** 2791 2792| Name | Type | Mandatory | Description | 2793| ------ | ------------------------------------------------------------ | ---- | ------------------ | 2794| formId | string | Yes | Widget ID. | 2795| result | [PublishFormResult](js-apis-app-form-formInfo-sys.md#publishformresult) | Yes | Result of the operation. | 2796 2797**Error codes** 2798 2799| Error Code ID | Error Message | 2800| -------- | ------------------------------------------------------------ | 2801| 201 | Permissions denied. | 2802| 202 | The application is not a system application. | 2803| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 2804| 16500050 | IPC connection error. | 2805| 16500060 | Service connection error. | 2806| 16501000 | An internal functional error occurred. | 2807| 16501001 | The ID of the form to be operated does not exist. | 2808 2809For details about the error codes, see [Form Error Codes](errorcode-form.md). 2810 2811**Example** 2812 2813```ts 2814import { formHost, formInfo } from '@kit.FormKit'; 2815import { BusinessError } from '@kit.BasicServicesKit'; 2816 2817try { 2818 let formId: string = '12400633174999288'; 2819 let res: formInfo.PublishFormResult = {code: formInfo.PublishFormErrorCode.SUCCESS, message: ''}; 2820 formHost.setPublishFormResult(formId, res); 2821} catch (error) { 2822 console.error(`catch error, code: ${(error as BusinessError).code}, message: ${(error as BusinessError).message}`); 2823} 2824``` 2825