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
使用 Usage
FAQ
- 给组件设置的 onChange、onFocus 等方法无效、不执行

安装 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>

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>

This package has been deprecated