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