nice Validator参考
例1. DOM传参
1. 要验证一个表单,只需要给字段绑定规则“data-rule
”就可以了
2. 字段可以有多条规则,规则之间用分号(;)分隔
3. js初始化不是必要的,只要是字段并且带有“data-rule”属性,即使是新插入的一段DOM也可以立马验证
4. 其中:required是内置规则(核心自带),username、password是配置文件中设置的全局规则(配置文件)
Preview
HTML
例2. js传参(这和上面的DOM传参等价)
1. 如果你愿意的话,也可以“DOM传参” 和 “js调用”混搭,js传递的规则优先级最高
Preview
HTML
Javascript
例3. 设置显示替换名
1. 在规则字符串的最前面加上该字段的名字,并且跟上一个冒号(:),例如下面的“用户名:”, 参见公共定义
2. 如果是js调用也是一样的
3. 下面的例子同时在form上绑定了参数
Preview
HTML
数值范围
规则:range[limits];
limits(范围)表示方式: ~100 (小于100),0~100 (0到100),100~ (大于100)
例1. 输入数值必须在指定范围
Preview
HTML
例2. 输入数值必须小于某个范围
Preview
HTML
例3. 输入数值必须大于某个范围
Preview
HTML
checkbox 和 radio的验证
例1. radio的必选
1. 对于checkbox和radio,要“必填”的话,不能使用“required
”,而是使用“checked
”
2. 你只需要在第一个checkbox或者radio上面绑定规则就可以了
3. 消息会自动生成,并且显示在最后面,你无需关注消息怎么显示
Preview
HTML
例2. 不能为空,至少选择一项
在第一个checkbox上绑定规则:checked
Preview
HTML
例3. 控制选中项目数
1.checked[2~]
表示选择的项目要在2项以上
2. 不要对:radio
使用参数,因为本身就是单选,直接checked
就可以了
Preview
HTML
例4. Ajax提交表单
1. 可以通过valid
参数传入回调,参见配置
2. 也可以直接接收valid.form
事件(下面例子采用接收事件的方式),参见事件
Preview
HTML
Javascript
例5. 规则的逻辑或、逻辑非
1、使用竖线(|)分隔的多个规则,只要其中一个验证通过,就算通过
2、连续的规则或,只需要给最后一条规则设置错误消息
3、在规则名前面加上逻辑非(!),即可反转规则的验证效果
4、规则非,不能使用原本规则的消息,只能重新定义
Preview
HTML
两个字段匹配
例1. 两个字段的值必须相同
规则:match[name];
Preview
HTML
例2. 两个字段比较大小
规则:match[limits, name];
limits可用值:eq (相同), lt (小于),gt (大于),lte (小于等于),gte (大于等于)
这种模式下,两个字段的值都会转换为数字进行比较
Preview
HTML
例3. 结束日期必须大于开始日期
规则:match[limits, name, date];
limits可用值:eq (相同), lt (小于),gt (大于),lte (小于等于),gte (大于等于)
第三个参数date
或time
代表要比较的类型
Preview
HTML
字符串长度
例1. 限制字符长度范围
规则:length[limits];
limits(范围)表示方式: ~100 (小于100),0~100 (0到100),100~ (大于100)
Preview
HTML
例2. 限制字符长度范围,计算真实长度(全角字符计算两个字符)
规则:length[limits, true];
limits(范围)表示方式同上
Preview
HTML
远程验证
例1. 服务器端验证并返回结果
a. 使用规则:
remote([get:]url [, name1, [name2]...]);
b. url前面的
get:
是可选的,加上此参数,将改变ajax方式为GETc. 从第二个参数起,可选传入字段的name,用于附带额外请求参数
d. 智能适配服务器返回的3种数据格式,对于json格式(2和3)只需要包含所需数据就适配:
1. '' => 成功, '错误消息' => 失败
2. {"ok":""} => 成功,{"ok":"名字很棒!"} => 成功, {"error":"错误消息"} => 失败
3. {"data":{"ok":""}} => 成功,{"data":{"ok":"名字很棒!"}} => 成功, {"data":{"error":"错误消息"}} => 失败
Preview
HTML
Javascript
例2. ajax验证时,传递额外的参数
1. 传递的name值需要是表单中已经存在的
2. 可以传递无限个参数
3. 每个参数之间用英文逗号(,)分隔,逗号后面的空格是必须的
Preview
HTML
Javascript
例3. 自定义ajax验证
1. 如果内置的remote规则不能满足你的需求,可以 自定义规则 ,将$.ajax()返回出来
2. 提交表单的时机是在表单验证通过后,这里演示了valid回调会在表单验证通过后才被调用
Preview
HTML
Javascript
过滤不安全字符
例1.不安全字符将自动丢掉
1. 直接过滤输入,不提示错误
2. 默认过滤尖括号(<>),你可以通过传入字符(支持正则),改变过滤规则
例如:filter(`%<>\/)
,将过滤:`%<>/
Preview
HTML
Twitter注册之DOM传参
1. 大多数表单验证都可以通过DOM方式传参
2. 做好全局配置(zh_CN.js),可以大大减少工作量
3. 如果你不放心DOM自动初始化,也可以在js中一行代码初始化一遍$('#form').validator();
Preview
HTML
Javascript
Twitter注册之js传参
, 更换主题,然后看看下面的提示消息有什么变化?
1. 无需侵入HTML结构,全js调用
2. 你还可以自由控制消息的位置,只要设置msgStyle
参数就可以了,例如:"margin-left:10px;margin-top:5px;"
3. 所谓主题,是通过配置表单的class、消息模板以及其他一些参数实现的不同展现效果
4. 所有参数(除了rules和messages), 都可以用来配置主题; 主题名字可以随意定义
5. 主题配置可以覆盖全局配置,同时也会被调用时的传参覆盖
Preview
HTML
Javascript
自定义规则
例1. 正则方式 - DOM传参
DOM传参:data-rule-ruleName="[RegExp, 'ErrorMessage']"
其中ruleName是规则名字,可以随便定义,只要调用规则时保持一致就可以
Preview
HTML
例2. 正则方式 - JS传参
JS传参:ruleName: [RegExp, 'ErrorMessage']
实际上跟DOM传参是一样的
Preview
HTML
Javascript
例3. 回调方式 - JS传参(具有最大的灵活性,几乎搞定任何验证)
JS传参:ruleName: function(element, param, field) {}
@param element 当前验证的DOM元素
@param param 规则传递的参数
@param field 当前字段元数据
以下是可返回的数据:
return undefined(等同于无return) => √通过
return true => √通过
return false => ×不通过
return "String" => ×不通过,并且认为这个字符串是错误消息
return {"ok": "正确提示"} => √通过,并且提示这个ok的消息
return {"error": "错误消息"} => ×不通过,并且提示这个error的消息
return $.ajax(),ajax验证 => 等待验证结果(注:ajax返回的数据格式参见remote的示例)
return null => 忽略本次验证(跳过该字段的验证,如果已经显示了消息将会自动隐藏)
Preview
HTML
Javascript
例4. 满足“用户名/手机号/邮箱”之一就合法
自定义规则方法中的this总是指向当前验证的实例,所以在内部可以直接调用实例方法(参见:方法)
注意:下面例子loginName规则中,第一个test是正则表达式的方法,后面两个this.test
是调用了验证的test方法
Preview
HTML
Javascript
例5. 自定义ajax验证
1. 如果内置的remote规则不能满足你的需求,可以 自定义规则 ,将$.ajax()返回出来
2. 提交表单的时机是在表单验证通过后,这里演示了valid回调会在表单验证通过后才被调用
Preview
HTML
Javascript
例6. 自定义required的验证条件
required(condition),只有满足condition规则,才验证required
Preview
HTML
Javascript
自定义消息显示位置
例1. 验证隐藏域,消息显示在代理的输入框周围
DOM传参:data-target="jQuery选择器"
如果“jQuery选择器”选择的DOM是输入框,该输入框将成为消息位置的代理
否则消息直接显示在“jQuery选择器”选择的DOM内部
下面的例子中,实际验证和提交的是“pid”字段,不要在意乎表象^_^
Preview
HTML
Javascript
例2. 设置消息占位,精确控制消息位置
<span class="msg-box" for="inputID"></span>
inputID对应input的id(如果input有id)或者input的name
把这段DOM放到哪个位置,消息就显示在哪儿,还可以通过给这个span写style内联样式,控制更精准的位置
注意:
消息占位的标签由msgWrapper参数(默认为span)决定,如果设置了msgWrapper: label,那么这里的标签也要用label
Preview
HTML
例3. 统一显示消息在一个位置
1、设置 msgMaker 参数为false,就不会再自动生成消息
2、使用 invalid 回调的第二个参数 errors
注意:
此功能在0.5.0+版本按以下方式支持,之前版本的msgHandler参数已被移除
Preview
HTML
Javascript
高亮错误
不管是高亮错误,还是高亮错误区域,都需要自己定义CSS(不确定的样式需要你自己来实现)
例1. 高亮出错的输入框
1. 字段验证失败后,该输入框会自动添加一个class(n-invalid
),字段验证通过后又会自动移除这个class
2. 可以自定义这个class的样式,实现高亮输入框
Preview
HTML
CSS
1 |
#demo_121 .n-invalid {border: 1px solid #f00;}
|
例2. 高亮出错的区域
1. 原理是通过invalid.field
事件,找到父节点添加一个class
2. 需要表单结构的配合,具体要看你表单的结构是什么样子来灵活使用
Preview
HTML
CSS
12 |
#demo_122 .form-item {padding:5px; margin:2px 0;}
#demo_122 .form-item-error {background: #FDE2E9;}
|
Javascript
例3. 高亮出错的区域,出错后不要停止验证
和例2大同小异,只不过加了几个参数
Preview
HTML
CSS
12 |
#demo_123 .form-item {padding:5px; margin:2px 0;}
#demo_123 .form-item-error {background: #FDE2E9;}
|
Javascript
组合验证
参见:文档 > 参数配置 > groups
组合验证有多种用途:
1. 当多个字段中,只要填写部分字段就通过的情况
2. 如果多个字段有关联性的时候,例如:每验证其中一个字段就需要做一下处理
例1、组合多个字段,至少正确填写其中任意一个字段,并且其他字段无错则通过
Preview
HTML
Javascript
使用ID标识字段
例1. 字段只有id,没有name的情况
这种情况,既可以js传参,也可以DOM传参
下面例子的两个字段,分别使用了js传参和DOM传参
Preview
HTML
Javascript
例2. 字段有name,但是使用id来标识
这种情况只能通过js传参,因为DOM传参会优先使用name作为标识
Preview
HTML
Javascript
例3. 为多个相同name的字段设置不同id,实现分别显示消息
如果多个字段name相同,并且要分别显示消息,就要为他们设置不同的id
Preview
HTML
<div id="result" class="tip-ok" style="display:none">提交成功</div> <form id="signup_form" class="signup" autocomplete="off"> <fieldset> <div class="form-item"> <div class="field-name">全名</div> <div class="field-input"> <input type="text" name="user[name]" maxlength="20" autocomplete="off"> </div> </div> <div class="form-item"> <div class="field-name">电子邮件地址</div> <div class="field-input"> <input type="text" name="user[email]" autocomplete="off"> </div> </div> <div class="form-item"> <div class="field-name">创建密码</div> <div class="field-input"> <input type="password" name="user[user_password]"> </div> </div> <div class="form-item"> <div class="field-name">选择你的用户名</div> <div class="field-input"> <input type="text" name="user[screen_name]" maxlength="15" autocomplete="off"> </div> </div> </fieldset> <button id="btn-submit" class="btn-submit" type="submit">创建我的账号</button> </form> //验证初始化 $('#signup_form').validator({ stopOnError:true, timely: 2, //自定义规则(PS:建议尽量在全局配置中定义规则,统一管理) rules: { username: [/^[a-zA-Z0-9]+$/, '用户名无效! 仅支持字母与数字。'] }, fields: { "user[name]": { rule: "required", tip: "输入你的名字与姓氏。", ok: "名字很棒。", msg: {required: "全名必填!"} }, "user[email]": { rule: "email;remote[check/email.php]", tip: "你的邮件地址是什么?", ok: "我们将会给你发送确认邮件。", msg: { required: "电子邮箱地址必填!", email: "不像是有效的电子邮箱。" } }, "user[user_password]": { rule: "required;length[6~];password;strength", tip: "6个或更多字符! 要复杂些。", ok: "", msg: { required: "密码不能为空!", length: "密码最少为6位。" } }, "user[screen_name]": { rule: "required;username;remote[check/user.php]", tip: "别担心,你可以稍后进行修改。", ok: "用户名可以使用。<br>你可以稍后进行修改。", msg: {required: "用户名必填!<br>你可以稍后进行修改。"} } }, //验证成功 valid: function(form) { $.ajax({ url: 'results.php', type: 'POST', data: $(form).serialize(), success: function(d){ $('#result').fadeIn(300).delay(2000).fadeOut(500); } }); }, //验证失败 invalid: function(form) { //按钮动画效果 $('#btn-submit').stop().delay(100) .animate({left:-5}, 100) .animate({left:5}, 100) .animate({left:-4}, 100) .animate({left:4}, 100) .animate({left:-3}, 100) .animate({left:0}, 100); } });
------------------------------------------------------------------------------
使用方式(Usage)
仅作为入门指引,详细了解建议查看公共定义以及配置说明
第一步、引入资源
使用之前,确保已经引入了jQuery,需要 1.7 以上版本。
<script type="text/javascript" src="path/to/jquery-1.7.2.min.js"></script>
然后引入验证插件,其中“zh_CN.js” 是本地化配置文件,你可以在里面配置一些全局的参数(规则、主题、多语言消息)。
<link rel="stylesheet" href="path/to/validator/jquery.validator.css">
<script type="text/javascript" src="path/to/validator/jquery.validator.js"></script>
<script type="text/javascript" src="path/to/validator/local/zh_CN.js"></script>
第二步、使用组件
两种方式(js传参 和 DOM传参),都可以实现表单验证:
通过JS传参,无需改变DOM。
@example
<form name="register">
<label>邮箱</label><input name="email">
</form>
$('form[name="register"]').validator({
stopOnError: false,
timely: false,
fields: {
'email': 'required;email;'
}
});
通过在DOM上绑定属性,无需js调用。
a. 在字段上绑定规则,参见公共定义-规则
b. 如果要改变默认参数,可以在form上以json字符串形式绑定参数data-validator-option,参见公共定义-表单
c. 如果参数全部在DOM元素上面传递,那么js就不需要初始化了
@example
<form name="register" data-validator-option="{stopOnError:false, timely:false}">
<label>邮箱</label><input name="email" data-rule="required;email;">
</form>
没理解?先看看示例,再来研究文档吧!
公共定义(Common)
帮助你理解nice Validator的验证方式
规则(rule)
"display: rule1; rule2; ... rulen;"
1. 前面的display:是可选的,用于替换错误消息中显示的字段名。
2. 后面的 rule1 ~ rulen 代表规则,规则之间需要使用分号(;)分隔,最后一个规则后面的分号可选
3. 冒号(:)或者分号(;)后面可以有空格
@example:
例如required规则的默认消息模板为:{0}不能为空
data-rule="required; username;" //required规则验证失败后,将提示:"不能为空"
data-rule="用户名: required; username;" //required规则验证失败后,将提示:"用户名不能为空
a. 每条规则之间用分号(;)分隔,分号后可以有空格,不限规则数量,规则越靠前越先被验证
b. 如果一条规则被定义为可以传参数,那么所有参数需要使用圆括号(())或者方括号([])括起来;
c. 如果有多个参数,那么每个参数之间需要使用“逗号+空格”隔开
DOM上绑定规则,使用data-rule-* = "[RegExp, 'errorMessage']"
@example:
<input name="demo" data-rule="required; xxx" data-rule-xxx="[/^\d{6}$/, '请输入6位数字']">
该例子定义了名字为“xxx”的规则,使用了正则表达式,且附带了错误消息,如果xxx验证失败将提示“请输入6位数字”。 实际上,你甚至可以覆盖内置或者全局的规则,例如required
js调用时传递规则,使用rules参数,这和在HTMl结构中定义规则是一样效果
@example:
<form id="yourForm">
<input name="demo">
</form>
$("#yourForm").validator({
rules: {
xxx: [/^\d{6}$/, '请输入6位数字']
},
fields: {
demo: "required; xxx"
}
});
字段(field)
字段是表单的基本构成。验证组件收集配置信息时也会以字段为单位
DOM传参支持的属性
a. 如果要使一个字段被验证,data-rule参数是必不可少的,其他参数都可选
b. 支持的属性:data-rule、data-rule-*、data-msg-*、data-tip、data-ok、data-target、novalidate、notimely
@example:
1<form id="yourForm">
<input type="password" name="demo"
data-rule="required; password"
data-rule-password="[/^\d{6}$/, '请填写6位数字']"
data-msg-required="请填写密码"
data-tip="密码由6位数字组成"
data-ok="别担心,稍后您还可以更改"
data-target="#msg_holder"
>
</form>
上面例子中:
data-rule 定义该字段的规则集
data-rule-password 定义了一条临时规则(在data-rule中已经使用了)
data-msg-required 更改了默认required的消息;
data-tip 参数使得元素获得焦点时,显示友好的信息;
data-ok 定义的消息,将在字段验证成功后显示;
data-target 如果定义,将决定消息最终显示位置。如果“#msg_holder”是字段(如input、select、textarea),消息的显示位置将转为该字段的消息位置,如果是带有“.msg-box”类的DOM,将显示在该DOM内;
另外两个特殊属性,不需要带值:
novalidate 不要验证该字段,动态添加和移除该属性可以使该字段在合适的时候验证
notimely 不要实时验证该字段,动态添加和移除该属性可以使该字段在合适的时候验证
使用JS传参方式
@example:
<form id="yourForm">
<input type="password" name="demo">
</form>
11111$("#yourForm").validator({
rules: {
xxx: [/^\d{6}$/, '请输入6位数字']
},
fields: {
demo: {
rule: "required; xxx",
msg: {required: "请填写密码"},
tip: "密码由6位数字组成",
ok: "别担心,稍后您还可以更改",
target: "#msg_holder"
}
}
});
表单(form)
表单也可以接收参数
@example:
<form id="yourForm" data-validator-option="{stopOnError:false, timely:false}">
<input type="password" name="password" data-rule="required;password">
</form>
data-validator-option 接收和js配置一样的json字符串
novalidate 指示暂时不要初始化该表单的验证,动态移除后,初始化还是会执行
配置说明(options)
debug {Number | Boolean}
默认: 是否启用调试模式,可用值:
0 || false: 关闭调试信息
1 || true: 启用调试信息
2: 启用调试信息,并且不论表单是否验证成功都提交表单,便于对比后端的验证
timely {Number | Boolean}
默认: 是否启用实时验证,可用值:
0 || false: 关闭实时验证,将只在提交表单的时候进行验证
1 || true: 启用实时验证,在字段失去焦点后验证该字段
2: 启用实时验证,在输入的同时验证该字段
theme {String}
默认: 'default'
主题名字,用于设置一个表单验证的主题样式。zh_CN.js中配置了几个主题,可以作为参考
stopOnError {Boolean}
默认: false
是否在验证出错时停止继续验证,默认不停止
focusInvalid {Boolean}v0.7.0+
默认: true
是否自动让第一个出错的输入框获得的焦点,默认获得
focusCleanup {Boolean}v0.7.0+
默认: false
是否在输入框获得焦点的时候清除消息,默认不清除
ignore {jqSelector}
指定需要忽略验证的元素的jQuery选择器,Example:
111//任何不可见的元素,都不作验证
$('form').validator({
ignore: ':hidden'
});
//id为tab2下的所有子元素都不作验证
$('form').validator({
ignore: '#tab2'
});
//动态改变要忽略验证的元素
$('form').data('validator').options.ignore = '#tab1';
rules {Object}
自定义用于当前实例的规则,支持两种定义方式。Example:
11111$('form').validator({
rules: {
//自定义验证函数,具有最大的灵活性,没有什么不能验证
myRule: function(el, param, field){
//do something...
},
//简单配置正则及错误消息,及其方便
another: [/^\w*$/, '请输入字母或下划线']
},
fields: {
//调用前面定义的两个规则
foo: 'required; myRule[param]; another'
}
});
messages {Object}
自定义用于当前实例的规则消息,Example:
$('form').validator({
messages: {
required: "请填写该字段",
email: "请检查邮箱格式",
},
fields: {
'email': 'required;email;'
}
});
fields {Object}
待验证的字段集合,键为字段的name值或者"#"+字段id。有两种用法:
快捷字符串传参:"name": "display: rule1;rule2;...rulen",其中“display:”可选,用于替换错误消息的字段名字
对象传参:
111111111fields: {
//name字段使用了所有支持的参数
name: {
rule: "姓名: required; rule2; rule3",
msg: {
required: "请填写姓名",
rule2: "xxxx",
rule3: "xxxx"
},
tip: "填写真实姓名有助于朋友找到你",
ok: "",
timely: false,
target: "#msg_holder"
},
//email和mobile字段用最简单的方式传递字段规则
email: "required; email",
mobile: "mobile"
}
fields[name].rule {String}
字段的验证规则,多个规则用分号(;)分隔,支持使用方括号([ ])或者圆括号(( ))传参。查看内置规则
fields[name].msg {Object}
自定义字段中每个规则的错误消息
fields[name].tip {String}
自定义获得焦点时的友好提示信息
fields[name].ok {String}
自定义字段验证成功后显示的消息
fields[name].msgWrapper {String}
自定义该字段的消息容器的标签名
fields[name].msgMaker {Function}
自定义该字段的消息生成器
fields[name].msgClass {String}
自定义该字段的消息Class
fields[name].msgStyle {String}
自定义该字段的消息CSS样式
fields[name].dataFilter {Function}
使用dataFilter回调可以转换ajax返回的结果为niceValidator支持的格式
fields[name].valid {Function}
字段验证通过的回调
fields[name].invalid {Function}
字段验证失败的回调
fields[name].must {Boolean}
是否强制验证该字段
fields[name].timely {Boolean}
是否启用实时验证,默认值继承自options的timely参数
fields[name].target {jqSelector}
验证当前字段,但是实际上在target的元素上提示错误消息,
如果目标元素是输入框(input,textarea、select),将会以目标元素为基准点,插入一条消息;
如果目标元素是消息占位(className为msg-box),这和直接使用消息占位没有区别
其他情况下,直接显示在target指向的容器中
groups {Array}v0.2.1+
组合多个字段,验证其中的每一个字段都会首先触发callback回调。Example:
11111$('form').validator({
groups: [{
fields: 'field1 field2 field3',
callback: function($elements){
//do something
},
target: '#msg_holder'
}],
fields: {
field1: 'tel',
field2: 'mobile',
field3: 'email'
}
});
beforeSubmit(form){Function} v0.5.0+
提交表单之前的回调,有一个参数:当前表单对象,如果在beforeSubmit内部返回false,将认为是取消本次提交
dataFilter(data){Function} v0.6.0+
使用dataFilter回调可以转换ajax返回的结果为niceValidator支持的格式
valid(form){Function}
表单验证成功后的回调,有一个参数:当前表单对象,支持事件绑定
invalid(form, errors){Function}
@param: {Element} form 表单DOM
@param: {Array} errors 错误消息数组
表单验证失败后的回调,支持事件绑定
以下配置与主题相关(一般在setTheme()中使用,或者全局配置)
defaultMsg{String}
默认: "{0} is not valid."
默认的错误消息,一般在全局配置里面配置一下就可以了
loadingMsg{String}
默认: "Validating..."
异步加载中的提示,一般在全局配置里面配置一下就可以了
showOk{Boolean | String}
默认: true
是否显示成功提示(注意:前提是有传ok的消息),如果设置成false在字段验证通过后将只是简单的隐藏消息。
还有另一种用法:如果传递一个字符串,在验证通过后将提示这个消息,如果设置成空字符串,将只显示一个成功的图标
11//字段验证通过后提示“正确”
$('form').validator({
showOk: "正确"
});
//对于simple_right主题,验证通过后默认不会提示,只是单纯的隐藏错误消息
//加上 showOk: "" 这个配置后,将显示一个通过的图标
$('form').validator({
theme: "simple_right",
showOk: ""
});
validClass{String}v0.7.0+
默认: "n-valid"
字段验证通过后自动给输入框添加的class名。
invalidClass{String}v0.7.0+
默认: "n-invalid"
字段验证失败后自动给输入框添加的class名。
formClass{String}
默认: ""
给表单额外添加的class名,用于自定义主题。这个class就是一个主题的样式命名空间
msgClass{String}
默认: ""
给消息额外添加的class名,用于自定义主题,控制消息样式。msgClass建议使用以下4个class之一,验证组件能够根据方向关键字智能识别并控制消息的显示位置,你也可以在这4个class的基础上再加上自己定义的class名,用空格隔开就可以了
msgClass: "n-top" //消息将自动显示在输入框上边
msgClass: "n-right" //消息将自动显示在输入框右边
msgClass: "n-bottom" //消息将自动显示在输入框下边
msgClass: "n-left" //消息将自动显示在输入框左边
msgClass: "n-right myclass" //消息将自动显示在输入框右边,你还可以通过myclass来定义更多样式
msgStyle{String}
默认: ""
有时候主题定义的消息样式的位置没有达到预期,就可以通过msgStyle参数传递css规则来精确控制消息位置
$('form').validator({
theme: "simple_right",
msgStyle: "margin-left:-10px; margin-top:10px;",
fields: {
'email': 'required;email;'
}
});
msgWrapper{String} v0.5.0+
默认: "span"
消息容器的标签名,多用于自定义主题
msgMaker{Function} v0.5.0+
默认: 内置消息构造器
消息构造器,可以用来自定义消息的结构
如下代码:
1$('#form').validator({
fields: {
'user[name]': 'required;username'
,'user[pwd]': 'required;password'
},
msgWrapper: 'div',
msgMaker: function(opt){
return '<span class="+ opt.type +">' + opt.msg + '</span>';
}
});
最后自动生成的消息为:
<div class="msg-box n-right" for="user[name]">
<span class="n-error">不能为空</span>
</div>
msgIcon{String}
默认: "<span class="n-icon"></span>"
icon图标模板,用于自定义主题,参见local文件夹下的配置文件
msgArrow{String}
默认: ""
小箭头模板,用于自定义主题,参见local文件夹下的配置文件
msgShow{Function}
默认: null
消息显示之前的回调,可用于自定义消息动画。有两个参数:当前消息的jQuery对象和消息类型。参见local文件夹下的配置文件
msgHide{Function}
默认: null
消息隐藏之前的回调,可用于自定义消息动画。有两个参数:当前消息的jQuery对象和消息类型。参见local文件夹下的配置文件
内置规则(rules)
公共定义:
1. 数值范围使用波浪线(~)表示,例如:6~(大于等于6)、~6(小于等于6)、6~16(6到16)
2. 大小比较使用 lt(小于)、lte(小于等于)、gt(大于)、gte(大于等于)、eq(等于)表示
3. 如果某个规则可以带参数,参数要使用方括号([])或者圆括号(())括起来,取决于你的习惯
规则 参数 描述 例子
required 必填项
required //不能为空
required(xxx) //满足xxx规则,才验证required
required(not, xxx) //如果值为空,或者xxx也认为是空
integer 可选,标识 整数
integer //请输入整数
integer[*] //请输入整数
integer[+] //请输入正整数
integer[+0] //请输入正整数或integer[-] //请输入负整数
integer[-0] //请输入负整数或match 可选,标识
必选, 另一字段名 与另一字段匹配,两种用法:
match[name];
用于验证两个字段的值必须相同
match[condition, name];
用于比较两个字段大小
match[password] //与password字段的值匹配
match[lt,money] //小于money字段的值
match[lte,money] //小于等于money字段的值
match[eq,money] //等于money字段的值匹配
match[gte,money] //大于等于money字段的值
match[gt,money] //大于money字段的值
range 必选,范围值 数值范围
range[0~99] //0到99的整数
range[~99] //小于或等于99的整数
range[0~] //大于或等于0的整数
length 必选,范围值
可选,是否计算真实长度 验证字符长度
length[6~16] //6-16个字符
length[6] //6个字符
length[~6] //小于6个字符
length[6~] //大于6个字符
length[~6, true] //小于6个字符,全角字符计算双字符
checked 可选,范围值 对于checkbox或radio
必须要选中多少项
checked //必填,相当于required
checked[3~5] //请选择3到5项
checked[3] //请选择3项
checked[~5] //请选择少于5项
checked[3~] //请选择大于3项
remote 必选,url地址
可选,附带额外的字段 远程验证
remote[path/to/server.php]
remote[path/to/server.php, name1, name2, ..]
方法(Methods)
1. 以下API描述中,使用 $form 代替form元素的jQuery对象,具体根据您的实际应用场景来决定
2. 所有使用 validator() 代理调用的方法,其返回值都是jQuery包装对象,可以继续链式调用
$form.validator( options )
根据传入的options,初始化表单验证
@param: {Object} options 配置参数
@return: {jqObject} $form
@example:
$('form').validator({
//自定义用于当前实例的规则
rules: {
username: function(element, params){
//内部的this指向的是当前实例,可以直接调用所有方法,这里调用了test方法
return this.test(element, 'email') || this.test(element, 'mobile') ||
'用户名可以输入邮箱或者手机号';
}
},
//自定义用于当前实例的消息
messages: {
required: "请填写{0}",
email: "邮箱地址不合法"
},
//待验证字段集合
fields: {
username: 'required; username;',
password: 'required; length[6~16]',
email: 'email;'
},
valid: function(form){
//表单验证通过,提交表单到服务器
$.ajax({
url: "result.php",
data: $(form).serialize(),
success: function(d){
//do something
}
});
}
});
$form.validator( validCallback ) v0.3.0+
初始化表单验证,在表单验证通过后执行validCallback回调
@param: {Function} validCallback 表单验证通过后的回调
@return: {jqObject} $form
@example:
//初始化验证,并且传入验证成功的回调
$('form').validator(function(form){
$(form).ajaxSubmit({
//some options
});
});
instance = $form.data( "validator" )
获取表单验证的实例
@base: 验证已经初始化
@return: {Object} 实例(instance)
@example:
//初始化验证,并且引用验证的实例
var v = $('form').validator().data('validator');
//使用实例的showMsg方法
v.showMsg('#mobile', '请填写手机号');
$input.isValid( callback ) v0.3.0+
判断某个字段是否验证通过($input代表表单元素的jQuery对象)
@base: 验证已经初始化
@param: {Function} callback 传入的回调
@return: {Boolean} 注意,如果有ajax的异步验证,返回值总是undefined
@example:
11//如果字段上面没有ajax验证,你可以像下面这样直接判断
if ( $('#mobile').isValid() ) {
// do something
}
//否则只能通过回调方式获取验证结果(用上面的方式将总是返回undefined)
$('#mobile').isValid(function(v){
if (v) {
// do something
}
});
$elements.isValid( callback ) v0.3.0+
判断某个区域是否验证通过($elements代表一个区域的jQuery对象)
@base: 验证已经初始化
@param: {Function} callback 传入的回调
@return: {Boolean} 注意,如果有ajax的异步验证,返回值总是undefined
@example:
//检测表单是否所有字段都验证通过
$('#formId').isValid(function(v){
console.log(v ? '表单验证通过' : '表单验证不通过');
});
instance.isFormValid() v0.7.0+
判断当前表单是否验证通过
注意:因为该方法有返回布尔值,所以只能通过实例的方式调用
@base: 验证已经初始化
@return: {Boolean} 当确定验证结果的时候,返回true或者false,当不确定的时候返回undefined
instance.cleanUp() v0.7.0+
或者 $form.validator( "cleanUp" )
调用该方法后,会清除表单中已经显示的验证消息
@base: 验证已经初始化
instance.destroy()
或者 $form.validator( "destroy" )
销毁表单验证,包括事件和实例
@base: 验证已经初始化
instance.holdSubmit( hold ) v0.4.0+
或者 $form.validator( "holdSubmit", hold )
用来禁止或者释放submit事件的验证和提交。
注意:如果你hold住了表单后一直不释放hold,这个表单就等于只能提交一次
@base: 验证已经初始化
@param: {Boolean} hold 是否控制住submit事件,默认true(不传参)
@example:
$("#myForm").validator({
valid: function(form){
var me = this;
// 提交表单之前,hold住表单,防止重复提交
me.holdSubmit();
$.ajax({
url: "xxx.php",
data: $(form).serialize(),
type: "POST",
success: function(){
// 提交表单成功后,释放hold,如果不释放hold,就变成了只能提交一次的表单
me.holdSubmit(false);
}
});
}
});
hold参数为true或者不传,表示要hold住,还可以为回调函数,也是要hold住,只不过在每次被hold住的时候都会执行该回调
$("#myForm").validator({
valid: function(form){
var me = this;
// 提交表单之前,hold住表单,并且在以后每次hold住时执行回调
me.holdSubmit(function(){
alert("正在处理中...");
});
$.ajax({
url: "xxx.php",
data: $(form).serialize(),
type: "POST",
success: function(){
// 提交表单成功后,释放hold,就可以再次提交
me.holdSubmit(false);
}
});
}
});
instance.test( element, ruleName )
测试某个元素是否符合某个规则,参数 ruleName 可以带参数,例如:this.test(element, "range[0~100]")
注意:
1、因为该方法有返回布尔值,所以只能通过实例的方式调用
2、该方法无法测试remote规则,以及其他异步验证的规则。
@base: 验证已经初始化
@param: {Element} element 字段元素
@param: {String} ruleName 规则名字
@return: {Boolean}
1111111$("#myForm").validator({
rules: {
// 自定义规则:符合用户名、手机号或者邮箱规则都算通过
// 注意:第一个test是正则的方法,后面两个是this.test()是当前实例的方法
loginName: function(element) {
return /^[a-zA-Z]\w{3,}/.test(element.value)
|| this.test(element, "mobile")===true
|| this.test(element, "email")===true
|| '请填写用户名、手机号或者邮箱';
}
},
fields: {
"loginName": "required; loginName",
"password": "required; password"
}
});
instance.mapMsg( obj )
或者 $form.validator( "mapMsg", obj )
用来显示服务器的验证消息。(提交表单并且服务器验证完毕后,返回一个name为键、msg为value的json传入此方法中)
@base: 验证已经初始化
@param: {Object} obj name为键、msg为值的对象
@example:
$('form').validator('mapMsg', {
username: '用户名已被使用',
password: '密码太弱了'
});
instance.showMsg( element, obj )
或者 $form.validator( "showMsg", element, obj )
在一个字段元素上显示一条消息
@base: 验证已经初始化
@param: {Element} element 要显示消息的元素,可以是jQuery选择器
@param: {Object} obj 消息的参数
@example:
//给id为“mobile”的元素显示一条错误消息
$('form').validator('showMsg', '#mobile', {
type: "error",
msg: "手机号已存在"
});
instance.hideMsg( element, obj )
或者 $form.validator( "hideMsg", element, obj )
隐藏一个字段元素上的消息
@base: 验证已经初始化
@param: {Element} element 要显示消息的元素,可以是jQuery选择器
@param: {Object} obj 消息的参数,可选
@example:
//隐藏id为“mobile”的的元素的消息
$('form').validator('hideMsg', '#mobile');
instance.setMsg( obj )
或者 $form.validator( "setMsg", obj )
自定义消息,可用来动态改变某个表单验证的消息(优先于内置、全局、传参的消息)
@base: 验证已经初始化
@param: {Object} obj rule名为键、msg为值的对象
@example:
//动态更改当前实例的错误消息
$('form').validator('setMsg', {
username: '用户名已被使用',
password: '密码太弱了'
});
instance.setRule( obj )
或者 $form.validator( "setRule", obj )
自定义规则,可用来动态改变某个表单验证的规则(优先于内置、全局、传参的规则)
@base: 验证已经初始化
@param: {Object} obj rule名为键、msg为值的对象
@example: 以下示例展现了两种定义规则的方式
//动态更改当前实例的规则
$('form').validator('setRule', {
username: [/^\w{3,12}$/, "请输入3-12位数字、字母、下划线"],
password: function(element, params, field){
//do something...
//If verification returns true, otherwise it returns an error message
}
});
instance.setField( key, field )
或者 $form.validator( "setField", key, field )
更新一个字段信息.
如果是新字段就等于添加了一个字段;
如果field===null,并且实例中存在字段key,则会删除字段key(不验证key字段)
@base: 验证已经初始化
@param: {String} key 字段名
@param: {String | Object} field 字段信息
@example:
//动态更改字段name为“username”的验证规则
$('form').validator("setField", "username", "用户名:required;username;");
instance.setField( fields )
或者 $form.validator( "setField", fields )
批量更新字段信息.
如果是新字段就等于添加了一个字段;
如果某个字段的值为null,并且实例中存在该字段,则会删除该字段(不验证该字段)
@base: 验证已经初始化
@param: {Object} fields 字段信息,参见options中fields的配置
@example:
//批量更改字段的验证规则
$('form').validator('setField', {
foo: null, //将不再验证foo字段
bar: 'required' //更改bar字段的验证规则
});
$.validator.config( options )
全局配置接口,参见配置参数,以及local文件夹下的配置文件
$.validator.setTheme( options )
设置验证的主题,参见local文件夹下的配置文件
事件(Events)
validitionv0.7.0+
每次验证完一个字段,都会触发该事件,此事件需要绑定在form上面,利用此事件可以实时监测表单的验证结果
@example:
$("#form").on("validation", function(e, current){
// 表单全部字段验证通过则返回 true
// 只要有一个字段验证不通过就返回 false
// 还没验证完,即验证结果未知的情况下返回 undefined
console.log(this.isValid);
// 当前正在验证的字段是否通过
console.log(current.isValid);
})
valid.form
表单验证成功,同options中valid
@example:
$('#form').on('valid.form', function(e, form){
//do something...
});
invalid.form
表单验证失败,同options中invalid
@example:
$('#form').on('invalid.form', function(e, form, errors){
//do something...
});
valid.field
字段验证成功
@example:
$('input[name="username"]').on('valid.field', function(e, result, me){
//do something...
});
invalid.field
字段验证失败
@example:
$('input[name="username"]').on('invalid.field', function(e, result, me){
//do something...
});
valid.rule
字段规则验证成功
@example:
$('input[name="username"]').on('valid.rule', function(e, ruleName){
//“remote”规则验证通过时
if (ruleName === 'remote') {
//do something...
}
});
invalid.rule
字段规则验证失败
@example:
$('input[name="username"]').on('invalid.rule', function(e, ruleName){
//“remote”规则验证失败时
if (ruleName === 'remote') {
//do something...
}
});
$input.trigger("validate");
手动触发元素进行验证
@example:
//手动触发username字段验证
$('input[name="username"]').trigger("validate");
$form.trigger("validate"); v0.7.0+
手动触发表单进行验证,验证通过后不会自动提交
@example:
//手动触发表单验证
$('#form').trigger("validate");
$form.trigger("submit");
手动触发表单提交,在提交前会自动验证
@example:
//手动触发表单提交
$('#form').trigger("submit");
$input.trigger("showtip"); v0.5.0+
触发元素显示tip消息
@example:
//验证初始化完成后,立即显示所有字段的提示
$('#form').validator().trigger("showtip");