rc-form
React HOC高阶组件.
开发使用
npm install
npm start
open http://localhost:8000/examples/
特性
- 支持 react.js 和 react-native
- 使用 async-validator
验证字段Install
使用
import { createForm, formShape } from 'rc-form';
class Form extends React.Component {
static propTypes = {
form: formShape,
};
submit = () => {
this.props.form.validateFields((error, value) => {
console.log(error, value);
});
}
render() {
let errors;
const { getFieldProps, getFieldError } = this.props.form;
return (
<div>
<input {...getFieldProps('normal')}/>
<input {...getFieldProps('required', {
onChange(){}, // have to write original onChange here if you need
rules: [{required: true}],
})}/>
{(errors = getFieldError('required')) ? errors.join(',') : null}
<button onClick={this.submit}>submit</button>
</div>
);
}
}
export createForm()(Form);
在 React Native 中使用
或者简单一点的例子:
import { createForm } from 'rc-form';
class Form extends React.Component {
componentWillMount() {
this.requiredDecorator = this.props.form.getFieldDecorator('required', {
rules: [{required: true}],
});
}
submit = () => {
this.props.form.validateFields((error, value) => {
console.log(error, value);
});
}
render() {
let errors;
const { getFieldError } = this.props.form;
return (
<div>
{this.requiredDecorator(
<input
onChange={
// can still write your own onChange
}
/>
)}
{(errors = getFieldError('required')) ? errors.join(',') : null}
<button onClick={this.submit}>submit</button>
</div>
);
}
}
export createForm()(Form);
createForm(option: Object) => (WrappedComponent: React.Component) => React.Component
选项参数 | 描述 | 数据类型 | 默认值 |
---|---|---|---|
option.validateMessages | async-validator 的预置消息 | Object | {} |
option.onFieldsChange | 字段改变时调用, 你可以传递字段到 redux store. | (props, changed, all): void | NOOP |
option.onValuesChange | value 值改变时调用. | (props, changed, all): void | NOOP |
option.mapProps | 当被包裹的组件获得新的props时调用。 | (props): Object | props => props |
option.mapPropsToFields | 从 props 中给字段赋值。可以用来从 redux store 中读取字段. | (props): Object | NOOP |
option.fieldNameProp | 指定 getFieldProps 的 name 参数在哪存储。 |
String | – |
option.fieldMetaProp | 在哪里存储 getFieldProps 的元数据。 |
String | – |
option.fieldDataProp | 在哪储存字段值 | String | – |
option.withRef(deprecated) | 是否保存包裹组件的实例,使用 refs.wrappedComponent 来访问. |
boolean | false |
注意: rc-form@1.4.0 以后版本,使用 wrappedComponentRef 而不是 withRef。
class Form extends React.Component { ... }
// 弃用
const EnhancedForm = createForm({ withRef: true })(Form);
<EnhancedForm ref="form" />
this.refs.form.refs.wrappedComponent // => The instance of Form
// 推荐
const EnhancedForm = createForm()(Form);
<EnhancedForm wrappedComponentRef={(inst) => this.formRef = inst} />
this.formRef // => The instance of Form
(WrappedComponent: React.Component) => React.Component
createForm() 函数的返回值. 它会将具有以下成员的对象作为 prop 传递给包裹组件 WrappedComponent:
getFieldProps(name, option): Object { [valuePropName], [trigger], [validateTrigger] }
会传递给可视为输入框组件一系列 props,该组件必须实现 value 和 onchange 接口
设置好只有, 这将创建与此输入的绑定。.
<form>
<input {...getFieldProps('name', { ...options })} />
</form>
name: String
输入框的唯一 name
字段。即输入框的值将会被赋值给的键名
选项参数: Object
选项参数 | 描述 | 类型 | 默认值 | |
---|---|---|---|---|
option.valuePropName | 组件 value 的来源, 例如: checkbox 应该设置为 checked … |
String | 'value' |
|
option.getValueProps | 根据字段值,获取输入框组件的 props | (value): Object | (value) => ({ value }) | |
option.getValueFromEvent | 指定如何从事件中获取值。可以把 onChange 的参数(如 event)转化为控件的值 | (e): any | See below | |
option.initialValue | 当前组件的初始值。 | any | – | |
option.normalize | 返回标准化处理后的值。 | (value, prev, all): Object | – | |
option.trigger | 收集表单数据的时机。 | String | ‘onChange’ | |
option.validateTrigger | 监听验证的事件。 设置为 false 仅在调用props.validateFields 时验证。 |
String | String[] | ‘onChange’ |
option.rules | 验证规则。 详见: async-validator | Object[] | – | |
option.validateFirst | 当某一规则校验不通过时,是否停止剩下的规则的校验 | boolean | false | |
option.validate | Object[] | – | ||
option.validate[n].trigger | 同 option.validateTrigger |
String | String[] | ‘onChange’ |
option.validate[n].rules | 同 option.rules |
Object[] | – | |
option.hidden | 在验证或获取字段时忽略当前字段 | boolean | false | |
option.preserve | 即便字段不再使用,也保留该字段的值 | boolean | false |
getValueFromEvent
的默认值
function defaultGetValueFromEvent(e) {
if (!e || !e.target) {
return e;
}
const { target } = e;
return target.type === 'checkbox' ? target.checked : target.value;
}
技巧
{
validateTrigger: 'onBlur',
rules: [{required: true}],
}
// 是以下的简化
{
validate: [{
trigger: 'onBlur',
rules: [{required: true}],
}],
}
getFieldDecorator(name:String, option: Object) => (React.Node) => React.Node
和 getFieldProps
一样, 但添加一些帮助警告,你可以直接在React.Node道具中编写onXX:
<form>
{getFieldDecorator('name', otherOptions)(<input />)}
</form>
getFieldsValue([fieldNames: String[]])
通过字段名来获取该字段的值。
getFieldValue(fieldName: String)
通过字段名来获取该字段的值。
getFieldInstance(fieldName: String)
通过字段名来获取对应输入框组件的实例。
setFieldsValue(obj: Object)
按key-value对象设置字段值。
setFieldsInitialValue(obj: Object)
通过key-value对象设置字段初始值initialValue。用于重置和初始显示值。
setFields(obj: Object)
按kv对象设置字段名。每个字段都可以包含错误和值成员。
validateFields([fieldNames: String[]], [options: Object], callback: (errors, values) => void)
通过fieldNames验证并获取字段值。
和 async-validator中的方法参数是一样的。
同时添加了 force
and scroll
. scroll
和 dom-scroll-into-view’s function parameter 配置
一样.
options.force: Boolean
默认 false。是否验证已验证的字段(由validateTrigger引起)。
getFieldsError(names): Object{ [name]: String[] }
获取输入组件的验证错误。
getFieldError(name): String[]
获取输入组件的验证错误。
isFieldValidating(name: String): Bool
此输入是否有效。
isFieldsValidating(names: String[]): Bool
其中一个输入是否有效。
isFieldTouched(name: String): Bool
其中一个输入值是否已被用户更改。
isFieldsTouched(names: String[]): Bool
其中一个输入值是否已被用户更改。
resetFields([names: String[]])
重置指定的输入。默认为全部。
isSubmitting(): Bool (Deprecated)
表单是否正在提交。
submit(callback: Function) (Deprecated)
原因是提交返回true,在调用callback之后,isSubmitting返回false。
rc-form/lib/createDOMForm(option): Function
createDOMForm 增强, 支持 props.form.validateFieldsAndScroll
validateFieldsAndScroll([fieldNames: String[]], [options: Object], callback: (errors, values) => void)
props.form.validateFields 增强, 支持支持滚动到第一个无效的表单字段
扩
options.container: HTMLElement
默认为表单字段的第一个可滚动容器(直到文档)。
注意
-
不要在Form组件中使用无状态函数组件: https://github.com/facebook/react/pull/6534
-
不能为getFieldProps的validateTrigger / trigger值设置相同的prop名称
<input {...getFieldProps('change',{
onChange: this.iWantToKnow // you must set onChange here or use getFieldDecorator to write inside <input>
})}>
- 你不能使用getFieldProps设置
ref
字段
<input {...getFieldProps('ref')} />
this.props.form.getFieldInstance('ref') // use this to get ref
或者
<input {...getFieldProps('ref',{
ref: this.saveRef // use function here or use getFieldDecorator to write inside <input> (only allow function)
})} />
测试案例
npm test
npm run chrome-test
覆盖
npm run coverage
open coverage/ dir