react-material-formutil
Happy to use react-formutil in the project based on Material-UI
^_^
已迁移至
react-mui-formmutil
,支持最新的@mui/material
5.x版本。
在 Material-UI 项目,结合react-formutil 来快速构建表单。
如果你在使用其他 react-组件库,可以查阅:
- ant-design
react-antd-formutil
![]()
- react-bootstrap
react-bootstrap-formutil
![]()
- react-md
react-md-formutil
![]()
安装 Installation
# npm
npm install react-material-formutil --save
# yarn
yarn install react-material-formutil
使用 Usage
react-material-formutil
整合了react-formutil
的组件,所以可以直接从react-material-formutil
中导出所需要的react-formutil
组件。不用单独从react-formutil
中导出。
先看一个使用示例(点击查看在线完整示例 : react-material-formutil on codesandbox.io):
import React, { Component } from 'react';
import { withForm, FormControl } from 'react-material-formutil';
import TextField from '@material-ui/core/TextField'; // 导入mui的TextField组件
@withForm
class MyForm extends Component {
submit = () => {
const { $invalid, $getFirstError, $params } = this.props.$formutil;
if ($invalid) {
alert($getFistError());
} else {
// submit your data
}
};
render() {
return (
<form onSubmit={this.onSubmit}>
<FormControl name="username" required>
<TextField label="Username" />
</FormControl>
</form>
);
}
}
FormControl
是 react-material-formuitl
新增加的组件,withForm
是react-formutil
的组件(没错,你可以直接从react-material-formutil
中导出react-formutil
的组件啦)。
只需要将material-ui
的交互组件,嵌套在FormControl
下,即可实现自动的表单状态同步。
<FormControl />
要实现将material-ui
的交互组件的值能同步到 react-formutil
的状态中,需要通过 FormControl
这个组件来实现中间态绑定。
FormControl
类似material-ui
中的同名组件,但是它基于react-formutil
实现了表单状态的收集与同步,并对Checkbox
Radio
Switch
Select
Input
等做了兼容,并且也提供了类似material-ui
中同名组件的同样的 UI 层面功能。
FormControl
下只允许放置一个表单组件,不允许多个。
name
设置输入项的 name 值,表单项将会以 name 作为 key 收集到 formutil 的状态中。支持嵌套语法 (同react-formutil
的Field
同名参数,可以参考 name)
$defaultValue
设置该表单项的默认值 (同react-formutil
的Field
同名参数,可以参考$defaultvalue)
$validators
设置校验方法 (同react-formutil
的Field
同名参数 , 可以参考
$validators)
同 react-formutil 的 EasyField,FormControl 也内置了同样的校验规则:
required
必填required
maxLength
。最大输入长度,有效输入时才会校验maxLength="100"
minLength
最小输入长度,有效输入时才会校验minLength="10"
max
最大输入数值,仅支持 Number 比较。有效输入时才会校验max="100"
min
最小输入数值,仅支持 Number 比较。有效输入时才会校验min="10"
pattern
正则匹配。有效输入时才会校验pattern={/^\d+$/}
enum
枚举值检测。有效输入时才会校验enum={[1,2,3]}
checker
自定义校验函数。checker={value => value > 10 && value < 100 || ' 输入比如大于 10 小与 100'}
注:校验属性的值为 null
时表示不进行该校验
内置的校验规则无需再次声明,除非规则不符合预期,需要替换,则可以通过$validators
传递同名校验方法即可替换默认的。另外,内置的校验规则,如果校验不通过,会尝试去 validMessage
匹配错误信息。
controlProps
该属性为要传递给material-ui
中的FormControl
组件的配置项。如果使用TextField
,则会传递给TextField
组件:
<FormControl
controlProps={{
fullWidth: true
}}>
<Input />
</FormControl>
label
设置 label,如果传入字符串,会自动应用InputLabel
:
<FormControl name="name" label="Username">
<Input />
</FormControl>
//or
<FormControl name="name" label={<InputLabel>Username</InputLabel>}>
<Input />
</FormControl>
helperText
设置 helperText,如果传入字符串,会自动应用FormHelperText
:
<FormControl name="name" helperText="Please type your name">
<Input />
</FormControl>
//or
<FormControl name="name" helperText={<FormHelperText>Please type your name</FormHelperText>}>
<Input />
</FormControl>
$parser
设置输入的值收集到 formutil 状态中时的过滤处理。默认为value => value
<FormControl $parser={value => parseInt(value)}>
<Input />
</FormControl>
$formatter
设置 formutil 中的值渲染到输入组件上时的过滤处理。默认为value => value
<FormControl $formatter={value => '$' + value}>
<Input />
</FormControl>
checked
unchecked
对于 <Switch />
<Checkbox />
<Radio />
这三种组件,其值默认是 checked 属性,为布尔值。可以通过checked
unchecked
来设置 checked 状态时所要映射的值:
<FormControl checked="yes" unchecked="no">
<Switch />
</FormControl>
该示例中, 当 Switch 为开时,获取的值将为 yes。
validMessage
设置校验结果的错误信息。
<FormControl
name="username"
required
validMessage={{
required: '请输入用户名'
}}>
<Input />
</FormControl>
valuePropName
changePropName
focusPropName
blurPropName
该四个参数可以用来设置绑定到组件上的值或者值变动、是否聚焦等事件回调。该项一般不需要设置,FormControl
已经针对 material-ui
中的所有 data-entry
型组件做了兼容处理。
对于一些特殊场景,例如不需要同步 focus
、blur
,则可以通过将该值设为{null}
来禁用:
//禁用focus、blur状态同步
<FormControl focusPropName={null} blurPropName={null} name="username">
<Input />
</FormControl>
errorLevel
用来覆盖全局的 errorLevel 设置。参考setErrorLevel(level)
setErrorLevel(level)
setErrorLevel
该方法可以用来全局设置错误信息何时出现,有三个级别可以设置:
-
0
当$dirty
$touched
invalid
都为 true 时 -
1
当$dirty
invalid
都为 true 时 -
2
当invalid
为 true 时
默认值为 1
import { setErrorLevel } from 'react-antd-formutil';
setErrorLevel(0);
支持的组件
TextField
<FormControl name="name">
<TextField label="Name" margin="normal" />
</FormControl>
Select
<FormControl name="age">
<Select>
<MenuItem value="">
<em>None</em>
</MenuItem>
<MenuItem value={10}>Ten</MenuItem>
<MenuItem value={20}>Twenty</MenuItem>
<MenuItem value={30}>Thirty</MenuItem>
</Select>
</FormControl>
NativeSelect
<FormControl name="age">
<NativeSelect>
<option value="" />
<option value={10}>Ten</option>
<option value={20}>Twenty</option>
<option value={30}>Thirty</option>
</NativeSelect>
</FormControl>
Input
<FormControl name="name">
<Input />}
</FormControl>
Checkbox
<FormControl name="agree">
<Checkbox />}
</FormControl>
Radio
<FormControl name="agree">
<Radio />}
</FormControl>
Switch
<FormControl name="agree">
<Switch />}
</FormControl>
FormControlLabel
FormControlLabel
必须配合Checkbox
Radio
Switch
其一一起用:
<FormControl name="agree">
<FormControlLabel control={<Checkbox />} />
</FormControl>
<FormControl name="agree">
<FormControlLabel control={<Radio />} />
</FormControl>
<FormControl name="agree">
<FormControlLabel control={<Switch />} />
</FormControl>
DatePicker
日期、时间选择,依赖于外部库material-ui-pickers
TimePicker
日期、时间选择,依赖于外部库material-ui-pickers
DateTimePicker
日期、时间选择,依赖于外部库material-ui-pickers
FAQ
给组件设置的 onChange、onFocus 等方法无效、不执行
FormControl
会覆盖掉直接添加到 material-ui
组件上的onFocus
onBlur
onChange
方法,所以如果需要这三个事件方法,需要添加到
FormControl
上:
<FormControl name="test" onChange={ev => console.log('change', ev)} onFocus={ev => console.log('focus', ev)}>
<Input />
</FormControl>