qi-validator v0.0.7

验证工具库

本库特点 ：

• 集成验证方法110多项，可覆盖绝大多数数据验证应用场景。
• 链式，简单简洁，可多层级嵌套, 值对象与规则结构的属性一致。
• 内置方法已实现string与number类型互转，无需手动转换。
• 前后端通用，最低支持ES5，使用ES5异步Promise需垫片，无其它依赖库。
• 可拆分使用，仅使用单项正则，或仅使用单项验证方法（见模块引用）。

async-validator（AntD、Element等UI框架集成的）与本库兼容方法处理，见示例

安装：    简单验证     深度验证体验

npm install qi-validator

引用库模块：

import v from 'qi-validator';
// ES5方式 const validator = require('qi-validator').default;
v.validate("dafb", v.string.len(4).min(3)); // true

// 仅使用正则规则集：
import rules from 'qi-validator/es/rules'; 
// ES5方式 const rules = require('qi-validator/lib/rules').default;
rules.password.test('dd3&G_1a');

// 仅使用方法集（含所有正则规则）：
import methods from 'qi-validator/es/methods'; 
// ES5方式 const methods = require('qi-validator/lib/methods');
methods.password('dd3&G_1a');

方法说明

• .get(data, path) 根据路径获取对象数据值。

  例： var obj = {a:1,b:{c:{d:1, d:2}}} , v.get(obj, 'b.c.d.1') // 返回2
  例： var obj = {a:{"b.1":1}} , v.get(obj, 'a','b.1') // 返回1

• .validate(data, struct) 验证数据，使用详见“例子及说明”。

属性说明

• .printout 是否输出验证失败消息（console.warn），默认否。
• .singleMode 同步验证只要有1项不通过就输出结果。默认否，即验证所有项后输出结果。
• .string 字符串验证链式对象。
• .number 数字验证链式对象。
• .object 对象值类型验证链式对象。
• .array 数组值验证链式对象。
• .boolean 布尔值验证链式对象。
• .any 任意类型数据验证链式对象。

链式对象说明：

内置链式对象属性方法见“数据验证规则类型表”
1位参数的规则项：eq、not、gt、gte、lt、lte、len、min、max、charlen、in、has、regexp，例：v.string.eq('foo')
2位参数的规则项：between，例：v.number.between(10,20)
最少1位以上，可变参数的规则项：minof、maxof、enum、and、an、or 例：v.number.minof(2,19,10,20)
无参数的规则项，均为直接使用属性方式：例：v.string.english.upper
链式对象支持所有规则任意搭配，但不建议无意义组合，例：v.string.number
链式对象仅仅是索引，没有实质验证过程，通过v.validate(...)才会生效

• .error(handler:function)，绑定未通过验证的回调函数，用法见示例。
• .ok(handler:function)，绑定已通过验证的回调函数，用法见示例。
• .apply(fnc:function, ...args:any[])，使用自定义方法验证，用法见示例。
• .async(fnc:function, ...args:any[])，使用异步方法验证，将组合同步验证结果。
• .struct(struct:object)，当验证数据为对象或数组，按结构进行分拆及组合验证，见“数据深度验证”示例
• .alias(fieldname:string,...names:string[])，设定数据项、匹对项目的名称，用于格式化消息。
• .msg(key:string|obj, info:string) 自定义消息模板，用法见“消息自定义说明”示例。

例子及说明：

数据验证方式

// 简单的数据验证
v.validate('admin', v.string.enum('admin','user','guest'));  // 返回 true

// 对象深度验证（不限层级），多重组合验证，可使用struct进行组合
v.validate({
  name:'张三', 
  hobby:[ {item:'唱歌' }, {item: '跳舞'} ],
  place:[ { shows:11 }, { shows:5 } ]
}, {
  name: v.string.required.chinese.min(2).alias('姓名'),
  hobby: [, {c: v.any.required.alias('爱好二')} ],
  place: v.array.len(2).alias('出演次数').struct([ 
      {shows: v.number.required.integer}
    ])
}); // 返回 true

