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