[TOC]
## 核心参数
### **debug - 调试**
**类型**：`Number`
**默认**：`0`
**可用值**：
* `0`：关闭调试信息
* `1`：开启调试信息（查看浏览器控制台）
* 2`：开启调试，无视验证结果直接触发验证通过事件
### **timely - 实时验证**
**类型**：`Number`
**默认**：`1`
**可用值**：
* `0`：关闭实时验证，只在提交表单的时候执行验证
* `1`：输入框失去焦点（focusout）时执行验证
* `2`：输入框改变值（input）时执行验证
* `3`：输入框失去焦点和改变值（综合 1 + 2） (`v0.8.0+`)
* `8`：同 2，并且详细提示每个规则的结果 (`v0.9.0+`)
* `9`：同 3，并且详细提示每个规则的结果 (`v0.9.0+`)
* 大于 100 的数值：验证延迟时间
### **theme - 主题**
**类型**：`String`
**默认**：`"default"`
主题名称，每个表单验证实例可以设置不同的主题。参考[自定义主题](https://validator.niceue.com/docs/custom-themes.html)，以及 zh-CN.js 的主题配置
### **stopOnError - 在第一次错误时停止验证**
**类型**：`Boolean`
**默认**：`false`
### **focusInvalid - 第一个错误字段自动获得焦点**
**类型**：`Boolean`
**默认**：`true`
### **focusCleanup - 输入框获得焦点时清除验证消息**
**类型**：`Boolean`
**默认**：`false`
### **ignoreBlank - 不验证空值的字段（只针对实时验证）**
**支持**：`v0.8.0+`
**类型**：`Boolean`
**默认**：`false`
### **ignore - 忽略验证 jQuery 选择器选中的字段**
**类型**：`jqSelector`
**默认**：`""`
**示例**：
~~~javascript
//任何不可见的元素，都不作验证
$('form').validator({
ignore: ':hidden'
});
//id为tab2下的所有子元素都不作验证
$('form').validator({
ignore: '#tab2'
});
//动态改变要忽略验证的元素
$('form').data('validator').options.ignore = '#tab1';
~~~
### **display - 自定义消息中`{0}`的替换字符**
**类型**：`Function(elem)`
**默认**：`null`
**示例**：
~~~javascript
$('form').validator({
display: function(elem){
return $(elem).closest('.form-item').children('label:eq(0)').text();
}
});
~~~
### **target - 自定义消息的显示位置**
**类型**：`Function(elem) | jqSelector`
**默认**：`null`
**描述**：验证当前字段，但是实际上在 target 的元素上提示错误消息。
1、如果目标元素是输入框（input，textarea、select），将会以目标元素为基准点，插入一条消息；
2、如果目标元素是**消息占位**（class="msg-box"），这和直接使用消息占位没有区别；
3、其他情况下，直接显示在target指向的**消息容器**中。
消息容器与消息占位的区别：消息占位只能包含一条消息，消息容器可以容纳很多消息。
**示例**：
~~~javascript
$('form').validator({
// 自己指定消息容器位置
target: function(elem){
var $formitem = $(elem).closest('.form-item'),
$msgbox = $formitem.find('span.msg-box');
if (!$msgbox.length) {
$msgbox = $('<span class="msg-box"></span>').appendTo($formitem);
}
return $msgbox;
}
});
$('form').validator({
// 将所有消息全部提示在 id 为 myContainer 里面
target: "#myContainer"
});
~~~
### **valid - 表单验证通过时调用此函数**
**类型**：`Function(form)`
**默认**：`null`
**描述**：表单验证成功后的回调。也可以使用[valid.form](https://validator.niceue.com/docs/events.html#section-1-2)事件
**示例**：ajax 提交表单
~~~javascript
$('#form1').validator({
fields: {
username: "required; email|mobile; remote(/check/username)",
password: "required; length(6~16)",
passwordAgain: "match(password)"
},
valid: function(form){
// 表单验证通过，提交表单
$.post("path/to/server", $(form).serialize())
.done(function(d){
// some code
});
}
});
~~~
### **invalid - 表单验证不通过时调用此函数**
**类型**：`Function(form, errors)`
**默认**：`null`
**描述**：表单验证失败后的回调。也可以使用[invalid.form](https://validator.niceue.com/docs/events.html#section-1-3)事件
**示例**：摇晃提交按钮（需要[animate.css](http://daneden.github.io/animate.css/)支持）
~~~javascript
$('#form1').validator({
invalid: function(form, errors){
var CLS_ANIMATE = 'shake animated';
$('#submitBtn').addClass(CLS_ANIMATE)
.one('animationend webkitAnimationEnd mozAnimationEnd', function(){
$(this).removeClass(CLS_ANIMATE);
});
}
});
~~~
### **validation - 验证每个字段后调用此函数**
**类型**：`Function(form)`
**默认**：`null`
**描述**：验证完每个字段时的回调。也可以使用[validation](https://validator.niceue.com/docs/events.html#section-1-1)事件
**示例**：只有在全部字段都验证通过时，提交按钮才可用
~~~javascript
$('#form1').validator({
validation: function(element, result){
$("#submitBtn").prop('disabled', !element.form.isValid)
}
});
~~~
### **rules - 自定义规则**
**类型**：`Object`
**默认**：`null`
**示例**：自定义用于当前实例的规则，支持两种定义方式
~~~javascript
$('form').validator({
rules: {
// 自定义验证函数，具有最大的灵活性
myRule: function(el, param, field){
//do something...
},
// 简单配置正则及错误消息
another: [/^\w*$/, 'Please enter the letters or underscore.']
},
fields: {
//调用前面定义的两个规则
foo: 'required; myRule[param]; another'
}
});
~~~
### **messages - 自定义消息**
**类型**：`Object`
**默认**：`null`
**描述**：自定义用于当前实例的规则消息。当有多个字段使用同一个规则，而这个规则没有消息或需要覆盖它的消息，则使用 messages 统一配置比较方便。消息中可以包含`{0}`模板变量，会自动替换成 display 的值
**示例**：
~~~javascript
$('form').validator({
messages: {
required: "Please fill in this field",
email: "Please enter a valid email address.",
},
fields: {
'email': 'required;email;'
}
});
~~~
### **fields - 配置字段规则及参数**
**类型**：`Object`\- 待验证的字段集合，键为字段的 name 值或者 #id
**默认**：`null`
**参数**：
* fields\[key\].`rule`
字段规则，多个规则用分号 “;” 分隔，支持使用圆括号 “( )” 或者方括号 “\[ \]” 传参
* fields\[key\].`msg`
自定义字段中每个规则的错误消息
* fields\[key\].`tip`
自定义获得焦点时的友好提示信息
* fields\[key\].`ok`
自定义字段验证成功后显示的消息
* fields\[key\].`valid`
字段验证通过的回调
* fields\[key\].`invalid`
字段验证失败的回调
* fields\[key\].`timely`
是否启用实时验证，默认继承
* fields\[key\].`target`
验证当前字段，但是实际上在 target 的元素上提示错误消息，
如果目标元素是输入框（input，textarea、select），将会以目标元素为基准点，插入一条消息；
如果目标元素是消息占位（className 为 msg-box），这和直接使用消息占位没有区别
其他情况下，直接显示在target指向的容器中
* fields\[key\].`dataFilter`
使用 dataFilter 回调可以转换 ajax 返回的结果为 nice-validator 支持的格式
* fields\[key\].`must`
是否强制验证该字段
* fields\[key\].`msgWrapper`
自定义该字段的消息容器的标签名
* fields\[key\].`msgMaker`
自定义该字段的消息生成器
* fields\[key\].`msgClass`
自定义该字段的消息Class
* fields\[key\].`msgStyle`
自定义该字段的消息 CSS 样式
* fields\[key\].`getValue`（`v1.0.0+`）
自定义 value 的 getter
* fields\[key\].`setValue`（`v1.0.0+`）
自定义 value 的 setter
**示例**：快捷传参和对象传参
~~~javascript
fields: {
//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"
}
~~~
### **beforeSubmit - 在提交表单之前调用此函数**
**类型**：`Function(form)`
**默认**：`null`
一次 submit 事件触发的流程：
1. 接收 form 的 submit 事件；
2. 执行 beforeSubmit 回调，如果 beforeSubmit 返回值为 false，将取消本次验证与提交；
3. 验证整个表单；
4. 根据表单验证结果决定执行 valid 回调还是 invalid 回调
### **dataFilter - 转换ajax返回数据为插件支持的格式**
**类型**：`Function(data)`
**默认**：`null`
**示例**：如果服务端返回格式无法更改，可以用[dataFilter](https://validator.niceue.com/docs/options.html#section-1-18)参数转换
~~~javascript
/* 假设服务端返回结果为： {"status":600, "msg":"名字已被占用"}
*/
$('#form1').validator({
dataFilter: function(data) {
if (data.status === 200) return "";
else return data.msg;
},
fields: {
name: "required; length(4~12); remote(/user/check/name)"
}
});
~~~
* * *
## 主题相关参数
### **showOk - 是否显示成功提示**
**类型**：`Boolean|String`
**默认**：`true`
是否显示成功提示（注意：前提是有传ok的消息），如果设置成false在字段验证通过后将只是简单的隐藏消息。
还有另一种用法：如果传递一个字符串，在验证通过后将提示这个消息，如果设置成空字符串，将只显示一个成功的图标
~~~javascript
//字段验证通过后提示“正确”
$('form').validator({
showOk: "正确"
});
//对于simple_right主题，验证通过后默认不会提示，只是单纯的隐藏错误消息
//加上 showOk: "" 这个配置后，将显示一个通过的图标
$('form').validator({
theme: "simple_right",
showOk: ""
});
~~~
### **validClass - 给验证通过的输入框添加的class名**
**类型**：`String`
**默认**：`n-valid`
### **invalidClass - 给验证不通过的输入框添加的class名**
**类型**：`String`
**默认**：`n-invalid`
### **bindClassTo - 设置 validClass 和 invalidClass 添加到的位置**
**支持**：`v0.9.0+`
**类型**：`jqSelector`
**默认**：`:verifiable`
**示例**：适配[Bootstrap](http://v3.bootcss.com/css/#forms-control-validation)样式
~~~html
<form id="form1">
<div class="form-group">
<label for="email">Email address</label>
<input type="email" name="email" id="email" class="form-control" placeholder="Email">
</div>
</form>
~~~
~~~javascript
$('#form1').validator({
validClass: "has-succes",
invalidClass: "has-error",
bindClassTo: ".form-group",
fields: {
email: "required; email"
}
});
~~~
### **formClass - 主题的 class 名称，添加在 form 上**
**类型**：`String`
**默认**：`n-default`
### **msgClass - 字段消息的 class 名称，添加在消息容器上**
**类型**：`String`
**默认**：`n-right`
**示例**：
~~~javascript
msgClass: "n-top" //消息将自动显示在输入框上边
msgClass: "n-right" //消息将自动显示在输入框右边
msgClass: "n-bottom" //消息将自动显示在输入框下边
msgClass: "n-left" //消息将自动显示在输入框左边
msgClass: "n-right myclass" //消息将自动显示在输入框右边，你还可以通过myclass来定义更多样式
~~~
### **msgStyle - 自定义 CSS 样式，添加在消息容器上**
**类型**：`String`
**默认**：`""`
**示例**：
~~~javascript
// 有时候主题定义的消息样式的位置没有达到预期，就可以通过 msgStyle 参数传递 css 来精确控制消息位置
$('form').validator({
theme: "simple_right",
msgStyle: "margin-left:-10px; margin-top:10px;",
fields: {
'email': 'required;email;'
}
});
~~~
### **msgWrapper - 消息容器的 tagName**
**类型**：`String`
**默认**：`span`
### **msgMaker - 自定义消息 HTML 结构**
**类型**：`Function(obj)`|`Boolean`
**默认**：`null`
**说明**：msgMaker 生成的消息 HTML 会插入到对应的 msgWrapper 中，如果不想生成消息，可以设置`msgMaker:false`
**示例**：
~~~javascript
$('#form').validator({
fields: {
'user[name]': 'required;username'
,'user[pwd]': 'required;password'
},
msgWrapper: 'div',
msgMaker: function(opt){
return '<span class="'+ opt.type +'">' + opt.msg + '</span>';
}
});
~~~
以上 msgMaker 配置，将生成如下消息结构
~~~html
<div class="msg-box n-right" for="user[name]">
<span class="n-error">Please fill this field.</span>
</div>
~~~
### **msgIcon - 自定义消息图标的 HTML 模板**
**类型**：`String`
**默认**：`"<span class="n-icon"></span>"`
### **msgArrow- 自定义消息箭头的 HTML 模板**
**类型**：`String`
**默认**：`""`
### **msgShow - 消息提示之前调用此函数**
**类型**：`Function($msgbox, type)`
**默认**：`null`
### **msgHide - 消息隐藏之前调用此函数**
**类型**：`Function($msgbox, type)`
**默认**：`null`
