意见反馈: zhaohuihua@126.com

1

概要描述

zhh.validate.js,是一个jQuery插件,一个HTML页面的WEB前端校验框架,提供表单字段的配置式校验功能。

使用方便,所有校验参数都提供data-API,常用的校验功能不需要写一行JavaScript代码,即可完全通过配置来实现。

扩展简单,支持开发人员自定义复杂的校验,支持全局预置和页面定制。对基础校验功能也都提供了修改的方法。

整个表单的校验和每个字段行的校验都支持自动触发和手工触发。

所有的提示文本都是在HTML页面配置的,JavaScript代码里面没有任何的文本信息,这样就可以很好的支持国际化。

与页面的实现语言无关,JSP/Struts/ASP/HTML等都可以使用。

2

文件结构

zhh.validate/
 ├── doc/
 ├── zhh.validate.2.x.css
 └── zhh.validate.2.x.js

文件结构非常简单,解开压缩包后只有JS和CSS两个文件,doc文件夹下是说明文档。

依赖jquery.1.10+,和zhh.tools.js。

CSS文件的内容很少,建议直接copy到WEB项目的公共样式文件当中使用。

3

基本概念

校验单元

以<form>为基础,其中的每一个class="vld-line"class="form-group"为一个校验单元。

一般就是表单的一个字段。如用户名/密码/注册邮箱等,都可以作为一个校验单元。

校验规则

校验规则,以data-vld="..."的形式配置在输入框上。

data-vld="{ label:'登录账号', rules:[ {required:true}, {length:[4,10]}, ... ] }"

如果label可以自动获取,则简写为:

data-vld="[ {required:true}, {length:[4,10]}, ... ]"

如果只有一个规则,还可以简写为:

data-vld="required:true" // 必填
data-vld="regexp:'mobile'" // 手机号码

默认支持的类型有必填校验、长度校验、正则表达式校验、对比校验、AJAX校验、密码强度校验等。

标签文本

错误提示中的占位符{label}表示校验单元里面的标签文本。

标签文本可以自动查找校验单元中的class="vld-label"class="control-label"。会清除前面的星号和后面的冒号。

以下示例,{label}=登录账号:

<label class="vld-label">登录账号</label><input type="text" ... data-vld="[...]" />

也可以通过配置指定,data-vld="{ label:'登录账号', rules:[...] }"。配置指定优先级高于自动查找。

<label class="vld-label">账号</label><input type="text" ... data-vld="{ label:'登录账号', rules:[...] }" />

4

校验示例

先来一个真实的例子,具体校验规则之后有详细解说。

4-10位数字或字母

必填,4-10位,不支持中文字符

不允许包含!@#$%^&*,./\等特殊字符,AJAX校验

密码必须包含字母/数字/特殊字符的任意两种

必填,6-16位,支持空格,不支持中文字符,不能与用户名相同

<form class="vld-form form-horizontal">
  <div class="control-group vld-line">
    <label class="control-label"><span class="asterisk">*</span> 登录账号</label>
    <div class="controls">
      <input class="span3" type="text" name="account"
        data-vld="[ {required:true}, {length:[4,10]}, {regexp:'ascii'}, {regexp:'illegal-char'}, {ajax:'demo/ajax.txt',options:{type:'GET',dataType:'text'},text:'用户名已被使用'} ]" />
      <span class="help-inline">
        <i class="vld-tips">4-10位数字或字母</i>
      </span>
    </div>
    <div class="controls">
      <p>必填,4-10位,不支持中文字符</p>
      <p>不允许包含!@#$%^&*,./\等特殊字符,AJAX校验</p>
    </div>
  </div>
  <div class="control-group vld-line">
    <label class="control-label"><span class="asterisk">*</span> 密码</label>
    <div class="controls">
      <input class="span3" type="password" name="pwd" data-trim="false" 
        data-vld="[ {required:true}, {length:[6,16]}, {regexp:'ascii'}, {compare:'[name=account]',reverse:true}, {pwdlevel:'medium'} ]" />
      <span class="help-inline">
        <i class="vld-tips">密码必须包含字母/数字/特殊字符的任意两种</i>
      </span>
    </div>
    <div class="controls">
      <p>必填,6-16位,支持空格,不支持中文字符,不能与用户名相同</p>
    </div>
  </div>
  <div class="control-group">
    <label class="control-label"> </label>
    <div class="controls">
      <input type="button" class="btn btn-primary input-medium vld-submit" value="提交" />
    </div>
  </div>
