@tanshenghu/form-binder v1.0.4
title: FormBinder category: Components
chinese: 表单粘合剂
表单数据获取方案。
说明： 1. 淘宝 飞冰团队已经将近一年没有更新这个组件了，并且这个组件将慢慢被弃用，所以本人后期慢慢维护源码
- 在原有的基础之上修复list列表表单，添加、删除、上下移动等功能引起的验证问题
- 当多个input相互关联，或按钮等其它元素关联input时，自动监听onChange触发验证问题的扩展
- 如果使用的是 FormBinder 0.x 的版本，请移步到 0.x 参考文档。
- 如果使用的是 FormBinder 1.x 的版本，需要确保依赖的 react 版本在 16.2.0 以上，1.x 版本使用了 React.Fragments API，支持 FormBinderWrapper 组件返回多个节点。
安装和升级
npm install @tanshenghu/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 ，请务必遵守这个协议。