# 快速上手 （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
});
});
```
