November: Procrastination Month

    react-material-formutil
    TypeScript icon, indicating that this package has built-in type declarations

    0.0.4 • Public • Published

    react-material-formutil

    npm

    Happy to use react-formutil in the project based on Material-UI ^_^

    Material-UI 项目,结合react-formutil 来快速构建表单。

    如果你在使用其他 react-组件库,可以查阅:

    1. ant-design react-antd-formutil npm
    2. react-bootstrap react-bootstrap-formutil npm
    3. react-md react-md-formutil npm

    安装 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>
            );
        }
    }

    FormControlreact-material-formuitl 新增加的组件,withFormreact-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-formutilField同名参数,可以参考 name

    $defaultValue

    设置该表单项的默认值 (同react-formutilField同名参数,可以参考$defaultvalue

    $validators

    设置校验方法 (同react-formutilField同名参数 , 可以参考 $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 型组件做了兼容处理。

    对于一些特殊场景,例如不需要同步 focusblur,则可以通过将该值设为{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 时
    • 2invalid 为 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>

    Install

    npm i react-material-formutil

    DownloadsWeekly Downloads

    3

    Version

    0.0.4

    License

    ISC

    Unpacked Size

    46.4 kB

    Total Files

    9

    Last publish

    Collaborators

    • qiqiboy