title: FormBinder category: Components chinese: ICE 表单粘合剂

ICE 表单数据获取方案。

说明：

1. 如果使用的是 FormBinder 0.x 的版本，请移步到 0.x 参考文档。
2. 如果使用的是 FormBinder 1.x 的版本，需要确保依赖的 react 版本在 16.2.0 以上，1.x 版本使用了 React.Fragments API，支持 FormBinderWrapper 组件返回多个节点。

安装和升级

npm install @icedesign/form-binder

表单功能

• 表单双向绑定
• 表单值统一处理
• 布局自由组合
• 对数据的有效性进行验证

表单元素

表单元素指的是 ICE 基础组件以及业务组件中的 Input 、 Checkbox 、 Select 、 Range 、 DatePicker 、 TimePicker 、 NumberPicker 、 Switch 、 Upload 等以及用户自定义的组件，它能够响应 onChange 等用来获取用户输入

参数（Props）

| 方法名 | 说明 | 类型 | 默认值 | | :------------- | :----------------------------------------------------------------------- | :------------------------------------------------------- | :----- | | validateFields | 校验并获取一组输入域的值与 Error，若 fieldNames 参数为空，则校验全部组件 | ([fieldNames: string[]],callback(errors,values)) => void | |

FormBinderWrapper

整个表单的容器，支持传入 value 和 onChange 等属性，其中 value 会作为整个表单数据根节点，交由下层组件去获取、更新操作

经过 FormBinderWrapper 包装的组件，数据传递和同步将被接管，这意味着：

1. 你不需要使用表单元素的 onChange 来做同步，但还是可以继续监听 onChange 等事件
2. 你不能使用组件的表单元素的 value、 defaultValue 等属性来设置表单元素的值，但可以通过初始的 value 进行设置
3. 你不需要通过 setState 来动态更新表单的值，因为表单默认支持双向数据通信，但可以通过 setFieldValue 和 getFieldValue 来设置或者更新表单域的值

参数（Props）

| 属性参数 | 说明 | 类型 | 默认值 | | :------------------------ | :-------------------------------------------------------------------- | :-------------- | :------- | | value | 表单值 | object | {} | | onChange | 任一表单域的值发生改变时的回调 | function(value) | () => {} | | enableScrollErrorField | 全局校验时，是否开启滚动到报错表单位置 | boolean | false | | scrollErrorFieldTopOffset | 全局校验滚动到报错位置时，距离顶部的偏移值（适用于头部 fixed 的场景） | number | 0 |

FormBinder

表单组件粘合剂，将其作为 FormBinderWrapper 的子组件，即可实现双向绑定特性，之后表单域的改变会通过 FormBinder 转发从而响应到 FormBinderWrapper 的 onChange 方法进行通信

FormBinder 支持的属性包含以下两部分：

• 自定义规则
• 检验规则

自定义规则

参数（Props）

| 属性参数 | 说明 | 类型 | 默认值 | | :------------ | :--------------------- | :-------------------------- | :--------- | | rules | 校验规则，参考下方文档 | object[] | | | name​ | 表单域名称 | string | | | setFieldValue | 设置一个输入控件的值 | Function(fieldName: string) | | | getFieldValue | 获取一个输入控件的值 | Function(fieldName: string) | | | triggerType | 指定合适的触发事件 | string | 'onChange' |

校验规则

参数（Props）

| 参数 | 说明 | 类型 | 默认值 | | :--------- | :--------------------------- | :-------------------------------------- | :------- | | enum | 枚举类型 | string | | | len | 字段长度 | number | | | max | 最大长度 | number | | | message | 校验文案 | string | | | min | 最小长度 | number | | | pattern | 正则表达式校验 | RegExp | | | required | 是否必选 | boolean | false | | transform | 校验前转换字段值 | function(value) => transformedValue:any | | | type | 内建校验类型 | string | 'string' | | validator | 自定义校验 | function(rule, value, callback) | | | whitespace | 必选时，空格是否会被视为错误 | boolean | false |

内建校验类型，可选项 自定义校验（注意，callback 必须被调用）

推荐：

1. 建议统一使用 async-validator 的校验规则，尽量不要使用表单元素的相关检验属性，这样做有利于代码的可维护性和优雅。
2. 内建校验类型，可选项。
3. 更多高级用法可参考 async-validator。

FormError

自定义表单的报错信息，自定义报错信息时需要指定 name，以此来获取当前报错的表单域来源

参数（Props）

| 参数 | 说明 | 类型 | 默认值 | | :-------- | :----------------------------- | :------------------------- | :----- | | name​ | 表单域名称 | string | | | style | 自定义样式对象 | object | | | className | 自定义样式类名 | string | | | render | 自定义渲染报错的组件和处理逻辑 | Function(errors):ReactNode | |

双向绑定协议

双向绑定协议指的是组件接收 value 和 onChange 两个参数，其用户输入值由 value 提供，当用户操作组件导致数据变更，组件会调用 onChange 并把新的 value 作为第一个参数传出。React 社区的大多数组件都遵守这个设计，如 @alifd/next 的 Input, Select, Checkbox 等，如果你希望你的表单类组件能够接入 FormBinder ，请务必遵守这个协议。