react-easyform

A Higher Order Component to build form &input, support validators.
一个 React 高阶组件（HOC），用来方便的创建表单，支持各类表单验证，支持异步验证。

react-easyform 已经停止维护，请切换到 react-formutil

功能特色 & Features

• 使用简便，具有详细的表单校验辅助 html 类名（classname）显示
• 支持单选组、复选组表单
• 支持表单嵌套、组合
• 支持多种表单验证规则，自定义验证信息显示
• 支持异步验证
• 通过内置的表单 easyFieldwrapper 包装器，可以自由定义表单输入项，以支持 easyform

预览

• 在线示例 & Demo
• 完整代码示范

安装 & Installation

 npm install --save react-easyform

开始使用 & Getting started

• 登录表单示例

import React, { Component, PropTypes } from 'react';
import EasyForm, { Field, FieldGroup } from 'react-easyform';

class Form extends Component {
    submit = ev => {
        alert('submit!');
    };

    render() {
        // 经过EasyForm包装的组件，props里会有一个params属性，包含所有的表单项值
        const { params } = this.props.params;
        /*
             * props里的easyform对象，包含了一组验证结果，
             * 其中$invalid/$valid 可以用来判断表单项是够已经正确填写
             */
        const { $invalid } = this.props.easyform.$invalid;

        return (
            <form className="" onSubmit={this.submit}>
                <Field
                    type="text"
                    name="username"
                    required
                    pattern={/^[\w]{5,10}$/}
                    validMessage={{ required: '请填写用户名', pattern: '用户名不能包含字母数字下划线以外的字符' }}
                />
                <Field type="text" name="password" required validMessage={{ required: '请填写密码' }} />
                <button className="btn-submit" disabled={$invalid ? 'disabled' : false}>
                    提交
                </button>
            </form>
        );
    }
}

export default EasyForm(Form);

• 单选、复选、下拉等示例

import React, { Component, PropTypes } from 'react';
import EasyForm, { Field, FieldGroup } from 'react-easyform';

class Form extends Component {
    submit = ev => {
        alert('submit!');
    };

    render() {
        // 经过EasyForm包装的组件，props里会有一个params属性，包含所有的表单项值
        const { params } = this.props.params;
        /*
             * props里的easyform对象，包含了一组验证结果，
             * 其中$invalid/$valid 可以用来判断表单项是够已经正确填写
             */
        const { $invalid } = this.props.easyform.$invalid;

        return (
            <form className="" onSubmit={this.submit}>
                <div>性别</div>
                <FieldGroup type="radio" name="sex" required validMessage={{ required: '请选择性别' }}>
                    <Field label="男" value="0" />
                    <Field label="女" value="1" />
                </FieldGroup>
                <FieldGroup
                    type="checkbox"
                    name="hobbies"
                    required
                    minLength="2"
                    validMessage={{ required: '请选择你的爱好', minLength: '至少选择两个爱好' }}>
                    <Field label="篮球" value="0" />
                    <Field label="足球" value="1" />
                    <Field label="乒乓球" value="2" />
                    <Field label="羽毛球" value="3" />
                </FieldGroup>
                <button className="btn-submit" disabled={$invalid ? 'disabled' : false}>
                    提交
                </button>
            </form>
        );
    }
}

export default EasyForm(Form);

文档 API & Documention

• EasyForm {Function}

  高阶组件包装器，你的表单组件需要使用该方法包装后返回。

  /**
   * EasyForm
   *
   * @param {Component} WrapperComponent 需要被包装的页面表单组件
   * @param {Number} errorLevel 错误显示级别，默认为1
   *     0: 关闭
   *     1: focus时显示
   *     2: dirty有改动时显示
   *     3: 总是显示
   * @return {HOC} 返回包装后的高阶组件
   */
  class MyFormContainer extends React.Component {
      render() {
          return <div />;
      }
  }
  
  //导出时需要使用 EasyForm 包装下
  export default EasyForm(MyFormContainer, 1);

  返回的高阶组件，props 里会被注入两个属性：

  • easyform EasyForm 的表单实例，保存了验证结果、表单项值、每个表单项的引用等
  • params 一个快捷访问表单参数的对象（easyform 对象下也有该值）

• Field {High Order React-Component}

  表单项高阶组件，支持 React 对 form 输入项节点的所有属性，例如defaultValue type onChange等；也支持各种事件绑定。

      <Field type="password" placeholder="请输入密码" onChange={this.onChange} />
      <Field type="password" placeholder="请输入密码" onFocus={this.onFocus} defaultValue="12345" />
      <Field type="select" placeholder="请选择性别">
          <option value="">请选择</option>
          <option value="0">女</option>
          <option value="1">男</option>
      </Field>
      <Field type="radio" label="单选项描述这里传入" />
      <Field type="checkbox" label="复选项描述这里传入" />
      <Field type="search" />
      <Field type="textarea" />

  有几点需要注意：

  • 如果是单选或者复选，label 必须通过属性 label 传入
  • 如果有默认值，要使用 defaultValue 传入，如果使用 value 也会导致组件成为一个受限组件（controlled components）
  • 下拉框，也要通过 Field 高阶组件创建，指定 type="select" 即可
  • textarea，同样，指定 type="textarea" 即可

  使用 Field 生成的节点，会包含一组 easyform 验证结果 classname：

      <div class="form-group">
          <input type="password" placeholder="请输入密码"
              class="form-control ef-valid ef-invalid ef-dirty ef-touched ef-focusing ef-error-required ef-error-minLength" />
      </div>

  上面即为生成的节点结构，其中 input 父级容器会包含默认的 form-group classname，以及你通过 Field 传入的 classname。input 节点上会包含一个固定的 form-control classname，以及一组其他的值：

  • ef-dirty
  • ef-touched
  • ef-invalid
  • ef-valid
  • ef-focusing
  • ef-error-required
  • ef-error-pattern
  • ef-error-minLength
  • ... more

  具体可以参看示例 demo

• FieldGroup {High Order React-Component}

  表单项组，暂时只支持 单选和复选。

      <h3>性别</h3>
      <FieldGroup type="radio" name="sex">
          <Field label="女" value="0" />
          <Field label="男" value="1" />
      </FieldGroup>
  
      <h3>爱好</h3>
      <FieldGroup type="checkbox" name="hobbies">
          <Field label="篮球" value="0" />
          <Field label="足球" value="1" />
          <Field label="乒乓球" value="2" />
          <Field label="羽毛球" value="3" />
      </FieldGroup>

  其中 type 和 name 值必须传入。type 只能为 radio和checkbox。

• 表单校验 & Validators

  暂时支持以下几种校验：

  • required
  • pattern {RegExp | Function} 可以是正则或者一个函数，返回 bool。通过传入函数可以实现各种复杂校验需求
  • confirm 一致性检测，例如二次密码确认。值为其他表单项的引用，例如 confirm={this.refs.password}
  • minLength 支持FieldGroup
  • maxLength 支持FieldGroup
  • min
  • max

  异步校验

  • asyncValidator 函数返回 promise

开发 & develop

$ git clone git@github.com:qiqiboy/react-easyform.git
$ cd react-easyform/
$ npm install
$ npm start