# 快速上手 (Getting Started)
## 1. 加載插件
> nice-validator 依賴 [jQuery][1](https://validator.niceue.com/docs/1.7+)。除了直接引用插件,還支持 AMD 模塊系統。
### (1)、直接引用
一行代碼引入插件,local 參數用來加載對應的配置文件。如果不傳 local 參數,配置以及樣式就需要自行引入
```html
<script src="path/to/nice-validator/jquery.validator.js?local=zh-CN"></script>
```
### (2)、通過 [RequireJS](http://requirejs.org/) 模塊系統
```js
requirejs.config({
paths: {
jquery: 'http://cdn.jsdelivr.net/jquery/1.12.3/jquery.min',
validator: 'path/to/nice-validator/local/zh-CN'
},
shim: {
validator: ['path/to/nice-validator/jquery.validator.js?css']
}
});
require(['jquery', 'validator'], function($){
$('#form1').validator();
});
```
## 2. 了解規則
### (1)、定義規則語句
```
"display: rule1; rule2(p1, p2); ...rulen(n1~n2)"
```
> 1. 前面的 display: 是可選的,用于替換錯誤消息中的{0},一般為顯示的字段名。
> 2. 多個規則由分號(;)分開,末尾分號可省略,不限制規則數量,按規則先后順序執行驗證
> 3. 未定義的規則自動忽略,對驗證不產生影響
#### 規則語句中的符號:
- 分號 `;` - 分隔多個規則,也代表**邏輯與**
- 冒號 `:` - 分隔 display(字段顯示名)與規則語句
- 括號 `()` - 規則傳參使用,也可以使用方括號([ ])
- 逗號 `, ` - 分隔規則的參數,**注意:逗號后需加空格**
- 波浪 `~` - 定義范圍值使用
- 俺的 `&` - **邏輯與**,用在某個規則前面,與;(分號)效果差不多
- 嘆號 `!` - **邏輯非**,用在某個規則前面,對規則取反
- 豎線 `|` - **邏輯或**,用在多個規則之間,多個規則滿足之一則通過
**示例**:
```javascript
// 單個規則
"required"
// 多個規則
"required; email; remote(/server/check/email)"
// 范圍參數
"range(1~100)"
// 規則有多個參數
"match(neq, oldPassword)"
// 定義顯示替換名稱
"郵箱: required; email"
// 邏輯或
"required; mobile|email; remote(/server/check/user)"
// 邏輯非
"required; !digits"
```
### (2)、配置規則
**示例**:DOM 配置規則,使用 data-rule
```html
<input name="email" data-rule="required;email;remote(/path/to/server)">
```
**示例**:JS 配置規則,使用 [fields](https://validator.niceue.com/docs/options.html#section-1-16) 參數
```javascript
$("#form").validator({
fields: {
email: "required;email;remote(/path/to/server)"
}
});
```
### (3)、內置規則
插件內置 8 個規則:
* [required - 使字段必填](https://validator.niceue.com/docs/core-rules.html#section-1)
* [checked - 必選,還可以控制選擇項目的數量](https://validator.niceue.com/docs/core-rules.html#section-2)
* [match - 當前字段與另一個字段比較](https://validator.niceue.com/docs/core-rules.html#section-3)
* [remote - 獲取服務器端驗證的結果](https://validator.niceue.com/docs/core-rules.html#section-4)
* [integer - 只能填寫整數](https://validator.niceue.com/docs/core-rules.html#section-5)
* [range - 只能填寫指定范圍的數](https://validator.niceue.com/docs/core-rules.html#section-6)
* [length - 字段值必須符合指定長度](https://validator.niceue.com/docs/core-rules.html#section-7)
* [filter - 過濾當前字段的值,不做驗證](https://validator.niceue.com/docs/core-rules.html#section-8)
自定義規則如果與內置規則同名,則自定義規則優先
詳情參考[內置規則](https://validator.niceue.com/docs/core-rules.html)
### (4)、自定義規則
詳情參考[自定義規則](https://validator.niceue.com/docs/custom-themes.html)
**示例**:在 `local/zh-CN.js` 中配置全局規則(**全局生效**)
```js
$.validator.config({
rules: {
mobile: [/^1[3-9]\d{9}$/, "請填寫有效的手機號"],
chinese: [/^[\u0391-\uFFE5]+$/, "請填寫中文字符"]
}
});
```
**示例**:通過 DOM 方式自定義規則(**只對當前字段有效**)
```html
<input name="demo" data-rule="required; xxx" data-rule-xxx="[/^\d{6}$/, '請輸入6位數字']">
```
**示例**:通過 [rules](https://validator.niceue.com/docs/options.html#section-1-14) 配置規則(**當前表單實例有效**)
```js
$('#form1').validator({
rules: {
// 使用正則表達式定義規則
mobile: [/^1[3-9]\d{9}$/, "請填寫有效的手機號"],
// 使用函數定義規則
xxx: function(elem, param) {
return /^1[3458]\d{9}$/.test($(elem).val()) || '請檢查手機號格式';
}
},
fields: {
// 對字段 username 應用規則 mobile
'username': 'required;mobile'
}
});
```
## 3. 初始化驗證
#### (1)、DOM 綁定規則,無需 JS 代碼
```html
<form id="form1" action="register.php">
<label>Email</label>
<input type="email" name="email" data-rule="required;email">
<label>Password</label>
<input type="password" name="pwd" data-rule="required;length(6~16)">
</form>
```
參考[DOM 綁定](https://validator.niceue.com/docs/dom-bindings.html)
#### (2)、JS 配置規則,無侵入 DOM
```html
<form id="form1" action="register.php">
<label>Email</label>
<input type="email" name="email">
<label>Password</label>
<input type="password" name="pwd">
</form>
// 初始化驗證
$('#form1').validator({
fields: {
'email': 'required;email',
'pwd': 'required;length(6~16)'
}
});
```
調用插件方法 [.validator()](https://validator.niceue.com/docs/methods.html#section-1-1),并使用 [fileds](https://validator.niceue.com/docs/options.html#section-1-16) 參數
當然,DOM 和 JS 兩種方式也支持同時使用,你也可以通過 DOM 綁定規則,然后使用 js 初始化。
## 4. 提交表單
> 1. nice-validator 一旦初始化就會阻止表單被提交,直到表單規則全部驗證通過。
> 2. 如果傳遞了`valid`參數回調或者`valid.form`事件,表單即使驗證通過也不會被提交,而是由`valid`參數和`valid.form`事件接管。然后你需要自己決定如何提交表單。
#### 方式一:點擊提交按鈕,表單驗證通過后自動原生方式提交
```html
<form id="form1" action="register.php">
<label>Email</label>
<input type="email" name="email" data-rule="required;email">
<label>Password</label>
<input type="password" name="pwd" data-rule="required;length(6~16)">
<button type="submit">提交</button>
</form>
```
#### 方式二:使用驗證通過回調(參考:[valid](https://validator.niceue.com/docs/options.html#section-1-11))
```js
$('#form1').validator({
valid: function(form) {
// do something
// use native submit.
form.submit();
}
});
```
#### 示例三:綁定表單驗證通過的事件(參考:[valid.form事件](https://validator.niceue.com/docs/events.html#section-1-2))
```js
$('#form1').on('valid.form', function(e){
// You can do something, then submit form by native
// this.submit();
// or use ajax submit
$.post("path/to/server", $(this).serialize())
.done(function(d){
// some code
});
});
```