</form>

>

必填校验

{ required:true }

可以自定义提示信息,如:

{ required:true, text:'请同意服务协议' }
{ required:true, text:'请选择{label}' }

如果目标输入框内容为空,则校验不通过。

单选框/复选框,没有选中则校验不通过。

单选框/复选框的校验规则应配置在第一个input上。

data-vld="{required:true}"

data-vld="{required:true}"

下拉选择框,选中项的值为空则校验不通过,<option value="">-请选择-</option>

data-vld="{required:true,text:'请选择{label}'}"

单选框/复选框,没有选中则校验不通过。

data-vld="{required:true,text:'请同意服务协议'}"

>

字符长度校验

如果目标输入框的字符长度不符合要求,则校验不通过。

min指定字符长度的最小值,max指定最大值,这两个参数至少要指定一个。

如果不是必填项,即使指定了最小长度而输入框为空,也认为校验通过,可以提交。

{ length:{min:4,max:12} } // 字符长度4-12位
{ length:[4,12] } // 字符长度4-12位
{ length:{min:4} } // 字符长度不得小于4位
{ length:[4] } // 字符长度不得小于4位
{ length:{max:12} } // 字符长度不得大于12位

>

数字校验

如果目标输入框的内容不是数字,或者数字超过了指定范围,则校验不通过。

min指定数字的最小值,max指定最大值,这两个参数可以都不指定。

sign指定是否允许前面的+-号,默认为不允许。

decimal指定小数位数,默认为0,即只允许输入整数。

{ number:true } // 必须是数字
{ number:{min:1900,max:2999} } // 数字必须在1900-2999之间
{ number:[1900,2999] } // 数字必须在1900-2999之间
{ number:{min:1900} } // 数字不得小于1900
{ number:[1900] } // 数字不得小于1900
{ number:{max:2999} } // 数字不得大于2999
{ number:true, sign:true } // 允许+-号
{ number:true, decimal:4 } // 最多4位小数
{ number:true, sign:true, decimal:4 } // 允许+-号, 最多4位小数

>

正则表达式校验

预定义正则表达式

{ regexp:'xxx' }

xxx指向预定义的正则表达式,url、email、mobile(手机号码)、ascii(只支持英文字符)、illegal-char(不支持非法字符)。

预定义的正则表达式可以自己扩充。

