Home

Awesome

<p align="center"> <img width="400" src="assets/v2.png" alt="we-validator" /> </p> <p align="center"> <a href="https://travis-ci.org/ChanceYu/we-validator"><img src="https://img.shields.io/travis/ChanceYu/we-validator/master.svg?color=green&style=popout-square" /></a> <a href="https://opensource.org/licenses/mit-license.php"><img src="https://img.shields.io/npm/l/we-validator.svg?color=blue&style=popout-square" /></a> <a href="https://www.npmjs.com/package/we-validator"><img src="https://img.shields.io/npm/v/we-validator.svg?color=green&style=popout-square" /></a> </p>

2.x 和 1.x 版本有所差别,如果您继续使用老版本,可以查看 1.x 版本。如果您要升级到 2.x 请先阅读升级指南,推荐使用 2.x 版本。

简单灵活的表单验证插件,支持小程序、浏览器、Nodejs。小程序端支持:微信、支付宝、百度智能、字节跳动,小程序默认提示使用 showToast

API 文档 | 示例 Examples,如果你 :sparkling_heart: 就点击 ★Star 吧。

特点

安装

使用 npm:

npm install we-validator --save

使用 cdn:

<script src="https://unpkg.com/we-validator/dist/we-validator.min.js"></script>

使用

下面是微信小程序的用法,其它小程序类似

<details open> <summary>点击查看栗子 :chestnut: </summary>
<form bindsubmit="onSubmitForm">
    <input type="text" name="username" placeholder="用户名" />
    <input type="number" name="phoneno" placeholder="手机号" />
    <input type="text" name="str" placeholder="长度为3的字符串" />

    <button type="default" formType="submit">提交</button>
</form>
const WeValidator = require('we-validator')

Page({
    onReady(){
        this.initValidator()
    },
    onSubmitForm(e){
        let { value } = e.detail

        if(!this.validatorInstance.checkData(value)) return

        // 开始提交表单
        // wx.request
    },
    initValidator(){
        // 实例化
        this.validatorInstance = new WeValidator({
            rules: {
                username: {
                    required: true
                },
                phoneno: {
                    required: true,
                    mobile: true
                },
                str: {
                    length: 3
                },
            },
            messages: {
                username: {
                    required: '请输入用户名'
                },
                phoneno: {
                    required: '请输入手机号',
                    mobile: '手机号格式不正确'
                },
                str: { // 非必填字段
                    length: '请输入长度为3的字符串'
                },
            },
        })
    },
})
</details>

Examples

您也可参考当前项目下对应示例

API

Static API

默认支持的规则

注意: 非必填字段只有字段有值才会校验配置的规则

规则描述默认提示
required: true必填此字段必填
pattern: /^\d+$/正则通用不符合此验证规则
email: true电子邮件格式请输入有效的电子邮件地址
mobile: true11位手机号请输入11位的手机号码
tel: true座机号<br>例如:010-1234567、0551-1234567请输入座机号
url: trueURL网址请输入有效的网址
idcard: true身份证号请输入18位的有效身份证
equalTo: 'field'字段值相同校验<br>例如:密码和确认密码,参考输入值必须和字段 field 相同
notEqualTo: 'field'字段值不能相同校验<br>equalTo 相反输入值不能和字段 field 相同
contains: 'str'是否包含某字符输入值必须包含 str
notContains: 'str'不能包含某字符输入值不能包含 str
length: 5长度为多少的字符串请输入 5 个字符
minlength: 2最少多长的字符串最少要输入 2 个字符
maxlength: 6最多多长的字符串最多可以输入 6 个字符
rangelength: [2, 6]某个范围长度的字符串请输入长度在 26 之间的字符
number: true数字请输入有效的数字
digits: true正整数数字只能输入正整数数字
integer: true正整数或负整数数字只能输入整数数字
min: 3大于多少的数字<br>(最小只能多少),也可以比较字段的值,参考请输入大于 3 的数字
max: 9小于多少的数字<br>(最大只能多少),也可以比较字段的值请输入小于 9 的数字
range: [3, 9]大于且小于多少的数字请输入大于 3 且小于 9 的数字
chinese: true中文字符只能输入中文字符
minChinese: 3最少多少个中文字符最少输入 3 个中文字符
maxChinese: 9最多多少个中文字符最多输入 9 个中文字符
rangeChinese: [3, 9]大于且小于多少个中文字符只能输入 39 个中文字符
date: true日期(默认使用 new Date(value) 校验)请输入有效的日期
dateISO: true日期(ISO标准格式)<br>例如:2019-09-19,2019/09/19请输入有效的日期(ISO标准格式)
ipv4: trueipv4地址请输入有效的IPv4地址
ipv6: trueipv6地址请输入有效的IPv6地址