// 异步验证（链中如有1项异步，结果均需通过异步才能取得，可通过链中isAsync判断）
const fnc = async (val:number, ...val2:number[]) =>  {
  return await new Promise<boolean>(resolve => {
    setTimeout(() => {
      resolve(val2.length === val)
    }, 500);
  })
}
v.validate(10, v.object.async(fnc, 2)) // 返回 Promise<boolean>
  .then(res => {
    console.log(res); // 返回 true
  })

空白与必填项验证

// 空白数据与必填验证
v.validate('', v.string);  // 返回 true
v.validate('aaa', v.string);  // 返回 true
v.validate('', v.string.required); // 返回 false

// 多项数据联合验证必填
v.validate('aaa', v.string.and('bbb', 'ccc')); // 返回 true
v.validate('aaa', v.string.an('bbb', 'ccc'));  // 返回 false
v.validate('aaa', v.string.or('', ''));  // 返回 true

let obj = { a:'aaa', b: { c:'bbb'} }
v.validate(obj, {
  a: v.string.and(v.get(obj,'b.c'))  // 取不同的属性值比较
});

验证结果处理

说明： 链的所有节点，包含自定义的异步、同步方法，都统一处理
函数参数返回对象属性如下：

• .keys 验证失败或成功的相关方法名称，或自定义方法的顺序位置，数组
• .path 对象值的路径，数组
• .msgs 验证失败的消息，数组

// 验证失败处理
const errHandler = m => {
  console.log(m.msgs) // 返回错误消息
  if (m.keys.includes('gt'))  // 返回 true
    console.log('必须大于14');
}
v.validate(10, v.number.integer.gt(14).alias('年龄').error(errHandler)); 

// 验证成功处理
const okHandler = m => {
  console.log(m.keys.includes('gt')) // 通过判断keys，来自定义处理方法
}
v.validate(10, v.number.gt(4).ok(okHandler));

消息自定义说明：

说明： 消息自定义仅针对验证失败的项。
如果成功也要处理，请在.ok(...)里定义方法。见上述说明。

// 消息模板中%a代表值的域名称，%t代表匹对项名称，通过alias(...)定义的替换
v.validate(23, v.number.gt(18).lt(30)
  .msg('gt', '%a必须大于%t！')
  .msg('lt', '%a必须小于%t！')
  .alias('年龄','十八') // 第一个参数替换%a，第二个参数替换%t
  .alias('三十')) // 再追加的也是替换%t，按顺序替换。

// 模板中%0等数字代表实参值序号，%1, %2...依次类推，非数字文本则被替换成空白 
v.validate(23, v.number.between(18, 30)
  .msg('between', '%a不仅要大于%1，也要小于%2！'))  // %0表示23, %1表示18，%2为30

// 自定义验证方法（包括同步、异步）的消息key用前后顺序位数替代
v.validate(23, v.any.apply(r => r>0)
  .msg('0','%a值有误！')) 

// 一次定义多个消息
v.any.msg({'integer':'%a数字有误！', 'gt': '比较有误'}) 

数据验证规则类型表

标识☆号的，为非正则规则。

async-validtor 兼容处理

以VUE ELement UI的表单验证为例，对比：

// 原校验方式
rules: {
  username: [
    {required: true, message: '用户名不能为空', trigger: 'blur'},
    {type: 'string', message: '用户名必须为字符串', trigger: 'blur'},
    {min: 2,  message: '用户名长度必须为大于2', trigger: 'blur'},
    {pattern: /^[A-Za-z]+[\w\-_]*[A-Za-z0-9]+$/, message: '用户名必需字母或数字组合', trigger: 'blur'},
  ]
},

// 使用本库处理
rules: {
  username: v.string.required.account.min(2).alias('用户名').rule()        
}

兼容处理方式，使用如下扩展即可

// 放在工具目录，引用即可；本库的异步错误处理与同步相同，无需特别处理  
import validator, { Chain } from 'qi-validator'

// 简化验证
Chain.prototype.rule = function(eventName) {
  validator.singleMode = true;
  return {
    type: 'any',
    required: this.__types.indexOf('required') > -1,
    trigger: eventName || 'blur',
    validator: (__rule, __value, __cb) => {
      const errors = [];

      validator.validate(__value, this.error(m => {
        errors.push(new Error(m.msgs[0]))    
      }))
      __cb(errors);
      return errors;
    }
  }
}

export default validator