@icedesign/form-binder NPM

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 包装的组件，数据传递和同步将被接管，这意味着：

你不需要使用表单元素的 onChange 来做同步，但还是可以继续监听 onChange 等事件
你不能使用组件的表单元素的 value、 defaultValue 等属性来设置表单元素的值，但可以通过初始的 value 进行设置
你不需要通过 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 必须被调用）

推荐：

建议统一使用 async-validator 的校验规则，尽量不要使用表单元素的相关检验属性，这样做有利于代码的可维护性和优雅。
内建校验类型，可选项。
更多高级用法可参考 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 ，请务必遵守这个协议。