(function(zv) {

	// 定义只允许输入数字和字母的表达式
	zv.regexp["number-ascii"] = /^[0-9a-zA-Z]*$/;
	zv.locals["zh-CN"]["regexp-number-ascii"] = "{label}只允许输入数字和字母";

	// 定义不允许特殊字符的表达式
	// reverse=true表示反转判断结果, 如果匹配就提示错误
	zv.regexp["illegal-char"] = { value:/[!@#$%^&*,.\-\/\\<>]/, reverse:true };
	zv.locals["zh-CN"]["regexp-illegal-char"] = "{label}不支持!@#$%^&*,.-/\<>等特殊字符";

})(jQuery.fn.zhhvalidate.defaults);

reverse:true表示反转判断结果,如果匹配就提示错误。

illegal-char这个例子里,意味着只要出现这些特殊字符就会提示错误。

指定正则表达式

{ regexp:/^[0-9a-zA-Z]*$/, text:'{label}只允许输入数字和字母' }

text错误提示不能省略!

正则表达式校验,表示该字段必须匹配正则,匹配为通过,不匹配则提示错误。

data-ignore-case="true"表示忽略大小写,默认为区分大小写。

data-reverse="true"表示反转判断结果,如果匹配就提示错误。

>

相等校验

{ compare:'selector' }
{ compare:'selector', reverse:true }

相等校验,表示该字段与另一字段必须相等,相等为通过,不相等则提示错误。

selector,通过jQuery选择符来从<form>中查找元素作为对比目标。

例如:确认密码必须与登录密码相同。{ compare:'input[name=pwd]' }指向登录密码输入框。

reverse:true表示反转判断结果,如果相等就提示错误。

例如:密码不能与用户名相同:

{ compare:'input[name=account]', reverse:true }

>

服务端校验

{ ajax:'url.do' }
{ ajax:'url.do', fields:fields }
{ ajax:'url.do', fields:fields, options:{ type:GET|POST, dataType:json|html|text, ...} }

如果服务端返回字符串,true或1表示校验通过;false或0表示校验不通过;其他字符串表示校验不通过,这个字符串就是错误提示。

如果服务端返回JSON格式的数据,就需要自已定义AJAX解析函数了:

(function(zv) {
    // 自定义AJAX解析函数
    var parse = zv.ajax.parse;
    zv.ajax.parse = function(e, json) {
        if ($.isPlainObject(json)) {
            return { passed:json.code=="000000", text:json.message };
        } else { // 调用原解析函数
            return parse.call(this, e, json);
        }
    };
})(jQuery.fn.zhhvalidate.defaults);

>

data-vld选项

<form data-vld="init:true,oninput:true,focus:true,failFast:false,tips:true,disabled:false">
<div class="vld-line" data-vld="group:true,failFast:false,tips:true,disabled:false"></div>
<input data-vld="tips:true,disabled:false"></input>

init:true|false是否需要初始化事件绑定,默认为true。如果不初始化, 则只有在点提交按钮时才会触发表单校验;如果初始化,则在校验目标输入框内容改变时、失去焦点时、选择框点击时均会触发单元校验,而且在点击<form>中的class="vld-submit"按钮时会校验整个表单,如果所有校验单元全部通过,则自动提交表单。

oninput:true|false是否需要绑定<input>和<textarea>的oninput事件(IE:onpropertychange),默认为true。如果不初始化, 则只有在点提交按钮时才会触发表单校验;如果绑定,则每输入一个字符都会触发单元校验。只在init=true时有效。

focus:true|false是否需要在表单校验失败时将焦点移至第一个失败的校验目标上,默认为true。

failFast:true|false快速失败,默认为false。设置为true时,遇到第一个错误就结束校验;false则即使失败仍然继续执行下一个单元校验。

tips:true|false|fix是否显示错误提示,默认为true。true=显示错误提示,查找校验单元中的vld-tips设置text;false=不自动显示错误提示,一般是js调用时传入false用于自已处理错误提示;fix=绝对定位,自动生成错误,显示在目标输入框的右侧。

disabled:true|false是否禁用校验,默认为false。禁用之后则校验始终为通过。如果上层已经禁用,则该选项无效。如form上配置disabled:true,则input上配置disabled:false仍然不会启用校验;而form上配置disabled:false,input上配置disabled:true可以禁用掉input上的校验。

group:true组合校验,配置在form或vld-line上,将其中包含的所有校验目标作为一组处理,错误提示只有一处。可以结合failFast一起使用,如果failFast!=true,则将所有的错误提示合并在一起显示。

>

组合校验

个人资料  

姓名:     年龄:
手机号码:
家庭住址:
收入水平 

姓名、手机号码不能为空;家庭住址不允许!@#$%^&*,./等特殊字符。

<div class="vld-line" data-vld="group:true"></div>
<form data-vld="group:true,failFast:true"></form>

>

其他

提交表单:

$("button[name=dosubmit]").click(function(e) {
    e.preventDefault();
    var $form = $(this).closest("form");
    $form.zhhvalidate(function(e) {
        if (e.passed) {
            $form.submit();
        }
    });
});

手动触发校验:

form.find("input[name=account]").zhhvalidate(function(e) {
    if (e.passed) {
        // do something
    }
});

自己处理错误提示:

$("button[name=dosubmit]").click(function(e) {
    e.preventDefault();
    var $form = $(this).closest("form");
    // 回调参数e
    //     passed(boolean) FORM表单校验是否通过
    //     text(String)    校验不通过时的错误原因(校验通过时为空)
    //     list([json])    每一个表单行的校验校验结果, json内容见vldinput的回调参数说明
    // 设置tips=false, 不显示错误提示; 还可以设置failFast=true, 每次只显示一条提示
    $form.zhhvalidate({ tips:false }, function(e) {
        if (e.passed) {
            $form.submit();
        } else {
            alert(e.text); // 自己处理错误提示
        }
    });
});

>

自定义校验规则

以下是自定义一个必须小于当前年份的规则。

(function(zv) {
    // 必须小于当前年份的自定义规则
    zv.rules.put("less-curr-year", function(e) {
        if (parseInt(e.value || 0) > new Date().getFullYear()) {
            return false; // 校验未通过
        }
        return true; // 校验通过
    });
    zv.locals["zh-CN"]["less-curr-year"] = "{label}不能大于今年";
})(jQuery.fn.zhhvalidate.defaults);
<input data-vld="[ {number:{min:1900}}, {'less-curr-year':true} ]" />

>

联系方式

zhaohuihua@126.com