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，2 * 4等类型卡片。<br/>默认值：Dimension_2_2。 | 49| temporary | boolean | 否 | 卡片是否为临时卡片，true表示是临时卡片，false表示不是临时卡片。<br/>默认值：false。 | 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类型）。 | 60| isLocked<sup>18+</sup> |boolean | 是 | 标识卡片是否为[管控状态](../../apis-form-kit/js-apis-app-form-formHost-sys.md#updateformlockedstate18)，true表示管控状态，false表示非管控状态。 | 61 62## FormSize<sup>18+</sup> 63 64卡片大小信息。 65 66| 参数名 | 参数类型 | 必填 | 参数描述 | 67| --------- | ------------------------------- | ---- |---------| 68| width | number | 是 | 卡片宽的尺寸，单位：vp。 | 69| height | number | 是 | 卡片高的尺寸，单位：vp。 | 70 71## ErrorInformation<sup>18+</sup> 72 73卡片错误信息。 74 75| 参数名 | 参数类型 | 必填 | 参数描述 | 76| --------- | ------------------------------- | ---- | ----------------------------------------------------------------------- | 77| errcode | number | 是 | [错误码](../../apis-form-kit/errorcode-form.md)。 | 78| msg | string | 是 | 错误信息。 | 79 80## FormDimension 81 82| 名称 | 描述 | 83| -------------------------- | -------- | 84| Dimension_1_2 | 1*2 卡片 | 85| Dimension_2_2 | 2*2 卡片 | 86| Dimension_2_4 | 2*4 卡片 | 87| Dimension_4_4 | 4*4 卡片 | 88| Dimension_2_1<sup>9+</sup> | 2*1 卡片 | 89| Dimension_1_1<sup>11+</sup> | 1*1 卡片 | 90| Dimension_6_4<sup>12+</sup> | 6*4 卡片 | 91| Dimension_2_3<sup>18+</sup> | 2*3 卡片为穿戴设备使用 | 92| Dimension_3_3<sup>18+</sup> | 3*3 卡片为穿戴设备使用 | 93 94## FormRenderingMode<sup>11+</sup> 95| 名称 | 描述 | 96| -------------------------- | -------- | 97| FULL_COLOR | 全色模式。| 98| SINGLE_COLOR | 单色模式。| 99 100## 属性 101 102### size<sup>18+</sup> 103 104size(formSize: FormSize) 105 106设置高宽尺寸。 107 108**系统接口：** 此接口为系统接口。 109 110**系统能力：** SystemCapability.ArkUI.ArkUI.Full 111 112**参数：** 113 114| 参数名 | 类型 | 必填 | 说明 | 115| ------ | --------------------------------------------------------- | ---- | ---------- | 116| formSize | [FormSize](#formsize18) | 是 | 宽高尺寸。 | 117 118### moduleName 119 120moduleName(value: string) 121 122设置卡片模块名称。 123 124**系统接口：** 此接口为系统接口。 125 126**系统能力：** SystemCapability.ArkUI.ArkUI.Full 127 128**参数：** 129 130| 参数名 | 类型 | 必填 | 说明 | 131| ------ | ------ | ---- | -------------- | 132| value | string | 是 | 卡片模块名称。 | 133 134### dimension 135 136dimension(value: FormDimension) 137 138设置卡片尺寸，支持2 * 2，4 * 4，2 * 4等类型卡片。 139 140**系统接口：** 此接口为系统接口。 141 142**系统能力：** SystemCapability.ArkUI.ArkUI.Full 143 144**参数：** 145 146| 参数名 | 类型 | 必填 | 说明 | 147| ------ | ------------------------------- | ---- | ------------------------------------ | 148| value | [FormDimension](#formdimension) | 是 | 卡片尺寸。<br/>默认值：Dimension_2_2。 | 149 150### allowUpdate 151 152allowUpdate(value: boolean) 153 154设置是否允许卡片更新。 155 156**系统接口：** 此接口为系统接口。 157 158**系统能力：** SystemCapability.ArkUI.ArkUI.Full 159 160**参数：** 161 162| 参数名 | 类型 | 必填 | 说明 | 163| ------ | ------- | ---- | ----------------------------------- | 164| value | boolean | 是 | 是否允许卡片更新，ture表示允许卡片更新，false表示不允许卡片更新。<br/>默认值：true。 | 165 166### visibility 167 168visibility(value: Visibility) 169 170设置是否允许卡片可见。 171 172**系统接口：** 此接口为系统接口。 173 174**系统能力：** SystemCapability.ArkUI.ArkUI.Full 175 176**参数：** 177 178| 参数名 | 类型 | 必填 | 说明 | 179| ------ | --------------------------------------------- | ---- | -------------------------------------- | 180| value | [Visibility](ts-appendix-enums.md#visibility) | 是 | 是否允许卡片可见。<br/>默认值：Visible。 | 181 182## 事件 183 184### onAcquired 185 186onAcquired(callback: Callback[\<FormCallbackInfo>](#formcallbackinfo12)) 187 188获取到卡片后触发，返回卡片的id。 189 190**系统接口：** 此接口为系统接口。 191 192**系统能力：** SystemCapability.ArkUI.ArkUI.Full 193 194**参数：** 195 196| 参数名 | 类型 | 必填 | 说明 | 197| ------ | ----------------------------------- | ---- | ---------- | 198| callback | [FormCallbackInfo](#formcallbackinfo12) | 是 | 卡片的id。 | 199 200### onError<sup>18+</sup> 201 202onError(callback: Callback\<ErrorInformation\>) 203 204组件加载错误回调。 205 206**系统接口：** 此接口为系统接口。 207 208**系统能力：** SystemCapability.ArkUI.ArkUI.Full 209 210**参数：** 211 212| 参数名 | 类型 | 必填 | 说明 | 213| ------ | ------------------------------------------------------------ | ---- | ----------------------------------------------- | 214| callback | Callback<[ErrorInformation](#errorinformation18)> | 是 | errcode: 错误码。<br/>msg: 错误信息。 | 215 216### onRouter<sup>18+</sup> 217 218onRouter(callback: Callback\<object\>) 219 220组件路由事件回调，返回[routerEvent](../js-service-widget-ui/js-service-widget-syntax-hml.md#事件绑定)中的信息。 221 222**系统接口：** 此接口为系统接口。 223 224**系统能力：** SystemCapability.ArkUI.ArkUI.Full 225 226**参数：** 227 228| 参数名 | 类型 | 必填 | 说明 | 229|------| - | ---- | ------------------------------------------------------------ | 230| callback | Callback\<object\> | 是 | [routerEvent](../js-service-widget-ui/js-service-widget-syntax-hml.md#事件绑定)中的信息。 | 231 232### onUninstall 233 234onUninstall(callback: Callback[\<FormCallbackInfo>](#formcallbackinfo12)) 235 236组件卸载回调，返回卸载卡片的id。 237 238**系统接口：** 此接口为系统接口。 239 240**系统能力：** SystemCapability.ArkUI.ArkUI.Full 241 242**参数：** 243 244| 参数名 | 类型 | 必填 | 说明 | 245|----------| ----------------------------------- | ---- | ---------- | 246| callback | [FormCallbackInfo](#formcallbackinfo12) | 是 | 卡片的id。 | 247 248### onLoad<sup>18+</sup> 249 250onLoad(callback: VoidCallback) 251 252组件加载回调，返回加载卡片的id。 253 254**系统接口：** 此接口为系统接口。 255 256**系统能力：** SystemCapability.ArkUI.ArkUI.Full 257 258**参数：** 259 260| 参数名 | 类型 | 必填 | 说明 | 261|----------| ----------------------------------- | ---- | ---------- | 262| callback | [VoidCallback](ts-types.md#voidcallback12) | 是 | 卡片的id。 | 263 264## 示例 265 266卡片示例。 267 268该示例创建一张2 * 2尺寸大小的卡片，并注册事件回调。 269```ts 270//card.ets 271@Entry 272@Component 273struct CardExample { 274 @State formId:string = '0'; 275 build() { 276 Column() { 277 Text('this is a card') 278 .fontSize(50) 279 .fontWeight(FontWeight.Bold) 280 FormComponent({ 281 id:this.formId, 282 name:"Form1", 283 bundle:"com.example.cardexample", 284 ability:"FormAbility", 285 module:"entry", 286 dimension:FormDimension.Dimension_2_2, 287 temporary:false 288 }) 289 .allowUpdate(true) 290 .size({width:360,height:360}) 291 .visibility(Visibility.Visible) 292 .onAcquired((form: FormCallbackInfo)=>{ 293 console.log(`form info : ${JSON.stringify(form)}`); 294 // Invalid form id 295 if (form.id == -1) { 296 this.formId = form.idString; 297 } else { 298 this.formId = form.id.toString(); 299 } 300 }) 301 .onError((err)=>{ 302 console.log(`fail to add form, err: ${JSON.stringify(err)}`); 303 }) 304 .onUninstall((form: FormCallbackInfo)=>{ 305 console.log(`uninstall form success : ${JSON.stringify(form)}`); 306 // Invalid form id 307 if (form.id == -1) { 308 this.formId = form.idString; 309 } else { 310 this.formId = form.id.toString(); 311 } 312 }) 313 } 314 .width('100%') 315 .height('100%') 316 } 317} 318``` 319 320
