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: FormInfo) 28 29创建卡片组件，用于显示提供的卡片。 30 31**参数：** 32 33| 参数名 | 参数类型 | 必填 | 参数描述 | 34| --------- | ------------------------------- | ---- | ----------------------------------------------------------------------- | 35| value | [FormInfo](#forminfo12) | 是 | 卡片信息。 | 36 37## FormInfo<sup>12+</sup> 38 39卡片信息。 40 41| 参数名 | 参数类型 | 必填 | 参数描述 | 42| --------- | ------------------------------- | ---- |-------| 43| id | number \| string | 是 | 卡片标识（新建卡片填0）。<br/>**说明：**<br>不同使用方不可使用相同id。<br/>同一使用方使用相同id时，显示后添加的卡片。 | 44| name | string | 是 | 卡片名称。 | 45| bundle | string | 是 | 目标卡片包名。 | 46| ability | string | 是 | 目标卡片Ability名称。 | 47| module | string | 是 | 卡片模块名称。 | 48| dimension | [FormDimension](#formdimension) | 否 | 卡片尺寸，支持2 * 2，4 * 4，4 * 2类型卡片。<br/>默认值：Dimension_2_2。 | 49| temporary | boolean | 否 | 卡片是否为临时卡片。 | 50| renderingMode | [FormRenderingMode](#formrenderingmode11) | 否 | 卡片渲染模式。取值如下，默认值为 FULL_COLOR。<br>- FULL_COLOR：代表全色模式，卡片框架不会对卡片效果做出修改，保持和卡片开发者设置的效果不变。<br>- SINGLE_COLOR：代表单色模式，卡片框架会把卡片背景设为透明，开发者需按最佳实践设置卡片风格。<br>**说明：**<br/>如果系统不支持统一渲染模式，卡片框架在单色模式下也不会把卡片背景设为透明。 | 51 52## FormCallbackInfo<sup>12+</sup> 53 54卡片查询或者卸载时获取formId的参数。 55 56| 参数名 | 参数类型 | 必填 | 参数描述 | 57| --------- | ------------------------------- | ---- | ----------------------------------------------------------------------- | 58| id | number | 是 | 卡片标识（number类型）。<br/>**说明：**<br>如果获取到的id为-1，说明id大于等于2^53，需要使用idString获取。 | 59| idString | string | 是 | 卡片标识（string类型）。<br/> | 60 61## FormDimension 62 63| 名称 | 描述 | 64| -------------------------- | -------- | 65| Dimension_1_2 | 1*2 卡片 | 66| Dimension_2_2 | 2*2 卡片 | 67| Dimension_2_4 | 2*4 卡片 | 68| Dimension_4_4 | 4*4 卡片 | 69| Dimension_2_1<sup>9+</sup> | 2*1 卡片 | 70| Dimension_1_1<sup>11+</sup> | 1*1 卡片 | 71| Dimension_6_4<sup>12+</sup> | 6*4 卡片 | 72| Dimension_2_3<sup>14+</sup> | 2*3 卡片为穿戴设备使用 | 73| Dimension_3_3<sup>14+</sup> | 3*3 卡片为穿戴设备使用 | 74 75## FormRenderingMode<sup>11+</sup> 76| 名称 | 描述 | 77| -------------------------- | -------- | 78| FULL_COLOR | 全色模式。| 79| SINGLE_COLOR | 单色模式。| 80 81## 属性 82 83### size 84 85size(value: { width: number; height: number }) 86 87设置高宽尺寸。 88 89**系统接口：** 此接口为系统接口。 90 91**系统能力：** SystemCapability.ArkUI.ArkUI.Full 92 93**参数：** 94 95| 参数名 | 类型 | 必填 | 说明 | 96| ------ | --------------------------------------------------------- | ---- | ---------- | 97| value | {<br/>width?: number,<br/>height?: number<br/>} | 是 | 宽高尺寸。 | 98 99### moduleName 100 101moduleName(value: string) 102 103设置卡片模块名称。 104 105**系统接口：** 此接口为系统接口。 106 107**系统能力：** SystemCapability.ArkUI.ArkUI.Full 108 109**参数：** 110 111| 参数名 | 类型 | 必填 | 说明 | 112| ------ | ------ | ---- | -------------- | 113| value | string | 是 | 卡片模块名称。 | 114 115### dimension 116 117dimension(value: FormDimension) 118 119设置卡片尺寸，支持2 * 2，4 * 4，4 * 2类型卡片。 120 121**系统接口：** 此接口为系统接口。 122 123**系统能力：** SystemCapability.ArkUI.ArkUI.Full 124 125**参数：** 126 127| 参数名 | 类型 | 必填 | 说明 | 128| ------ | ------------------------------- | ---- | ------------------------------------ | 129| value | [FormDimension](#formdimension) | 是 | 卡片尺寸。<br/>默认值：Dimension_2_2 | 130 131### allowUpdate 132 133allowUpdate(value: boolean) 134 135设置是否允许卡片更新。 136 137**系统接口：** 此接口为系统接口。 138 139**系统能力：** SystemCapability.ArkUI.ArkUI.Full 140 141**参数：** 142 143| 参数名 | 类型 | 必填 | 说明 | 144| ------ | ------- | ---- | ----------------------------------- | 145| value | boolean | 是 | 是否允许卡片更新。<br/>默认值：true | 146 147### visibility 148 149visibility(value: Visibility) 150 151设置是否允许卡片可见。 152 153**系统接口：** 此接口为系统接口。 154 155**系统能力：** SystemCapability.ArkUI.ArkUI.Full 156 157**参数：** 158 159| 参数名 | 类型 | 必填 | 说明 | 160| ------ | --------------------------------------------- | ---- | -------------------------------------- | 161| value | [Visibility](ts-appendix-enums.md#visibility) | 是 | 是否允许卡片可见。<br/>默认值：Visible | 162 163## 事件 164 165### onAcquired 166 167onAcquired(callback: Callback[\<FormCallbackInfo>](#formcallbackinfo12)): FormComponentAttribute 168 169获取到卡片后触发，返回卡片的id。 170 171**系统接口：** 此接口为系统接口。 172 173**系统能力：** SystemCapability.ArkUI.ArkUI.Full 174 175**参数：** 176 177| 参数名 | 类型 | 必填 | 说明 | 178| ------ | ----------------------------------- | ---- | ---------- | 179| Callback | [FormCallbackInfo](#formcallbackinfo12) | 是 | 卡片的id。 | 180 181### onError 182 183onError(callback: (info: { errcode: number; msg: string }) => void) 184 185组件加载错误回调。 186 187**系统接口：** 此接口为系统接口。 188 189**系统能力：** SystemCapability.ArkUI.ArkUI.Full 190 191**参数：** 192 193| 参数名 | 类型 | 必填 | 说明 | 194| ------ | ------------------------------------------------------------ | ---- | ----------------------------------------------- | 195| info | { errcode: number, msg: string } | 是 | errcode: 错误码。<br/>msg: 错误信息。 | 196 197### onRouter 198 199onRouter(callback: (info: any) => void) 200 201组件路由事件回调，返回[routerEvent](../js-service-widget-ui/js-service-widget-syntax-hml.md#事件绑定)中的信息。 202 203**系统接口：** 此接口为系统接口。 204 205**系统能力：** SystemCapability.ArkUI.ArkUI.Full 206 207**参数：** 208 209| 参数名 | 类型 | 必填 | 说明 | 210| ------ | ---- | ---- | ------------------------------------------------------------ | 211| info | any | 是 | [routerEvent](../js-service-widget-ui/js-service-widget-syntax-hml.md#事件绑定)中的信息。 | 212 213### onUninstall 214 215onUninstall(callback: Callback[\<FormCallbackInfo>](#formcallbackinfo12)): FormComponentAttribute 216 217组件卸载回调，返回卸载卡片的id。 218 219**系统接口：** 此接口为系统接口。 220 221**系统能力：** SystemCapability.ArkUI.ArkUI.Full 222 223**参数：** 224 225| 参数名 | 类型 | 必填 | 说明 | 226| ------ | ----------------------------------- | ---- | ---------- | 227| Callback | [FormCallbackInfo](#formcallbackinfo12) | 是 | 卡片的id。 | 228 229 230## 示例 231 232卡片示例。 233 234该示例创建一张2 * 2尺寸大小的卡片，并注册事件回调。 235```ts 236//card.ets 237@Entry 238@Component 239struct CardExample { 240 @State formId:string = '0'; 241 build() { 242 Column() { 243 Text('this is a card') 244 .fontSize(50) 245 .fontWeight(FontWeight.Bold) 246 FormComponent({ 247 id:this.formId, 248 name:"Form1", 249 bundle:"com.example.cardexample", 250 ability:"FormAbility", 251 module:"entry", 252 dimension:FormDimension.Dimension_2_2, 253 temporary:false 254 }) 255 .allowUpdate(true) 256 .size({width:360,height:360}) 257 .visibility(Visibility.Visible) 258 .onAcquired((form: FormCallbackInfo)=>{ 259 console.log(`form info : ${JSON.stringify(form)}`); 260 // Invalid form id 261 if (form.id == -1) { 262 this.formId = form.idString; 263 } else { 264 this.formId = form.id.toString(); 265 } 266 }) 267 .onError((err)=>{ 268 console.log(`fail to add form, err: ${JSON.stringify(err)}`); 269 }) 270 .onUninstall((form: FormCallbackInfo)=>{ 271 console.log(`uninstall form success : ${JSON.stringify(form)}`); 272 // Invalid form id 273 if (form.id == -1) { 274 this.formId = form.idString; 275 } else { 276 this.formId = form.id.toString(); 277 } 278 }) 279 } 280 .width('100%') 281 .height('100%') 282 } 283} 284``` 285 286
