《zhh.validate.js》v1.x 说明文档
1
概要描述
zhh.validate.js,是一个jQuery插件,一个HTML页面的WEB前端校验框架,提供表单字段的配置式校验功能。
使用方便,所有校验参数都提供data-API,常用的校验功能不需要写一行JavaScript代码,即可完全通过配置来实现。
扩展简单,支持开发人员自定义复杂的校验,支持全局预置和页面定制。对基础校验功能也都提供了修改的方法。
整个表单的校验和每个字段行的校验都支持自动触发和手工触发。
所有的提示文本都是在HTML页面配置的,JavaScript代码里面没有任何的文本信息,这样就可以很好的支持国际化。
与页面的实现语言无关,JSP/Struts/ASP/HTML等都可以使用。
2
文件结构
zhh.validate/ ├── doc/ ├── zhh.validate.1.x.css └── zhh.validate.1.x.js
文件结构非常简单,解开压缩包后只有JS和CSS两个文件,doc文件夹下是说明文档。
CSS文件的内容很少,建议直接copy到WEB项目的公共样式文件当中使用。
3
基本概念
校验单元
以<form>为基础,其中的每一个class="vld-line"
为一个校验单元。一般就是表单的一个字段。如用户名/密码/注册邮箱等,都可以作为一个校验单元。
校验目标
即校验哪个输入框,默认是校验单元中的第1个输入框,<input>、<textarea>或<select>。
校验规则
校验规则,由校验类型、提示文本等组成,是class以vld-
开头的节点,目前支持的类型有必填校验、长度校验、正则表达式校验、对比校验、AJAX校验、密码强度校验、密码强度提示等。
4
校验示例
先来一个真实的例子,具体校验规则之后有详细解说。
<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" autocomplete="off" /> <span class="help-inline"> <i class="vld-message">4-10位数字或字母</i> <i class="vld-required">请输入用户名</i> <i class="vld-length" data-min="4" data-max="10">用户名长度必须在4至10位之间</i> <i class="vld-regexp" data-value="ascii">用户名不支持中文字符</i> <i class="vld-passed"></i> </span> </div> <div class="controls"> <p>必填,4-10位,不支持中文字符</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" /> <span class="help-inline"> <i class="vld-pwd-tips" data-weak="极弱" data-medium="一般" data-strong="较强" data-best="极强"> <i class="vld-pwd-text">密码强度:</i> <i class="vld-pwd-rate"><i></i></i> </i> </span> <span class="help-inline"> <i class="vld-message">密码必须包含字母/数字/特殊字符的任意两种</i> <i class="vld-required">请输入密码</i> <i class="vld-length" data-min="6" data-max="16">密码长度必须在6至16位之间</i> <i class="vld-regexp" data-value="ascii">密码不支持中文字符</i> <i class="vld-compare" data-compare-to="[name=account]" data-reverse="true">密码不能与用户名相同</i> <i class="vld-pwd-level" data-level="medium">密码必须包含字母/数字/特殊字符的任意两种</i> <i class="vld-passed"></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>
>
必填校验
<i class="vld-required">错误提示(可省略)</i>
如果目标输入框内容为空,则校验不通过,显示规则内容作为报错信息。
>
字符长度校验
<i class="vld-length" data-min="2" data-max="8">错误提示(可省略)</i>
如果目标输入框的字符长度不符合要求,则校验不通过,显示规则内容作为报错信息。
data-min指定字符长度的最小值,data-max指定最大值,这两个参数至少要指定一个。
如果不是必填项,即使指定了最小长度而输入框为空,也认为校验通过,可以提交。
>
数字校验
<i class="vld-number" data-sign="true" data-decimal="2" data-min="-150" data-max="1500">错误提示(可省略)</i>
如果目标输入框的内容不是数字,或者数字超过了指定范围,则校验不通过,显示规则内容作为报错信息。
data-min指定数字的最小值,data-max指定最大值,这两个参数可以都不指定。
data-sign指定是否允许前面的+-号,默认为不允许。
data-decimal指定小数位数,默认为0,即只允许输入整数。
>
正则表达式校验
预定义正则表达式
<i class="vld-regexp" data-value="xxx">错误提示(可省略)</i>
xxx指向预定义的正则表达式,url、mobile、email、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}不支持!@#$%^&*,.-/\<>等特殊字符"; })($.zhhvalidate || {});
reverse:true
表示反转判断结果,如果匹配就提示错误。
在illegal-char
这个例子里,意味着只要出现这些特殊字符就会提示错误。
占位符{label}
表示校验单元里面的标签,以下示例,{label}=用户姓名:
<label>用户姓名</label><input type="text" name="name" />
指定正则表达式
<i class="vld-regexp" data-value="xxx">错误提示(不能省略!)</i>
错误提示不能省略!
如<i class="vld-regexp" data-value="^([0-9]{4})?$">只支持4位数字</i>
正则表达式校验,表示该字段必须匹配正则,匹配为通过,不匹配则提示错误。
data-ignore-case="true"
表示忽略大小写,默认为区分大小写。
data-reverse="true"
表示反转判断结果,如果匹配就提示错误。
一看就懂,例子省略。。。
>
相等校验
<i class="vld-compare" data-compare-to="xxx">错误提示(可省略)</i>
相等校验,表示该字段与另一字段必须相等,相等为通过,不相等则提示错误。
data-compare-to
属性,通过jQuery选择符来从校验单元中查找元素作为对比目标。推荐使用input[name=xxx]
。
例如:确认密码必须与登录密码相同。data-compare-to
指向登录密码输入框。
data-reverse="true"
表示反转判断结果,如果相等就提示错误。
例如:密码不能与用户名相同:
<i class="vld-compare" data-compare-to="input[name=password]" data-reverse="true">错误提示(可省略)</i>
例子继续省略。。。
>
密码强度校验
<i class="vld-pwd-level" data-level="xxx">错误提示(可省略)</i>
data-level="xxx"
表示密码强度:weak表示极弱、medium表示一般、strong表示较强、best表示极强。
weak
只要不为空就能达到,没什么好说的。
medium
必须包含字母/数字/特殊字符的任意两种。
strong
必须包含字母/数字/特殊字符,三种都要有。
best
必须包含字母/数字/特殊字符且至少12位且特殊字符超过4位。
还有一条就是,如果密码位数不足6位,强度为极弱。这个值可以通过修改
(function(zv) { zv.pwd.minlength = 8; // 修改密码最小长度 })($.zhhvalidate || {});
>
密码强度提示
已经实现了,文档以后再补充,直接来个例子吧。。。
这是一个提示性的规则,不是校验规则。如果要限制密码强度必须达到某一级别,请看密码强度校验。
>
服务端校验
<i class="vld-ajax" data-url="demo/ajax.txt" data-type="GET" data-data-type="text">错误提示(可省略)</i>
如果服务端返回字符串,true或1表示校验通过;false或0表示校验不通过;其他字符串表示校验不通过,这个字符串就是错误提示。
如果服务端返回JSON格式的数据,就需要自已定义AJAX解析函数了:
// 自定义AJAX解析函数 var parse = zv.ajax.parse; zv.ajax.parse = function(e, json) { if ($.isPlainObject(json)) { return { passed:json.code=="000000", message:json.message }; } else { // 调用原解析函数 return parse.call(this, e, json); } };
>
其他注意事项
校验规则的执行顺序
一个校验单元可配置多条校验规则,校验时将按照规则声明时的顺序,从上到下逐条对校验目标进行校验,如果其中某条规则未通过,将显示该规则中的文本作为报错信息,同一校验单元的其他规则不再校验;所有校验规则全部通过才认为校验通过,将显示vld-passed
中的信息,默认是一个√号。
一个表单可以有多个校验单元,一个校验单元校验失败,仍然会对其他校验单元进行校验;所有校验单元的所有校验规则全部通过校验,才认为整个表单通过校验,才可以提交表单。
如何指定校验目标
校验目标即待校验输入框,默认是校验单元中的第1个输入框,<input>、<textarea>或<select>。
如果一个校验单元有多个输入框,就需要指定校验目标。
可以在校验规则上指定data-target
属性,通过jQuery选择符来从校验单元中查找元素作为校验目标。如data-target="#name"
、data-target="input[name=url]"
、data-target=".email"
等等。由于input的name一般是必需的,个人推荐input[name=xxx]
的写法,这样就不用额外给input增加id或class了。
也可以在输入框上指定vld-target
样式,表示这个输入框是这个校验单元的校验目标。
优先级:规则上指定data-target
属性 --> 输入框上指定vld-target
样式 --> 取第1个输入框,优先级递减。
<input type="hidden" name="id" /> <-- 第3优先级 <input type="text" name="account" class="vld-target" /> <-- 第2优先级 <input type="text" name="email" /> <i class="vld-required" data-target="input[name=email]">请输入邮箱</i> <-- 第1优先级,取到的是第3行 <i class="vld-required">请输入帐号</i> <-- 未指定target,取第2优先级
下面来个例子,这种情况就会出现一行有多个输入框:
清除前后空白字符的问题
获取校验目标的值之后,默认是会清除前后空白字符的。如果不希望清除,就需要给必填规则加上data-trim="false"
。
校验时机
在校验目标输入框内容改变时、失去焦点时、选择框点击时触发单元校验。
在点击<form>中的class="vld-submit"
按钮时校验整个表单,如果所有校验单元全部通过,将自动提交表单。
如果需要手动提交,那么首先删除提交按钮的class="vld-submit"
样式声明,再编写JavaScript代码调用校验单元的zhhvalidate()
方法触发表单校验,在回调函数中提交表单:
$("form").zhhvalidate(function(e) { if (e.passed) { // 校验通过 $(this).submit(); // 提交表单 } });
手动触发单元校验,如触发第一个单元行的校验:
$("form .vld-line:first").zhhvalidate(function(e) { // do something });
>
自定义校验规则
以下是自定义一个必须小于当前年份的规则。
<i class="vld-rule vld-less-year"></i>
(function(zv) { // 定义必须小于当前年份的规则 zv.rules.put("less-year", function(e) { if (parseInt(e.value || 0) > new Date().getFullYear()) { return false; // 校验未通过 } return true; // 校验通过 }); zv.locals["zh-CN"]["less-year"] = "{label}不能大于当前年份"; })(jQuery.zhhvalidate);
>
联系方式