---
group:
  title: 表单控件
  order: 3
title: ItemGroup
order: 2
toc: content
---

# ItemGroup  表单组

> 用于通用弹窗、筛选条件等组件内配置渲染表单组控件


## 代码演示

<code title="基础用法" src="../../src/FormComp/RenderItemGroup/demos/basic.tsx"></code>

<code title="栅格比例布局" description="可配置`size`,展示默认已配置的栅格比例，也可自定义栅格`displayLayout`。优先级itemGroup[].display 大于 displayLayout 大于 side" src="../../src/FormComp/RenderItemGroup/demos/size.tsx" ></code>

<code title="控件尺寸" description="可配置fieldSize显示控件尺寸大小" src="../../src/FormComp/RenderItemGroup/demos/fieldSize.tsx" ></code>

<code title="表单布局" description="可配置`layout`,展示标签与表单域排列方式。需与Form或StandardForm同时使用" src="../../src/FormComp/RenderItemGroup/demos/layout.tsx"></code>

<code title="表单混合布局" description="在 `Form.Item` 上单独定义 `layout`，可以做到一个表单多种布局。配置化使用`protoFormItem.layout`" src="../../src/FormComp/RenderItemGroup/demos/layoutMix.tsx"></code>

<code title="只读"  src="../../src/FormComp/RenderItemGroup/demos/viewOnly.tsx"></code>


[comment]: <> (<code title="formList" description="Form.List" src="../../src/FormComp/RenderItemGroup/demos/formList.tsx" ></code>)

## API

