开发者文档
强大的表单校验器,通过简单的配置规则即可实现表单校验。
并且支持自定义校验插件。
- 更新 v1.4.3: 增加了 gt, lt 两个规则。
- 更新 v1.4.2: 修复了校验报错消息中图标是斜体的bug。
- 更新 v1.2.2: 增加了两个新的接口可以直接控制错误消息 "showError" 和 "hideError",可以手动调用来显示/隐藏一个错误消息。增加了一个disable/enable接口,可以启用/禁用表单校验。
- 更新 v1.1.9: 自定义错误消息区分未填写和填写错误两种情况,可以分别定义。
- 更新 v1.1.7: 修复了url校验规则无法支持二级域名的bug,增加了一个出错消息配置,可以单独配置每一个输入框的错误消息。
通过HTML配置规则
通过html标签可以直接配置规则,不用写任何js代码,在form上加上 .sui-validate
之后会自动初始化校验器。
规则通过input标签的 data-rules
来定义,以 | 分割不同的规则,每个规则由规则名和规则值组成,规则值是可选的。
比如:data-rules='required|email|minlength=8'
- <form class="sui-form form-horizontal sui-validate">
- <div class="control-group">
- <label for="inputEmail" class="control-label">邮箱:</label>
- <div class="controls">
- <input type="text" id="inputEmail" name="name" placeholder="邮箱" data-rules="required|email">
- </div>
- </div>
- <div class="control-group">
- <label for="inputPassword" class="control-label">密码:</label>
- <div class="controls">
- <input type="password" id="inputPassword" name="password" placeholder="密码" data-rules="required" title="密码">
- </div>
- </div>
- <div class="control-group">
- <label for="inputRepassword" class="control-label">重复密码:</label>
- <div class="controls">
- <input type="password" id="inputRepassword" name="repassword" placeholder="重复密码" data-rules="required|match=password">
- </div>
- </div>
- <div class="control-group">
- <label for="inputGender" class="control-label">性别:</label>
- <div class="controls">
- <label data-toggle="radio" class="radio-pretty inline">
- <input type="radio" name="gender" value="1" data-rules="required"><span>男</span>
- </label>
- <label data-toggle="radio" class="radio-pretty inline">
- <input type="radio" name="gender" value="2" data-rules="required"><span>女</span>
- </label>
- </div>
- </div>
- <div class="control-group">
- <label for="inputPassword" class="control-label">年龄:</label>
- <div class="controls">
- <input type="text" id="inputPassword" name="age" placeholder="整数,需要小于100" data-rules="required|number|lt=100" title="年龄">
- </div>
- </div>
- <div class="control-group">
- <label for="inputGender" class="control-label">地址:</label>
- <div class="controls"><span class="sui-dropdown dropdown-bordered select"><span class="dropdown-inner"><a role="button" data-toggle="dropdown" href="#" class="dropdown-toggle">
- <input name="city" type="hidden" data-rules="required"><i class="caret"></i><span>请选择</span></a>
- <ul id="menu4" role="menu" aria-labelledby="drop4" class="sui-dropdown-menu">
- <li role="presentation"><a role="menuitem" tabindex="-1" href="javascript:void(0);" value="bj">北京</a></li>
- <li role="presentation"><a role="menuitem" tabindex="-1" href="javascript:void(0);" value="sb">圣彼得堡</a></li>
- </ul></span></span></div>
- </div>
- <div class="control-group">
- <label for="inputDes" class="control-label v-top">自我介绍:</label>
- <div class="controls">
- <textarea id="inputDes" name="des" placeholder="自我介绍" data-rules="required"></textarea>
- </div>
- </div>
- <div class="control-group">
- <label class="control-label"></label>
- <div class="controls">
- <button type="submit" class="sui-btn btn-primary">立即注册</button>
- </div>
- </div>
- </form>
- 复制代码代码已复制
通过JS配置规则
除了在html中直接配置规则,也可以在js中配置规则,两者可以结合使用,在JS中配置的规则会覆盖掉html中的同名规则。
HTML中的规则值只能为字符串,而JS中可以把规则值配置为函数从而实现更强大的功能。
- <form id="form5" class="sui-form form-horizontal" novalidate="novalidate">
- <div class="control-group">
- <label for="inputEmail" class="control-label">邮箱:</label>
- <div class="controls">
- <input type="text" id="inputEmail" name="email" placeholder="邮箱">
- </div>
- </div>
- <div class="control-group">
- <label for="inputPassword" class="control-label">密码:</label>
- <div class="controls">
- <input type="password" id="inputPassword" name="password" placeholder="密码" title="密码">
- </div>
- </div>
- <div class="control-group">
- <label for="inputRepassword" class="control-label">重复密码:</label>
- <div class="controls">
- <input type="password" id="inputRepassword" name="repassword" placeholder="重复密码">
- </div>
- </div>
- <div class="control-group">
- <label for="inputGender" class="control-label">性别:</label>
- <div class="controls">
- <label data-toggle="radio" class="radio-pretty inline">
- <input type="radio" name="gender" value="1"><span>男</span>
- </label>
- <label data-toggle="radio" class="radio-pretty inline">
- <input type="radio" name="gender" value="2"><span>女</span>
- </label>
- </div>
- </div>
- <div class="control-group">
- <label for="sanwei" class="control-label">三维:</label>
- <div class="controls">
- <input type="text" id="sanwei" name="sanwei" placeholder="三维">
- <div class="sui-msg msg-tips msg-naked">
- <div class="msg-con">女生必填</div>
- <s class="msg-icon"></s>
- </div>
- </div>
- </div>
- <div class="control-group">
- <label for="sanwei" class="control-label"></label>
- <div class="controls">
- <button type="submit" class="sui-btn btn-primary">立即注册</button>
- </div>
- </div>
- </form>
- <script>
- $("#form5").validate({
- rules: {
- email: {
- required: true,
- minlength: 2,
- maxlength: 10
- },
- password: {
- required: true,
- minlength: 6,
- maxlength: 12
- },
- repassword: {
- required: true,
- prefill: 'password',
- match: 'password'
- },
- sanwei: {
- required: function($input) {
- var value = $input.val()
- var $form = $input.parents("form")
- var gender = $form.find("[name='gender']:checked").val()
- if (gender == 2 && !value) {
- return false
- }
- return true
- }
- },
- gender: {
- required: true
- }
- },
- messages: {
- email: "亲,你连邮箱都没有么"
- },
- success: function() {
- $.alert("恭喜,没有问题了。");
- return false;
- }
- })
- </script>
一,通过两种方式可以启用表单校验
- 通过在form上添加
.sui-validate
- 通过直接调用js方法
$("form").validate()
校验组件依赖name属性,所以请确保表单中的元素有合理的name。 部分规则如prefill会依赖title属性。
注意:表单校验需要依赖input元素的 name
属性。
二,配置说明
调用validate方法的时候可以传入一个配置对象,所有配置项如下:
名称 | 默认值 | 说明 |
---|---|---|
errorTpl | <div class="sui-msg msg-error">\n <div class="msg-con">\n <span>$errorMsg</span>\n <s class="msg-icon"></s>\n </div>\n</div> | 错误提示模板,其中的变量 $errorMsg 是错误消息 |
inputErrorClass | input-error | 出错的input会被添加这个class以高亮显示 |
placeError | function($error, $input) { /**参见源码**/ } |
放置错误提示信息,在显示错误信息之前,会调用此方法把错误信息放在合适的位置
其中两个参数分别是:
|
rules | undefined | 定义规则,注意和$.validate.setRule区别,这里是定义某一个input的规则,和data-rules功能相似但是比它的优先级更高。 rules通过name来为input指定规则,比如 rules: { password: { minlength: 10}} 表示为 name=password 的输入框定义了一条规则 minlength=10 |
messages | undefined | 可以给每一个输入框单独设定出错消息,仍然是通过输入框的name来指定,出错消息可以是一个字符串或者回调函数。 比如: messages: { email: "亲,请输入你的邮箱"} 表示name为email的输入框出错后,总是显示"亲,请输入你的邮箱"。 如果想分别设定未填写和填写错误的消息,则可以传入一个数组,数组中第一个元素是未填写的出错消息,第二个元素是填写错误的出错消息。 比如: messages: { email: ["请填写您的邮箱", "亲,请输入你的邮箱"]} |
highlight | highlight: function($input, $error, inputErrorClass) { $input.addClass(inputErrorClass) $error.show() } | 高亮显示错误。 |
unhighlight | unhighlight: function($input, $error, inputErrorClass) { $input.removeClass(inputErrorClass) $error.hide() } | 取消高亮显示错误。 |
success | success: function(){$form} {} | 当用户提交表单且没有错误发生时调用此方法。如果返回值为false,则会阻止表单的默认提交行为。 |
fail | fail: function(){$errorInputs, $form} {} | 当用户提交表单且有错误发生时调用此方法。 |
三,配置规则
有两种方法可以配置规则:直接在html中写 data-rules
或者在初始化validate时传入rules对象。
后配置的规则总是会覆盖先配置的规则,所以js中配置的规则也总是会覆盖在html中配置的规则。
方法 | 示例 | 说明 |
---|---|---|
$.fn.validate(config) | $('#my-form').validate() | 启用表单校验,config详情见"文档" |
showError | $('#my-form').validate("showError", "email", "邮箱填错啦", "myEmailError") | 显示一个错误,其中四个参数分别是("showError", "输入框的name", "要显示的错误消息", "可选,该错误消息的名称,用来在hideError的时候引用") |
hideError | $('#my-form').validate("hideError", "email", "myEmailError") | 隐藏一个错误消息,其中三个参数分别是("hideError", "输入框的name,不填则隐藏所有的错误消息", "可选,要隐藏的错误消息的名称(在showError时指定的,或者就是规则名称),如果不填则会影藏该输入框对应的所有错误消息") |
enable/disable | $('#my-form').validate("enable/disable") | 启用/禁用表单校验 |
$.validate.setRule(name, method, msg) | var mobile = function(value, element, param) { return (/^0?1[3|4|5|7|8][0-9]\d{8,9}$/).test(trim(value)); }; Validate.setRule("mobile", mobile, '请填写正确的手机号码'); | 设置一条自定义规则,如果该规则已经存在则直接覆盖。 其中三个参数分别是:
|
$.validate.setMsg(ruleName, msg) | $.validate.setMsg('required', '亲,不要忘了填哦') | 自定义错误消息,其中msg参数和setRule中的msg参数一样既可以是字符串,也可以是函数。 |
事件
事件 | 说明 |
---|---|
update | 在输入框上手动触发这个事件,会立刻执行一次校验 |
highlight | 高亮一个错误时会在输入框上触发此事件 |
unhighlight | 取消高亮一个错误时会在输入框上触发此事件 |
自定义错误消息
错误消息可以非常灵活进行定制。错误消息有两种情况:
1. 没有给输入框指定错误消息,则会默认用对应出错规则的错误消息。每一个规则都有自己的错误消息,可以通过重载来改变一个规则的默认消息。如果一个输入框没有定义自己的错误消息,则会显示出错规则的错误消息。比如你定义了data-rules='required|email',但是用户输入的邮箱不合法,则显示的错误消息是email默认的消息"请填写正确的email地址".
2. 给输入框设定了错误消息,则会直接用设定的错误消息,而不会用出错规则对应的消息。
有两种方式可以定义错误消息:
1. 在html中通过 data-error-msg
和 data-empty-msg
来分别定义填写错误和未填写的错误消息。如果没有定义 data-empty-msg
,则用户未填写的时候会显示required规则对应的错误消息。
2. 在JS中通过 messages 来配置错误消息。比如: messages: { email: "邮箱不合法"}
,当用户填写错误邮箱时会显示"邮箱不合法"。也可以设置一个数组,分别表示未填写和填写错误时的出错消息,比如messages: { email: ["请填写邮箱", "邮箱不合法a]"}
。
- <form id="form-msg" class="sui-form form-horizontal" novalidate="novalidate">
- <div class="control-group">
- <label for="inputEmail" class="control-label">邮箱:</label>
- <div class="controls">
- <input type="text" id="inputEmail" name="email" placeholder="邮箱" data-rules="required|email">
- </div>
- </div>
- <div class="control-group">
- <label for="inputPassword" class="control-label">密码:</label>
- <div class="controls">
- <input type="password" id="inputPassword" name="password" placeholder="密码" title="密码" data-rules="required|minlength=6|maxlength=12">
- </div>
- </div>
- <div class="control-group">
- <label for="inputNick" class="control-label">昵称:</label>
- <div class="controls">
- <input type="text" id="inputNick" name="nick" placeholder="昵称" data-rules="required|minlength=2|maxlength=6" data-error-msg="昵称必须是2-6位" data-empty-msg="亲,昵称别忘记填了">
- </div>
- </div>
- <div class="control-group">
- <label for="sanwei" class="control-label"></label>
- <div class="controls">
- <button type="submit" class="sui-btn btn-primary">立即注册</button>
- </div>
- </div>
- </form>
- <script>
- $("#form-msg").validate({
- messages: {
- email: ["亲,你还没填邮箱呢", "邮箱不要瞎填哦"],
- password: "亲,密码必须是6-12位哦"
- }
- })
- </script>
手动显示/隐藏错误消息
有时候你可能需要手动操作错误消息,我们提供了 showError 和 hideError 接口可以使用。具体的参数说明见API说明
- <form id="form-showerror" class="sui-form form-horizontal sui-validate">
- <div class="control-group">
- <label for="inputEmail" class="control-label">邮箱:</label>
- <div class="controls">
- <input type="text" name="email" placeholder="邮箱" data-rules="required|email">
- </div>
- </div>
- <div class="control-group">
- <label for="inputPassword" class="control-label">密码:</label>
- <div class="controls">
- <input type="password" name="password" placeholder="密码" title="密码" data-rules="required|minlength=6|maxlength=12">
- </div>
- </div>
- <div class="control-group">
- <label for="inputNick" class="control-label">昵称:</label>
- <div class="controls">
- <input type="text" name="nick" placeholder="昵称" data-rules="required|minlength=2|maxlength=6">
- </div>
- </div>
- <div class="control-group">
- <label for="sanwei" class="control-label"></label>
- <div class="controls">
- <button type="submit" class="sui-btn btn-primary">立即注册</button>
- </div>
- </div>
- <div><a id="show-email-error" href="javascript:void(0);" class="sui-btn btn-primary">显示邮箱自定义错误</a><a id="hide-email-error" href="javascript:void(0);" class="sui-btn btn-primary">隐藏邮箱自定义错误</a><a id="hide-email-all-error" href="javascript:void(0);" class="sui-btn btn-primary">隐藏邮箱全部错误</a><a id="hide-all-error" href="javascript:void(0);" class="sui-btn btn-primary">隐藏所有错误</a></div>
- </form>
- <script>
- (function() {
- var $form = $("#form-showerror");
- $("#show-email-error").click(function() {
- $form.validate("showError", "email", "你的邮箱填错啦", "myerror");
- });
- $("#hide-email-error").click(function() {
- $form.validate("hideError", "email", "myerror");
- });
- $("#hide-email-all-error").click(function() {
- $form.validate("hideError", "email");
- });
- $("#hide-all-error").click(function() {
- $form.validate("hideError");
- });
- })()
- </script>
内置校验规则
校验器内置了一些常用的规则,包括手机号码、email、数字、长度限制等。
校验规则可以带参数,而且参数可以是一个函数。比如minlength的值可以是一个数字也可以是一个函数,如果是函数,则会使用此函数的返回值作为规则值。
- <form class="sui-form form-horizontal sui-validate">
- <div class="control-group">
- <label for="name" class="control-label">姓名:</label>
- <div class="controls">
- <input type="text" id="name" placeholder="required" data-rules="required" name="name">
- </div>
- </div>
- <div class="control-group">
- <label for="email" class="control-label">邮箱:</label>
- <div class="controls">
- <input type="text" id="email" placeholder="email" data-rules="required|email" name="email">
- </div>
- </div>
- <div class="control-group">
- <label for="password" class="control-label">密码:</label>
- <div class="controls">
- <input type="password" id="password" placeholder="required" data-rules="required|minlength=8|maxlength=16" name="password">
- </div>
- </div>
- <div class="control-group">
- <label for="repassword" class="control-label">重复密码:</label>
- <div class="controls">
- <input type="password" id="repassword" placeholder="match" data-rules="required|match=password" name="repassword">
- </div>
- </div>
- <div class="control-group">
- <label for="tel" class="control-label">座机号码:</label>
- <div class="controls">
- <input type="text" id="tel" placeholder="tel" data-rules="required|tel" name="tel">
- </div>
- </div>
- <div class="control-group">
- <label for="mobile" class="control-label">手机号码:</label>
- <div class="controls">
- <input type="text" id="mobile" placeholder="mobild" data-rules="required|mobile" name="mobile">
- </div>
- </div>
- <div class="control-group">
- <label for="zip" class="control-label">邮编:</label>
- <div class="controls">
- <input type="text" id="zip" placeholder="zip" data-rules="required|zip" name="zip">
- </div>
- </div>
- <div class="control-group">
- <label for="date" class="control-label">出生年月日:</label>
- <div class="controls">
- <input type="text" id="date" placeholder="date" data-rules="required|date" name="date" data-toggle="datepicker">
- </div>
- </div>
- <div class="control-group">
- <label for="time" class="control-label">睡觉时间:</label>
- <div class="controls">
- <input type="text" id="time" placeholder="time" data-rules="required|time" name="time" data-toggle="timepicker">
- </div>
- </div>
- <div class="control-group">
- <label for="datetime" class="control-label">日期加时间:</label>
- <div class="controls">
- <input type="text" id="datetime" placeholder="datetime" data-rules="required|datetime" name="datetime" data-toggle="datepicker" data-date-timepicker="true">
- </div>
- </div>
- <div class="control-group">
- <label for="age" class="control-label">年龄:</label>
- <div class="controls">
- <input type="text" id="age" placeholder="digits" data-rules="required|digits" name="age">
- </div>
- </div>
- <div class="control-group">
- <label for="url" class="control-label">个人网址(选填):</label>
- <div class="controls">
- <input type="text" id="url" placeholder="url" data-rules="url" name="url">
- </div>
- </div>
- <div class="control-group">
- <label class="control-label"></label>
- <div class="controls">
- <button type="submit" class="sui-btn btn-primary btn-large">注册</button>
- </div>
- </div>
- </form>
内置校验规则包括这些
名称 | 内容 |
---|---|
required | 必填,不能为空 |
prefill | 必须先填写另一个输入框,规则值为另一个输入框的name属性 |
match | 和另一个输入框的值保持一致 |
number | 数字 |
digits | 整数 |
mobile | 手机号码 |
tel | 座机号码,包括区号 |
email地址 | |
zip | 邮编 |
date | 日期,例如 2012-02-02 |
time | 时间,精确到分钟,例如 05:30 |
datetime | 日期加时间,例如 2012-02-02 05:30 |
url | 网址,协议是可选的 |
minlength | 最小长度 |
maxlength | 最大长度 |
lt | 数字必须小于某数(通常配合digits规则一起使用) |
gt | 数字必须大于某数(通常配合digits规则一起使用) |
编写插件
表单校验组件提供了常用的校验规则,并且你还可以非常方便地通过插件添加自定义的规则。
- //添加required规则
- var required = function(value, element, param) {
- return trim(value);
- };
- $.validate.setRule("required", required, function ($input) {
- var tagName = $input[0].tagName.toUpperCase();
- var type = $input[0].type.toUpperCase();
- if ( type == 'CHECKBOX' || type == 'RADIO' || tagName == 'SELECT') {
- return '请选择'
- }
- return '请填写'
- });
- //添加match规则
- var match = function(value, element, param) {
- value = trim(value);
- return value == $(element).parents('form').find("[name='"+param+"']").val()
- };
- $.validate.setRule("match", match, '必须与$0相同');
$.validate.setRule
可以添加自定义规则。setRule 方法有三个参数:
- name, 规则名
- method, 规则方法,该方法的返回值为布尔类型,表示是否发生错误,比如返回true则表示没有发生错误。
- msg,错误消息,可以是字符串,也可以是函数,如果是函数则调用函数并显示函数的返回值,并且在调用函数的时候会传入一个参数就是当前的输入框。具体参加api说明
规则函数也有三个参数:
- value,当前输入值
- element,当前输入框
- param,当前规则值,比如
data-rules="match=password"
,则param就是password