new WeValidator(options)

实例化

返回: <code>object</code> - <code>validatorInstance</code>

参数类型默认值描述
options<code>object</code>
[options.rules]<code>object</code>验证字段的规则
[options.messages]<code>object</code>验证字段错误的提示信息
[options.onMessage]<code>function</code>错误信息显示方式<br>默认会自动检测环境。小程序默认使用showToast<br>普通web浏览器默认使用alert<br>Nodejs端不做处理建议自己配置,详情
[options.multiCheck]<code>boolean</code>false是否校验多个字段<br>需要一次校验多个字段并显示错误信息时使用,详情
<details> <summary>点击查看栗子 :chestnut: </summary>
const WeValidator = require('we-validator')

new WeValidator({
    rules: {
        username: {
            required: true
        },
        phoneno: {
            required: true,
            mobile: true
        }
    },
    messages: {
        username: {
            required: '请输入用户名'
        },
        phoneno: {
            required: '请输入手机号',
            mobile: '手机号格式不正确'
        }
    }
})
</details>

.checkData(data, onMessage)

校验数据,会显示错误信息,校验所有字段规则

返回: <code>boolean</code>

参数类型默认值描述
data<code>object</code>需要校验的表单数据
onMessage<code>function</code>自定义错误信息提示,详情

.checkFields(data, fields, onMessage)

校验数据,会显示错误信息,只校验对应的字段,参考

通常用于单独校验一个或多个字段规则

返回: <code>boolean</code>

参数类型默认值描述
data<code>object</code>需要校验的表单数据
fields<code>array</code>校验的字段规则,必填<br>例如:<br>['phoneNo'] 只校验此字段的所有规则<br>['phoneNo:required'] 只校验此字段的 required 规则<br>['phoneNo:required,mobile'] 只校验此字段的 requiredmobile 规则<br>['phoneNo', 'code'] 只校验这两个字段的所有规则
onMessage<code>function</code>自定义错误信息提示,详情

.isValid(data, fields)

校验数据是否有效,不会提示错误信息

使用场景例如:表单中某些字段校验通过按钮才可点击的场景,参考

返回: <code>boolean</code>

参数类型默认值描述
data<code>object</code>需要校验的表单数据
fields<code>array</code>校验的字段<br>不传,默认校验所有字段规则<br>如果有,只校验对应的字段规则<br>配置方法同 .checkFields(data, fields)

.addRules(options)

动态添加字段校验,参考

参数类型默认值描述
options<code>object</code>new WeValidator(options)详情
<details> <summary>点击查看栗子 :chestnut: </summary>
const WeValidator = require('we-validator')

const validatorInstance = new WeValidator({
    rules: {
        username: {
            required: true
        }
    },
    messages: {
        username: {
            required: '请输入用户名'
        }
    }
})

// 动态添加校验
validatorInstance.addRules({
    rules: {
        phoneno: {
            required: true,
            mobile: true
        }
    },
    messages: {
        phoneno: {
            required: '请输入手机号',
            mobile: '手机号格式不正确'
        }
    }
})
</details>

