validation
yolain/validation 是一款非常易用的JavaScript验证器,它的使用方式类似于PHP里Laravel Validation,它可以帮助我们更高效的验证表单和请求对象的规则。
我们从 Validatorjs Fork了下来,在不改动原始逻辑的前提下做了些输出错误的调整,以便我们更好地进行开发。
为什么使用验证器?
- 不依赖任何库
- 在浏览器和Nodejs中都可以工作
- 可读和声明性验证规则
- 支持多语言错误消息
- AMD公司/要求.js以及CommonJS/Browserify支持
安装
使用npm
npm install @yolain/validation
使用yarn
yarn add @yolain/validation
浏览器使用
<script src="validator.js"></script>
Node.js / Browserify
// ES5
let Validator = require('@yolain/validation');
// ES6
import Validator from '@yolain/validation';
基础使用
let validation = new Validator(data, rules ,[customErrorMessages]);
data {Object} - 传入你要验证的对象
rules {Object} - 验证规则对象
customErrorMessages {Object} - (可选)自定义错误信息返回
案例1 - 通过验证
let data = {
name: 'John',
email: 'johndoe@gmail.com',
age: 28
};
let rules = {
name: 'required',
email: 'required|email',
age: 'min:18'
};
let validation = new Validator(data, rules);
validation.passes(); // true
validation.fails(); // false
若要将验证规则应用于 data 对象,请在 rule 对象下使用相同的键名。
案例2 - 验证失败的处理
let validation = new Validator({
name: 'D',
email: 'not an email address.com'
}, {
name: 'size:3',
email: 'required|email'
},{
name:'姓名',
email:'邮箱地址'
});
validation.fails(); // true
validation.passes(); // false
// 返回错误的文案 (原始)
validation.errors.first('email'); // '邮件格式不正确'
validation.errors.get('email'); // 返回一个所有邮件格式错误的数组
// 💡 返回错误的文案 (新增)
validation.errors.first(); // '姓名的长度必须等于3' <- 返回第一个出错的文案
validation.errors.all(true); // ['姓名的长度必须等于3','邮箱地址格式不正确'] <- 返回所有出错的文案数组
嵌套规则
嵌套对象同样可以进行校验, 有两种方法可以声明嵌套对象的验证规则。第一种方法是使用反映数据的相应嵌套对象结构来声明验证规则。第二种方法是用扁平化的键名声明验证规则。例如,要验证以下数据:
let data = {
name: 'John',
bio: {
age: 28,
education: {
primary: '小学',
secondary: '中学'
}
}
};
我们可以声明我们的验证规则如下:
let nested = {
name: 'required',
bio: {
age: 'min:18',
education: {
primary: 'string',
secondary: 'string'
}
}
};
// OR
let flattened = {
'name': 'required',
'bio.age': 'min:18',
'bio.education.primary': 'string',
'bio.education.secondary': 'string'
};
通配符规则
通配符也可以进行校验
let data = {
users: [{
name: 'John',
bio: {
age: 28,
education: {
primary: '小学',
secondary: '中学'
}
}
}]
};
我们可以声明我们的通配符规则如下:
let rules = {
'users.*.name': 'required',
'users.*.bio.age': 'min:18',
'users.*.bio.education.primary': 'string',
'users.*.bio.education.secondary': 'string'
};
可使用的规则
验证规则没有隐式 'required',如果字段是 undefined 或空字符串,则它将通过验证,如果希望未定义或“”的验证失败,请使用 required 规则
accepted
验证的字段必须是yes、on、1或true。这对于验证“服务条款”的接受是很有用的
after:date
验证的字段必须在给定日期之后
after_or_equal:date
验证的字段必须在给定日期之后或当天
alpha
验证的字段必须完全是字母字符
alpha_dash
验证的字段只能包含字母或数字,以及破折号和下划线
alpha_num
验证的字段必须完全是字母数字字符
array
验证的字段必须是数组
before:date
验证的字段必须在给定日期之前。
before_or_equal:date
验证的字段必须早于或当天
between:min,max
验证的字段的大小必须介于给定的最小值和最大值之间。字符串、数字和文件的计算方式与大小规则相同
boolean
验证的字段必须是形式为 true、false、0、1、"true”、“false”、“0”、“1” 的布尔值
confirmed
验证字段必须有一个匹配的 foo_confirmation 字段。例如,如果验证下的字段是 password,则输入中必须存在匹配的 password_confirmation 字段
date
验证字段必须是Javascript “date” 对象的有效日期格式
digits:value
验证字段必须是数字,并且必须具有精确的值长度
digits_between:min,max
验的字段必须是数字,并且长度必须介于给定的最小值和最大值之间
different:attribute
给定字段必须与验证字段不同
验证字段的格式必须为电子邮件地址
hex
验证字段应为十六进制格式。与其他规则(如hex)结合使用时非常有用 hex|size:6
用于十六进制颜色代码验证。
in:foo,bar,...
验证字段必须包含在给定的值列表中,该字段可以是数组或字符串
integer
验证字段必须为整数值。
max:value
验证值不能超过给定大小
Note: Maximum checks are inclusive.
min:value
验证值不能少于给定大小
Note: Minimum checks are inclusive.
not_in:foo,bar,...
验证字段不能包含在给定的值列表中
numeric
验证值是否为数值,数字的字符串表示将通过
present
验证字段必须存在于输入数据中,但可以为空
required
验证字段必须存在于输入数据中,且不可以为空
required_if:anotherfield,value
如果另一个字段等于任何值,则验证的字段必须存在且不为空
required_unless:anotherfield,value
验证的段必须存在且不为空,除非另一个字段等于任何值
required_with:foo,bar,...
只有在其他指定字段存在时,验证的字段必须存在且不为空
required_with_all:foo,bar,...
只有当所有其他指定字段都存在时,验证的字段必须存在且不为空
required_without:foo,bar,...
只有在任何其他指定字段不存在时,验证的字段必须存在且不为空
required_without_all:foo,bar,...
只有当所有其他指定字段都不存在时,验证的字段必须存在且不为空
same:attribute
给定字段必须与验证字段匹配
size:value
验证字段的大小必须与给定值匹配
string
验证字段必须是字符串。
url
验证属性是否具有有效的URL格式
regex:pattern
验证字段必须与给定的正则表达式匹配
注意:使用“regex”模式时,可能需要在数组中指定规则,而不是使用 "|" 分隔符,尤其是当正则表达式包含 "|" 字符时。
对于正则表达式模式中使用的每个反斜杠,必须用另一个反斜杠对每个反斜杠进行转义。
案例3 - 正则表达式验证
let validation = new Validator({
name: 'Doe',
salary: '10,000.00',
yearOfBirth: '1980'
}, {
name: 'required|size:3',
salary: ['required', 'regex:/^(?!0\\.00)\\d{1,3}(,\\d{3})*(\\.\\d\\d)?$/'],
yearOfBirth: ['required', 'regex:/^(19|20)[\\d]{2,2}$/']
});
validation.fails(); // false
validation.passes(); // true
案例4 - 类型检查验证
let validation = new Validator({
age: 30,
name: ''
}, {
age: ['required', { 'in': [29, 30] }],
name: [{ required_if: ['age', 30] }]
});
validation.fails(); // true
validation.passes(); // false
注册自定义的验证规则
Validator.register(name, callbackFn, errorMessage);
name {String} - 规则名称
callbackFn {Function} - 回调函数返回表示验证成功或失败的布尔值。
errorMessage {String} - 一个可选字符串,您可以在其中指定自定义错误消息。:attribute 在errorMessage中将替换为属性名称。
Validator.register('telephone', function(value, requirement, attribute) { // requirement parameter defaults to null
return value.match(/^\d{3}-\d{3}-\d{4}$/);
}, 'The :attribute phone number is not in the format XXX-XXX-XXXX.');
异步验证
注册接受“passes”回调的异步规则:
Validator.registerAsync('username_available', function(username, attribute, req, passes) {
// do your database/api checks here etc
// then call the `passes` method where appropriate:
passes(); // if username is available
passes(false, 'Username has already been taken.'); // if username is not available
});
然后使用 checkAsync
通过failes
和passes
回调调用验证器,如下所示:
let validator = new Validator({
username: 'test123'
}, {
username: 'required|min:3|username_available'
});
function passes() {
// Validation passed
}
function fails() {
validator.errors.first('username');
}
validator.checkAsync(passes, fails);
错误信息
构造函数将为失败的验证规则自动生成错误消息。
如果有错误,验证器实例将会把所有验证失败的错误消息添加到 errors 对象中。 errors 对象可使用的方法和属性有以下:
not required
)
.first(attribute 返回第一条错误消息,否则为false
.get(attribute)
返回属性的错误消息数组,如果没有错误,则返回空数组
Boolean
)
.all(full 返回一个包含所有错误消息的对象
.has(attribute)
如果属性存在错误消息,则返回true,否则返回false
.errorCount
验证错误数
let validation = new Validator(input, rules);
// 返回错误的文案 (原始)
validation.errors.first('email'); // '邮件格式不正确'
validation.errors.get('email'); // 返回一个所有邮件格式错误的数组
// 返回错误的文案 (新增)
validation.errors.first(); // '姓名的长度必须等于3' <- 返回第一个出错的文案
validation.errors.all(true); // ['姓名的长度必须等于3','邮箱地址格式不正确'] <- 返回所有出错的文案数组
自定义错误信息
如果您需要一个特定的错误消息,并且不想重写默认的错误消息,那么可以覆盖第三个参数传递给Validator对象,就像 Laravel.
let input = {
name: ''
};
let rules = {
name : 'required'
};
let validation = new Validator(input, rules, { required: 'You forgot to give a :attribute' });
validation.errors.first('name'); // returns 'You forgot to give a name'
一些验证器字段需要配置 string 和 numeric,你同意可以这样覆盖它
let input = {
username: 'myusernameistoolong'
};
let rules = {
username : 'max:16'
};
let validation = new Validator(input, rules, {
max: {
string: 'The :attribute is too long. Max length is :max.'
}
});
validation.errors.first('username'); // returns 'The username is too long. Max length is 16.'
您甚至可以根据每个属性提供错误消息!只需将消息的键设置为'验证器.属性'
let input = { name: '', email: '' };
let rules = { name : 'required', email : 'required' };
let validation = new Validator(input, rules, {
"required.email": "Without an :attribute we can't reach you!"
});
validation.errors.first('name'); // returns 'The name field is required.'
validation.errors.first('email'); // returns 'Without an email we can\'t reach you!'
New 新增 +
上述方式并不能很好的运用于实际项目中,于是我们新增了只需根据'属性'就可以更改错误信息的方式。
通过 '属性':'需要被替换的:attribute名称' 输出错误,参考如下:
let input = { name: '小明', email: 'a@test.com' };
let rules = { name : 'required', email : 'required|email' };
let validation = new Validator(input, rules, {
"email": "邮箱地址"
});
validation.errors.first(); // 返回'邮箱地址格式不正确'
当然我们也可以通过 '属性':{'验证属性':'自定义错误文案','text':'其他属性被替换的:attribute名称''} 输出错误,参考如下:
let input = { name: '小明', email: 'a@test.com' };
let rules = { name : 'required', email : 'required|min:8|email' };
let validation = new Validator(input, rules, {
"email":{min:'Email长度不符合',text:'邮箱地址'}
});
validation.errors.all(true); // 返回 ['Email长度不符合','邮箱地址格式不正确']
自定义属性名称
要在错误消息中显示自定义的“友好”属性名,请使用.setAttributeNames()
let validator = new Validator({ name: '' }, { name: 'required' });
validator.setAttributeNames({ name: 'custom_name' });
if (validator.fails()) {
validator.errors.first('name'); // "The custom_name field is required."
}
或者,您可以使用language中的 “attributes” 属性提供全局自定义属性名。
还可以配置自定义属性格式化程序:
// Configure global formatter.
Validator.setAttributeFormatter(function(attribute) {
return attribute.replace(/_/g, ' ');
});
// Or configure formatter for particular instance.
let validator = new Validator({ first_name: '' }, { first_name: 'required' });
validator.setAttributeFormatter(function(attribute) {
return attribute.replace(/_/g, ' ');
});
if (validator.fails()) {
console.log(validator.errors.first('first_name')); // The first name field is required.
}
注意:默认情况下,所有 _ 的字符都将替换为空格。
多语言支持
默认情况下,错误消息为英语。若要在浏览器中包含其他语言,请在脚本标记中引用该语言文件并调用 Validator.useLang('lang_code')
.
<script src="dist/validator.js"></script>
<script src="dist/lang/ru.js"></script>
<script>
Validator.useLang('es');
</script>
在 Node中它将自动拾取语言源文件
let Validator = require('@yolain/validation');
Validator.useLang('zh');
如果您没有看到对您的语言的支持,请添加一个到src/lang
!
您还可以通过调用setMessages
:
Validator.setMessages('lang_code', {
required: 'The :attribute field is required.'
});
获取给定语言的消息的原始对象:
Validator.getMessages('lang_code');
切换验证器使用的默认语言:
Validator.useLang('lang_code');
获取正在使用的默认语言:
Validator.getDefaultLang(); // returns e.g. 'en'
重写语言的默认消息:
let messages = Validator.getMessages('en');
messages.required = 'Whoops, :attribute field is required.';
Validator.setMessages('en', messages);
License
Copyright © 2012-2019 David Tang Released under the MIT license
Credits
validatorjs created by David Tang validatorjs maintained by Mike Erickson and Contributors
E-Mail: codedungeon@gmail.com
Twitter: @codedungeon
Website: codedungeon.io