写在前面
最近在看掘金小册Vue.js组件精讲时，自己也有跟着一起操练，在写一个具有校验功能的组件时有用到async-validator，在学习如何使用这个库时，感觉他的使用说明有一些晦涩，网上又没有很好的中文文档，便按照自己的理解做了一份用法指南。
基础用法——同步用法
import Schema from 'async-validator';
const descriptor = {
// name字段的校验规则
name: {
type: "string",
required: true,
validator(rule, value) {
return value === "muji"
},
message: "输入错误"
}
};
const validator = new Schema(descriptor);
validator.validate({ name: "muji" }, (errors, fields) => {
if (errors) {
// 校验不通过 do something
return;
}
// 校验通过 do something
});
涉及API
validator
指定的字段自定义同步校验函数
validator(rule, value, callback) {
// 设定校验规则，返回true则通过，反之不通过
return value === "muji"
// 当校验失败时，也可以返回一个Error对象，此时失败的提示信息为Error参数
return new Error(`${value} is not equal to 'test'.`);
// 此时校验错误提示信息为 muji is not equal to 'test'
}
//rule参数为一个对象，包含校验字段的信息以及校验规则
{
field: "name", // 字段名称
fullField: "name",
message: "输入错误", // 校验失败时的提示信息
required: true, // 是否必选
type: "string", // 是否为string类型
validator: ƒ validator(rule, value, callback)
}
// value 字段的值
"muji"
// callback 回调函数
Validate
function(source, [options], callback): Promise
source: 需要校验的对象（必选）。options: 描述校验的处理选项的对象（可选）。callback: 当校验完成时调用的回调函数（必选）
该方法将返回一个 Promise 对象，如下:
then()，校验通过catch({ errors, fields })，校验失败，errors 是一个所有 error 组成的数组；field 是一个对象，键是 field，值是对应的 errors 数组。
// callback参数解析 共两个参数
(errors, fields) => {}
// errors 校验失败时返回一个所有 error 组成的数组,[{message: "输入错误", field: "name"}]，校验成功则errors值为null
// fields 校验失败时返回一个对象,{name:[{message: "输入错误", field: "name"}]},校验成功则fileds值为null
基础用法——异步用法
import Schema from 'async-validator';
const descriptor = {
age: {
type: "number",
asyncValidator(rule, value) {
return new Promise((resolve, reject) => {
if (value < 18) {
// reject 不通过校验，reject返回的信息为校验未通过的提示
reject("too young")
} else {
// resolve 通过校验
resolve()
}
})
}
}
}
const validator = new Schema(descriptor)
validator
.validate({ age: 16 })
.then(() => {
// 验证通过 do something
})
.catch(({ errors, fields }) => {
// 验证未通过 do something
})
涉及API
asyncValidator
指定字段自定义异步校验函数
// 参数同validator
asyncValidator(rule, value) {
return new Promise((resolve, reject) => {
if (value < 18) {
// reject 不通过校验，reject返回的信息为校验未通过的提示
reject("too young")
} else {
// resolve 通过校验
resolve()
}
})
}
// ajax异步调用
asyncValidator(rule, value, callback) {
ajax({
url: 'xx',
value: value,
}).then(function(data) {
callback();
}, function(error) {
callback(new Error(error));
});
}
其余API解读
Messages
校验不通过时的错误提示
- 可以直接是字符串
{
name: {
type: 'string',
required: true,
message: '请填写名称'
}
}
- 可以是jsx格式
{
name: {
type: 'string',
required: true,
message: '<b>请填写名称</b>'
}
}
- 可以是一个函数
{
name: {
type: 'string',
required: true,
message(){
// do something
}
}
}
Transform
在校验之前对值进行处理，将处理后的值返回进行校验
{
name: {
type: 'string',
required: true,
pattern: /^[a-z]+$/,
transform(value) {
// do something
return value.trim()
}
}
}
Options
针对validate等涉及到options选项的内部参数，可进行的配置如下
-
suppressWarning: Boolean，指示是否取消关于无效值的内部警告。 -
first: Boolean，当第一个校验规则产生error时调用callback，不再继续处理校验规则。如果校验涉及多个异步调用（例如数据库查询） ，且只需要第一个error出现时就停止，则使用此选项。 -
firstFields: Boolean|String[], 当指定字段的第一个校验规则产生error时调用callback，不再继续处理相同字段的校验规则。true意味着所有字段生效。
validator.validate(
{ name: "muj" },
// 在此处配置options
{
suppressWarning: true
},
(errors, fields) => {
if (errors) {
// 校验不通过 do something
return
}
// 校验通过 do something
}
)
Rules
执行校验的函数
function(rule, value, callback, source, options)
rule: 在源descriptor中，与要校验的字段名称相对应的校验规则。始终为它分配一个field属性，其中包含要验证的字段的名称。value: 源对象属性中要校验的值。callback: 校验完成后要调用的callback。它期望传递一个Error实例数组以指示校验失败。如果校验是同步的，则可以直接返回false、Error或Error Array。source: 传给validate方法的源对象。options: 额外选项。
用法一
{
// 可以把它看出校验规则的另外一种写法，最开始的是对象形式
name(rule, value, callback, source, options) {
const errors = []
if (value != "muji") {
errors.push("错误")
}
return errors
}
}
用法二
// 多个校验规则校验一个规则
{
name: [
{
type: "string",
required: true,
validator(rule, value) {
return value === "muji"
},
transform(value) {
return value + "i"
},
message: "输入错误"
},
{
validator(rule, value, callback, source, options) {
const errors = []
if (value.length < 10) {
errors.push("长度不够")
}
// 当符合第一个规则之后，才会进行后面的校验
return ["errors"]
}
}
]
}
type
标志要使用的validator的type，可识别的type值为:
string: 必须为类型string， 这是默认的 type。number: 必须为类型number。boolean: 必须为类型boolean。method: 必须为类型function。regexp: 必须为RegExp的实例 或者 一个string，使用它 newRegExp时不能报错。integer: 必须为类型number并且是一个整数。float: 必须为类型number并且是一个浮点数。array: 必须是一个array，由Array.isArray确定。object: 必须为类型object并且Array.isArray返回false。enum: 值必须在enum中存在。date: 值必须是有效的，由Date确定。url: 必须为类型url。hex: 必须为类型hex。email: 必须为类型email。any: 可以是任意一种类型。
Required
rule属性required指示在校验时该field必须在source对象上存在
Pattern
rule属性pattern指示在校验时该值必须能通过正则表达式的校验。
Range
使用 min 和 max 属性定义范围。对于string和array类型，根据length属性进行比较，对于number类型，数字不能小于 min，也不能大于 max。
Length
若要校验field的精确长度，请指定 len 属性。对于string和array类型的比较是在length属性上执行的，对于number类型，这个属性表示数字的精确匹配，也就是说，它只能严格等于 len。
如果 len 属性与 min 和 max 两个 range 属性组合使用，len 优先。
Enumerable
从 3.0.0 版本开始，如果想校验> enum类型中的值> 0或 > false，就必须显式地包含它们。
要校验 所有可能值组成的列表 中的值，使用enum类型和enum属性列出该字段的有效值，例如:
const descriptor = {
role: { type: 'enum', enum: ['admin', 'user', 'guest'] },
};
