選項 · nice-validator

[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`