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