.removeRules(fields)

动态移除字段校验,参考

参数类型默认值描述
fields<code>array</code>需要移除校验的表单字段
validatorInstance.removeRules(['username'])

WeValidator.addRule(ruleName, ruleOption)

静态方法:添加自定义规则,参考

参数类型默认值描述
ruleName<code>string</code>规则名称
ruleOption<code>object</code>规则配置
[ruleOption.message]<code>string</code>默认错误信息文字<br>可以动态插入参数,例如 请输入长度在 {0} 到 {1} 之间的字符参考
[ruleOption.rule]<code>function|regexp</code>规则校验函数,需要返回一个 boolean<br>也可以直接写一个正则表达式(如果只是正则类型的校验)。
<details> <summary>点击查看栗子 :chestnut: </summary>
const WeValidator = require('we-validator')

// 添加自定义规则(这两种写法一样)
WeValidator.addRule('theRuleName', {
  message: '默认错误信息文字',
  rule(value, param){
    return /\d/.test(value)
  }
})
WeValidator.addRule('theRuleName', {
  message: '默认错误信息文字',
  rule: /\d/
})

// 使用方式一,实例化
new WeValidator({
    rules: {
        field1: {
            theRuleName: true
        }
    },
    messages: {
        field1: {
            theRuleName: '提示信息'
        }
    }
})

// 使用方式二,调用函数
WeValidator.checkValue('theRuleName', 'str')
</details>

WeValidator.checkValue(ruleName, value, param)

静态方法:函数校验

参数类型默认值描述
ruleName<code>string</code>规则名称
value<code>string</code>需要校验的内容
param<code>any</code>传递给规则参数

支持所有默认支持的规则,也支持自定义的规则。

 // 必填
let b1 = WeValidator.checkValue('required', 'str') // true

// 不能小于6的数字
let b2 = WeValidator.checkValue('min', 'str', 6) // false

// 大于2小于5的数字
let b3 = WeValidator.checkValue('range', 'str', [2, 5]) // false

WeValidator.onMessage

自定义错误信息提示

可以全局配置一个,也可以单独配置,非常灵活。

优先级是:.checkData(data, onMessage) > new WeValidator({ onMessage }) > WeValidator.onMessage > 默认检测

默认的消息提示方式:小程序默认使用showToast,浏览器默认使用alert,Nodejs端无处理建议自己配置。

<details> <summary>点击查看栗子 :chestnut: </summary>
const WeValidator = require('we-validator')

// 1、全局配置
WeValidator.onMessage = function(data){
    /*
    data 参数
    {
        msg, // 提示文字
        name, // 表单控件的 name
        value, // 表单控件的值
        param // rules 验证字段传递的参数
    }
    */
}

// 2、实例化配置
new WeValidator({
    rules: {},
    message: {},
    onMessage: function(data){
        alert(data.msg)
    }
})

// 3、验证的时候配置 onMessage(nodejs端校验可以使用此方式)
if(!obj.checkData(formData, onMessage)) return

function onMessage(data){
  alert(data.msg)
}
</details>

多个字段同时校验并显示错误

使用场景如下,注意:当multiChecktrue时,建议使用自定义onMessage参考

we-validator

<details> <summary>点击查看栗子 :chestnut: </summary>
var validatorInstance = new WeValidator({
  multiCheck: true,
  onMessage: function(data){
    console.log(data);
    
    // 根据自己的项目去处理,控制错误信息的显示
  },
  rules: {
      username: {
          required: true
      },
      phoneno: {
          required: true,
          mobile: true
      }
  },
  messages: {
      username: {
          required: '请输入用户名'
      },
      phoneno: {
          required: '请输入手机号',
          mobile: '手机号格式不正确'
      }
  }
});
</details>

Changelog

查看更新日志

Issues

如果您在使用过程中发现 Bug,或者有好的建议,欢迎报告问题

License

license

Copyright (c) 2019 ChanceYu