## 核心參數
### 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` **默認**:`""` **示例**:
~~~
?//任何不可見的元素,都不作驗證
?$('form').validator({
? ? ?ignore: ':hidden'
?});
?//id為tab2下的所有子元素都不作驗證
?$('form').validator({
? ? ?ignore: '#tab2'
?});
?//動態改變要忽略驗證的元素
?$('form').data('validator').options.ignore = '#tab1';
~~~
### display - 自定義消息中`{0}`的替換字符
**類型**:`Function(elem)` **默認**:`null` **示例**:
~~~
?$('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指向的**消息容器**中。
消息容器與消息占位的區別:消息占位只能包含一條消息,消息容器可以容納很多消息。
**示例**:
~~~
?$('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 提交表單
~~~
?$('#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/) 支持)
~~~
?$('#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) 事件 **示例**:只有在全部字段都驗證通過時,提交按鈕才可用
~~~
?$('#form1').validator({
? ? ?validation: function(element, result){
? ? ? ? ?$("#submitBtn").prop('disabled', !element.form.isValid)
? ? }
?});
~~~
### rules - 自定義規則
**類型**:`Object` **默認**:`null` **示例**:自定義用于當前實例的規則,支持兩種定義方式
~~~
?$('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 的值 **示例**:
~~~
?$('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
**示例**:快捷傳參和對象傳參
~~~
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) 參數轉換
~~~
/* 假設服務端返回結果為: {"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在字段驗證通過后將只是簡單的隱藏消息。 還有另一種用法:如果傳遞一個字符串,在驗證通過后將提示這個消息,如果設置成空字符串,將只顯示一個成功的圖標
~~~
//字段驗證通過后提示“正確”
$('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) 樣式
~~~
<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>
$('#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` **示例**:
~~~
msgClass: "n-top" //消息將自動顯示在輸入框上邊
msgClass: "n-right" //消息將自動顯示在輸入框右邊
msgClass: "n-bottom" //消息將自動顯示在輸入框下邊
msgClass: "n-left" //消息將自動顯示在輸入框左邊
msgClass: "n-right myclass" //消息將自動顯示在輸入框右邊,你還可以通過myclass來定義更多樣式
~~~
### msgStyle - 自定義 CSS 樣式,添加在消息容器上
**類型**:`String` **默認**:`""` **示例**:
~~~
?// 有時候主題定義的消息樣式的位置沒有達到預期,就可以通過 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` **示例**:
~~~
?$('#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 配置,將生成如下消息結構
~~~
?<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`
### [**](https://validator.niceue.com/docs/options.html#section-2-13)msgHide - 消息隱藏之前調用此函數
**類型**:`Function($msgbox, type)` **默認**:`null`