| 参数      | 说明  |   类型   |必选项| 默认值| 参考值 | 
|----------|------|-------------|------|------|------|
| form | 表单实例 | FormInstance  | 是 | - | - |
| size | 栅格下label与控件布局比例 | String | 否| `md` |可选:`xs`,`sm`,`md`,`lg`,`xlg` |
| columnCount | `vertical`、`horizontal`配置下栅格列数, 优先级高于`size`的栅格数 | Number | 否| - |可选:`1`,`2`,`3`,`4`|
| layout | 表单布局 | String | 否 |`horizontal` |`horizontal`/`vertical`/`inline` |
| itemGroup | 表单控件配置项组 | Array | 是 |- |[itemGroup参数](#itemgroup-api) |
| displayLayout | 自定义标签与控件栅格值 |  Object[参考](#displaylayout-配置值) |  否| |{labelCol: { span: 7 },  wrapperCol: { span: 15 },} |
| fieldStatus | 配置化表单展示状态：“viewOnly 只显示值不显示控件”或者"disabled:控件禁用" | String| 否 | `default` | |
| fieldSize | 统一配置控件大小，【优先级低于`itemGroup[{size}]`】 | String| 否 | `middle` |`large`/`middle`/`small`  |
| doUpdateFormFields | 子组件内表单控件更新触发 | Function |否  |- | - |


### itemGroup API

| 参数字段      | 说明  |   类型   |必选项| 参考值|
|----------|------|-------------|------|------|
| label | 标签显示值 | String | 是 | |
| filedName | 表单名称，会作为表单字段 id 前缀使用 | String| - |- |
| type | 当前控件类型 | String | 是 | [可选值](#type-可选值)|
| description | 描述，用于显示label后带info图标的浮层文本 | String/ ReactNode / TooltipProps & { icon: ReactNode } | 否 | 同`Form.Item.Tooltip`|
| isHide | 是否隐藏当前配置的组件(需要结合protoFormItem.shouldUpdate使用) | Boolean/Function(fieldValues, form)| 否 | fieldValues指当前配置表单内部的所有控件值，form指当前弹窗内部的表单实例 |
| customRender | 自定义表单控件结构(必须配合`type="custom"`使用) | Function(form,item,fieldStatus,extra) | 否  |extra={onFieldsChange: Function} |
| colSpan | 当前标签控件占用的栅格数 | Number | 否| |
| display |显示模式，`side`与其他控件并列展示或者`block`独占一行，若为对象则按对象定义的栅格展示 | String或Object | 否 | `side`/`block`/`{labelCol:{ span: 4 }, wrapperCol: { span: 19}}`  |
| size | 控件大小，【优先级高于`fieldSize`,低于`protoConfig.size`】 | String | 否 | `large`/`middle`/`small` |
| protoConfig | 表单控件antd原生属性配置 | Object | 否|参考官网各组件配置 |
| protoFormItem | Form.Item 原始API | Object | 否|[官网API](https://ant.design/components/form-cn/#Form.Item)  |
| protoCol | 表单栅格Col配置项 | Object | 否| [官网Col API](https://ant.design/components/grid-cn#col) |
| onChange | 控件更新事件 | Function | 否 | |
| preExtra | 表单域配置控件前置结构 | Function(data, form) | 否 | |
| extra | 表单域配置控件后置结构 | Function(data, form) | 否 | |
| rules | 校验规则 | 	{ validator, message }[] | 否 | |
| fieldOptions | 旧方式配置校验规则 | {rules: [], initialValue: any} | 否 | |
| componentStyle | 控件类样式 | object | 否 | |
| 其他 | 其他配置项目可查看 [Field](/components/field#api) |  | |-|


### type 可选值

> 输入类：`input、password、textarea、inputNumber`
>
> 选项类： `select、tree-select、checkbox、radio`
>
> 日期类： `datePicker、dateTimePicker、rangePicker、rangeTimePicker、timePicker、timePickerRange`
>
> 上传类： `upload、uploader`
>
> 数据类： `cascader、switch、slider`
>
> 自定义：`custom`
>
> 其他类： `title、html、StandardTitle`

###  type='input'
| 参数字段      | 说明  |   类型   |参考值|
|----------|------|-------------|------|
| protoConfig.viewOnlyHides | `viewOnly`下可指定隐藏前缀或后缀（`v6` 起用 `compactBefore`/`compactAfter`）  | `Array` | `['compactBefore', 'prefix', 'suffix', 'compactAfter']` |

###  type='inputNumber'

| 参数字段      | 说明  |   类型   |参考值|
|----------|------|-------------|------|
| protoConfig.viewOnlyHides | `viewOnly`下可指定隐藏前缀或后缀（`v6` 起用 `compactBefore`/`compactAfter`）  | `Array` | `['compactBefore', 'prefix', 'suffix', 'compactAfter']` |

###  type='search'

| 参数字段      | 说明  |   类型   |参考值|
|----------|------|-------------|------|
| protoConfig.viewOnlyHides | `viewOnly`下可指定隐藏前缀或后缀（`v6` 起用 `compactBefore`/`compactAfter`）  | `Array` | `['compactBefore', 'prefix', 'suffix', 'compactAfter']` |



###  type='mentions'

| 参数字段      | 说明  |   类型   |参考值|
|----------|------|-------------|------|
| protoConfig.viewOnlyHides | `viewOnly`下可指定隐藏前缀或后缀（`v6` 起用 `compactBefore`/`compactAfter`）  | `Array` | `['compactBefore', 'prefix', 'suffix', 'compactAfter']` |



###  type='title'

| 参数字段      | 说明  |   类型   |必选项| 参考值|
|----------|------|-------------|------|------|
| label | 自己定义标题结构，若label="StandardTitle"，则显示标准标题
| protoConfig.title | 自定义结构  | ReactNode | 是 | |结构，   | ReactNode | 是 | |
| protoConfig.mark | 显示标题左侧图标  | ReactNode | 是 | |

###  type='StandardTitle'

| 参数字段      | 说明  |   类型   |必选项| 参考值|
|----------|------|-------------|------|------|
| protoConfig.title | 自定义结构  | ReactNode | 是 | |结构，   | ReactNode | 是 | |
| protoConfig.mark | 显示标题左侧图标  | ReactNode | 是 | |

### displayLayout 配置值
>如使用配置值1，栅格将应用到`display:'side'`的控件,另外有配置`display: 'block'`将会使用原来默认的栅格`general.modalSize[size].formBlockLayout`
>
> 如果想让`display: 'block'`也更改，则可以使用配置值2，分别配置side与block的栅格


```javascript
// 配置值1：
  displayLayout={
    labelCol: { span: 4 },
    wrapperCol: { span: 20 },
  }
// 配置值2：
  displayLayout={
  // 针对于单行多列展示配置
    side: {
      labelCol: { span: 8},
      wrapperCol: { span: 16 },
    },
    // 单行展1列配置
    block: {
      labelCol: { span: 4 },
      wrapperCol: { span: 20 },
    }
  }
```


### 关于栅格数
> 仅在formLayout为 'horizontal'、'vertical' 有效
> 优先级 `columnCount` > `size`

若未配置 `columnCount`，`size`分别对应的栅格数为xs:1列，sm：1列，md:2列，lg：3列，xlg：3列，xxlg：4列

若配置了`columnCount`，则按`columnCount`显示栅格