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

0.0.1 • Public • Published

react-am-formutil

npm peerDependencies definitionTypes gzip download issues license github github github github

react-am-formutil

Happy to use react-formutil in the project based on antd-mobile^_^

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

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

  1. ant-design react-antd-formutil npm
  2. react-bootstrap react-bootstrap-formutil npm
  3. react-md react-md-formutil npm
  4. Material-UI react-material-formutil npm

安装 Installation

react-am-formutil

# npm 
npm install react-am-formutil --save
 
# yarn 
yarn install react-am-formutil

使用 Usage

react-am-formutil 整合了 react-formutil 的组件,所以可以直接从react-am-formutil中导出所需要的 react-formutil 组件。不用单独从 react-formutil 中导出。

先看一个简单的示例:

import React, { Component } from 'react';
import { withForm, FormItem } from 'react-am-formutil';
import { List, InputItem } from 'antd-mobile';
 
@withForm
class MyForm extends Component {
    submit = () => {
        const { $invalid, $getFirstError, $params } = this.props.$formutil;
 
        if ($invalid) {
            alert($getFistError());
        } else {
            // submit your data
        }
    };
 
    render() {
        return (
            <form noValidate onSubmit={this.onSubmit}>
                <List>
                    <FormItem name="username">
                        <InputItem />
                    </FormItem>
                </List>
            </form>
        );
    }
}

react-am-formutil提供了一个 FormItem 组件,通过将antd-mobiledata-entry型组件(例如, InputItem、Checkbox.CheckboxItem 等),直接当作 children 传递给该组件,来实现对data-entry型组件的值的捕获与同步。

<FormItem />

antd-mobile的表单型组件,大多数都是结合了其List.Item,所以我们提供的FormItem也会使用List.Item来包装 UI。如果你不希望如此,请直接使用react-formutil提供的EasyField组件即可。

在使用前,需要知晓以下原则:

  • FormItem 应当嵌套放置在<List />组件下方使用。
  • FormItem 不提供额外的错误信息展示,这是因为本身List.Item也没有提供很好的错误信息展示的设计。如果需要对用户展示错误信息提示,应当使用Toast Modal等组件提示。
  • FormItem 提供了额外的am-formutil-xxx的 className 支持,你可以通过这些 classNames 来使用 css 控制表单项的错误反馈显示。

支持传递的属性

FormItem是基于EasyField组件实现的,所以它可以接收所有的EasyField支持的属性;另外它也可以接收一些List.Item或者Checkbox.CheckboxItem等组件的属性(根据嵌套传递的组件变化)。

这里介绍几个和表单处理相关的常用属性:

label

表单项的标题/名字,支持字符串或者 reactNode。需要注意的是,并不是所有的组件都支持label,对于部分组件,例如Slider Range等,该属性是无效的。

<FormItem name="username" label="用户名">
    <InputItem />
</FormItem>
name

设置输入项的 name 值,表单项将会以 name 作为 key 收集到 formutil 的状态中。支持嵌套语法 (同react-formutilField同名参数,可以参考 name

$defaultValue

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

$validators

设置校验方法 (同react-formutilField同名参数, 可以参考 $validators

同 react-formutil 的 EasyField,FormItem 也内置了同样的校验规则:

  • 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 匹配错误信息。

$parser

请参考react-formutil$parser介绍。

$formatter

请参考react-formutil$formatter介绍。

checked unchecked

对于 <Switch /> <Checkbox /> <Radio /> 等组件,其值默认是 checked 属性,为布尔值。可以通过checked unchecked来设置 checked 状态时所要映射的值:

<FormItem checked="yes" unchecked="no">
    <Switch />
</FormItem>

该示例中, 当 Switch 为开时,获取的值将为 yes。

validMessage

设置校验结果的错误信息。

<FormItem
    name="username"
    required
    validMessage={{
        required: '请输入用户名'
    }}>
    <InputItem />
</FormItem>
valuePropName changePropName focusPropName blurPropName

该四个参数可以用来设置绑定到组件上的值或者值变动、是否聚焦等事件回调。该项一般不需要设置,FormItem 已经针对 antd 中的所有 data-entry 型组件做了兼容处理。

对于一些特殊场景,例如不需要同步 focusblur,则可以通过将该值设为{null}来禁用:

//禁用focus、blur状态同步
<FormItem focusPropName={null} blurPropName={null} name="username">
    <InputItem />
</FormItem>
errorLevel

用来覆盖全局的 errorLevel 设置。参考setErrorLevel(level)

setErrorLevel(level)

setErrorLevel 该方法可以用来全局设置错误信息何时出现,有三个级别可以设置:

  • 0$dirty $touched $invalid 都为 true 时
  • 1$dirty $invalid 都为 true 时
  • 2$invalid 为 true 时
  • off 关闭错误显示

默认值为 1

注意,该方法影响全局,如果只是希望单独对某个表单项进行设置,可以通过errorLevel属性进行设置:参考errorLevel

import { setErrorLevel } from 'react-antd-formutil';
 
setErrorLevel(0);
 
// 当关闭错误显示时,errorLevel='off',你可以手动自行设置错误展示方式:
<FormGroup name="errorOff" errorLevel="off">
    <InputItem />
</FormGroup>;

支持的组件

Checkbox Checkbox.CheckboxItem
<FormItem name="agree" label="我同意">
    <Checkbox />
</FormItem>
 
<FormItem name="agree" label="我同意">
    <Checkbox.CheckboxItem />
</FormItem>

小技巧 可以通过传递checked unchecked属性来改变映射到表单中的值

Radio Radio.RadioItem
Switch

Checkbox等用法

DatePicker DatePickerView

DatePicker不需要传递 children 属性:

<FormItem name="date">
    <DatePicker />
</FormItem>

DatePickerView不支持label

<FormItem name="date" label>
    <DatePickerView />
</FormItem>
Picker PickerView

Picker不需要传递 children 属性:

<FormItem name="address">
    <Picker data={data} />
</FormItem>

PickerView不支持label

<FormItem name="address" label>
    <PickerView data={data} />
</FormItem>

小技巧 因为Picker组件总是返回数组值,你可以使用$parser来转换。

InputItem TextareaItem
<FormItem name="password">
    <InputItem type="password" />
</FormItem>
 
<FormItem name="comment">
    <TextareaItem count={200} />
</FormItem>
Slider Range
<FormItem name="age">
    <Slider />
</FormItem>
 
<FormItem name="range">
    <Range />
</FormItem>
Stepper
<FormItem name="amount">
    <Stepper />
</FormItem>

FAQ

给组件设置的onChange、onFocus等方法无效、不执行

FormItem会覆盖掉直接添加到 antd-mobile 组件上的onFocus onBlur onChange方法,所以如果需要这三个事件方法,需要添加到 FormItem上:

<FormItem name="test" onChange={ev => console.log('change', ev)} onFocus={ev => console.log('focus', ev)}>
    <InputItem />
</FormItem>

Package Sidebar

Install

npm i react-am-formutil

Weekly Downloads

29

Version

0.0.1

License

MIT

Unpacked Size

151 kB

Total Files

18

Last publish

Collaborators

  • qiqiboy