1# FormComponent (系统接口) 2 3提供卡片组件，实现卡片的显示功能。 4 5> **说明：** 6> 7> - 该组件从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8> 9> - 该组件为卡片组件的使用方，对应提供方的使用参考文档[JS服务卡片UI组件](../js-service-widget-ui/js-service-widget-file.md)。 10> 11> - 该组件使用需要具有系统签名。 12> 13> - 本模块为系统接口。 14 15## 权限 16 17ohos.permission.REQUIRE_FORM, ohos.permission.GET_BUNDLE_INFO_PRIVILEGED 18 19 20## 子组件 21 22无 23 24 25## 接口 26 27FormComponent(value: { 28 id: number; 29 name: string; 30 bundle: string; 31 ability: string; 32 module: string; 33 dimension?: FormDimension; 34 temporary?: boolean; 35 renderingMode?: FormRenderingMode; 36 }) 37 38创建卡片组件，用于显示提供的卡片。 39 40**参数：** 41 42| 参数名 | 参数类型 | 必填 | 参数描述 | 43| --------- | ------------------------------- | ---- | ----------------------------------------------------------------------- | 44| id | number | 是 | 卡片标识（新建卡片填0）。<br/>**说明：**<br>不同使用方不可使用相同id。<br/>同一使用方使用相同id时，显示后添加的卡片。 | 45| name | string | 是 | 卡片名称。 | 46| bundle | string | 是 | 目标卡片包名。 | 47| ability | string | 是 | 目标卡片Ability名称。 | 48| module | string | 是 | 卡片模块名称。 | 49| dimension | [FormDimension](#formdimension) | 否 | 卡片尺寸，支持2 * 2，4 * 4，4 * 2类型卡片。<br/>默认值：Dimension_2_2。 | 50| temporary | boolean | 否 | 卡片是否为临时卡片。 | 51| renderingMode<sup>11+</sup> | [FormRenderingMode](#formrenderingmode11) | 否 | 卡片渲染模式。取值如下，默认值为 FULL_COLOR。<br>- FULL_COLOR：代表全色模式，卡片框架不会对卡片效果做出修改，保持和卡片开发者设置的效果不变。<br>- SINGLE_COLOR：代表单色模式，卡片框架会把卡片背景设为透明，开发者需按最佳实践设置卡片风格。<br>**说明：**<br/>如果系统不支持统一渲染模式，卡片框架在单色模式下也不会把卡片背景设为透明。 | 52 53## FormDimension 54 55| 名称 | 描述 | 56| -------------------------- | -------- | 57| Dimension_1_2 | 1*2 卡片 | 58| Dimension_2_2 | 2*2 卡片 | 59| Dimension_2_4 | 2*4 卡片 | 60| Dimension_4_4 | 4*4 卡片 | 61| Dimension_2_1<sup>9+</sup> | 2*1 卡片 | 62| Dimension_1_1<sup>11+</sup> | 1*1 卡片 | 63 64## FormRenderingMode<sup>11+</sup> 65| 名称 | 描述 | 66| -------------------------- | -------- | 67| FULL_COLOR | 全色模式。| 68| SINGLE_COLOR | 单色模式。| 69 70## 属性 71| 名称 | 参数类型 | 必填 | 描述 | 72| ----------- | ----------------------------------------------------------------------------------------------------- | ---- | ----------------------------------------------------------------------- | 73| size | {<br/>width?: number,<br/>height?: number<br/>} | 是 | 设置高宽尺寸。 | 74| moduleName | string | 是 | 卡片模块名称。 | 75| dimension | [FormDimension](#formdimension) | 否 | 卡片尺寸，支持2 * 2，4 * 4，4 * 2类型卡片。<br/>默认值：Dimension_2_2。 | 76| allowUpdate | boolean | 否 | 是否允许卡片更新。<br/>默认值：true。 | 77| visibility | [Visibility](ts-appendix-enums.md#visibility) | 否 | 是否允许卡片可见。<br/>默认值：Visible。 | 78 79 80 81## 事件 82 83| 名称 | 功能描述 | 84| ------------------------------------------------------------ | ------------------------------------------------------------ | 85| onAcquired(callback: (info: { id: number }) => void) | 获取到卡片后触发，返回卡片的id. | 86| onError(callback: (info: { errcode: number, msg: string }) => void) | 组件加载错误回调。<br/>errcode: 错误码。<br/>msg: 错误信息。<br/>具体可参考[卡片错误码说明文档](../../apis-form-kit/errorcode-form.md) | 87| onRouter(callback: (info: any) => void) | 组件路由事件回调,返回[routerEvent](../js-service-widget-ui/js-service-widget-syntax-hml.md#事件绑定)中的信息。 | 88| onUninstall(callback: (info: { id: number }) => void) | 组件卸载回调，返回卸载卡片的id. | 89 90 91## 示例 92 93```ts 94//card.ets 95@Entry 96@Component 97struct CardExample { 98 @State formId:number = 0; 99 build() { 100 Column() { 101 Text('this is a card') 102 .fontSize(50) 103 .fontWeight(FontWeight.Bold) 104 FormComponent({ 105 id:this.formId, 106 name:"Form1", 107 bundle:"com.example.cardexample", 108 ability:"FormAbility", 109 module:"entry", 110 dimension:FormDimension.Dimension_2_2, 111 temporary:false 112 }) 113 .allowUpdate(true) 114 .size({width:360,height:360}) 115 .visibility(Visibility.Visible) 116 .onAcquired((form)=>{ 117 console.log(`form info : ${JSON.stringify(form)}`); 118 this.formId = form.id; 119 }) 120 .onError((err)=>{ 121 console.log(`fail to add form, err: ${JSON.stringify(err)}`); 122 }) 123 124 } 125 .width('100%') 126 .height('100%') 127 } 128} 129``` 130 131
