SUI
新版本1.4.2发布了。第一次升级到 1.4.x 版本请注意在1.4.0版本的重大变动，具体请阅读更新日志。

开发者文档

强大的表单校验器，通过简单的配置规则即可实现表单校验。
并且支持自定义校验插件。

  • 更新 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'

请选择 
  1. <form class="sui-form form-horizontal sui-validate">
  2.   <div class="control-group">
  3.     <label for="inputEmail" class="control-label">邮箱：</label>
  4.     <div class="controls">
  5.       <input type="text" id="inputEmail" name="name" placeholder="邮箱" data-rules="required|email">
  6.     </div>
  7.   </div>
  8.   <div class="control-group">
  9.     <label for="inputPassword" class="control-label">密码：</label>
  10.     <div class="controls">
  11.       <input type="password" id="inputPassword" name="password" placeholder="密码" data-rules="required" title="密码">
  12.     </div>
  13.   </div>
  14.   <div class="control-group">
  15.     <label for="inputRepassword" class="control-label">重复密码：</label>
  16.     <div class="controls">
  17.       <input type="password" id="inputRepassword" name="repassword" placeholder="重复密码" data-rules="required|match=password">
  18.     </div>
  19.   </div>
  20.   <div class="control-group">
  21.     <label for="inputGender" class="control-label">性别：</label>
  22.     <div class="controls">
  23.       <label data-toggle="radio" class="radio-pretty inline">
  24.         <input type="radio" name="gender" value="1" data-rules="required"><span>男</span>
  25.       </label>
  26.       <label data-toggle="radio" class="radio-pretty inline">
  27.         <input type="radio" name="gender" value="2" data-rules="required"><span>女</span>
  28.       </label>
  29.     </div>
  30.   </div>
  31.   <div class="control-group">
  32.     <label for="inputPassword" class="control-label">年龄：</label>
  33.     <div class="controls">
  34.       <input type="text" id="inputPassword" name="age" placeholder="整数，需要小于100" data-rules="required|number|lt=100" title="年龄">
  35.     </div>
  36.   </div>
  37.   <div class="control-group">
  38.     <label for="inputGender" class="control-label">地址：</label>
  39.     <div class="controls"><span class="sui-dropdown dropdown-bordered select"><span class="dropdown-inner"><a role="button" data-toggle="dropdown" href="#" class="dropdown-toggle">
  40.             <input name="city" type="hidden" data-rules="required"><i class="caret"></i><span>请选择</span></a>
  41.           <ul id="menu4" role="menu" aria-labelledby="drop4" class="sui-dropdown-menu">
  42.             <li role="presentation"><a role="menuitem" tabindex="-1" href="javascript:void(0);" value="bj">北京</a></li>
  43.             <li role="presentation"><a role="menuitem" tabindex="-1" href="javascript:void(0);" value="sb">圣彼得堡</a></li>
  44.           </ul></span></span></div>
  45.   </div>
  46.   <div class="control-group">
  47.     <label for="inputDes" class="control-label v-top">自我介绍：</label>
  48.     <div class="controls">
  49.       <textarea id="inputDes" name="des" placeholder="自我介绍" data-rules="required"></textarea>
  50.     </div>
  51.   </div>
  52.   <div class="control-group">
  53.     <label class="control-label"></label>
  54.     <div class="controls">
  55.       <button type="submit" class="sui-btn btn-primary">立即注册</button>
  56.     </div>
  57.   </div>
  58. </form>

通过JS配置规则

除了在html中直接配置规则，也可以在js中配置规则，两者可以结合使用，在JS中配置的规则会覆盖掉html中的同名规则。
HTML中的规则值只能为字符串，而JS中可以把规则值配置为函数从而实现更强大的功能。

女生必填
  1. <form id="form5" class="sui-form form-horizontal" novalidate="novalidate">
  2.   <div class="control-group">
  3.     <label for="inputEmail" class="control-label">邮箱：</label>
  4.     <div class="controls">
  5.       <input type="text" id="inputEmail" name="email" placeholder="邮箱">
  6.     </div>
  7.   </div>
  8.   <div class="control-group">
  9.     <label for="inputPassword" class="control-label">密码：</label>
  10.     <div class="controls">
  11.       <input type="password" id="inputPassword" name="password" placeholder="密码" title="密码">
  12.     </div>
  13.   </div>
  14.   <div class="control-group">
  15.     <label for="inputRepassword" class="control-label">重复密码：</label>
  16.     <div class="controls">
  17.       <input type="password" id="inputRepassword" name="repassword" placeholder="重复密码">
  18.     </div>
  19.   </div>
  20.   <div class="control-group">
  21.     <label for="inputGender" class="control-label">性别：</label>
  22.     <div class="controls">
  23.       <label data-toggle="radio" class="radio-pretty inline">
  24.         <input type="radio" name="gender" value="1"><span>男</span>
  25.       </label>
  26.       <label data-toggle="radio" class="radio-pretty inline">
  27.         <input type="radio" name="gender" value="2"><span>女</span>
  28.       </label>
  29.     </div>
  30.   </div>
  31.   <div class="control-group">
  32.     <label for="sanwei" class="control-label">三维：</label>
  33.     <div class="controls">
  34.       <input type="text" id="sanwei" name="sanwei" placeholder="三维">
  35.       <div class="sui-msg msg-tips msg-naked">
  36.         <div class="msg-con">女生必填</div>
  37.         <s class="msg-icon"></s>
  38.       </div>
  39.     </div>
  40.   </div>
  41.   <div class="control-group">
  42.     <label for="sanwei" class="control-label"></label>
  43.     <div class="controls">
  44.       <button type="submit" class="sui-btn btn-primary">立即注册</button>
  45.     </div>
  46.   </div>
  47. </form>
  48. <script>
  49.   $("#form5").validate({
  50.     rules: {
  51.       email: {
  52.         required: true,
  53.         minlength: 2,
  54.         maxlength: 10
  55.       },
  56.       password: {
  57.         required: true,
  58.         minlength: 6,
  59.         maxlength: 12
  60.       },
  61.       repassword: {
  62.         required: true,
  63.         prefill: 'password',
  64.         match: 'password'
  65.       },
  66.       sanwei: {
  67.         required: function($input) {
  68.           var value = $input.val()
  69.           var $form = $input.parents("form")
  70.           var gender = $form.find("[name='gender']:checked").val()
  71.           if (gender == 2 && !value) {
  72.             return false
  73.           }
  74.           return true
  75.         }
  76.       },
  77.       gender: {
  78.         required: true
  79.       }
  80.     },
  81.     messages: {
  82.       email: "亲，你连邮箱都没有么"
  83.     },
  84.     success: function() {
  85.       $.alert("恭喜，没有问题了。");
  86.       return false;
  87.     }
  88.   })
  89. </script>

一，通过两种方式可以启用表单校验

  1. 通过在form上添加.sui-validate
  2. 通过直接调用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) { /**参见源码**/ } 放置错误提示信息，在显示错误信息之前，会调用此方法把错误信息放在合适的位置 其中两个参数分别是：
  • $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, '请填写正确的手机号码'); 设置一条自定义规则，如果该规则已经存在则直接覆盖。 其中三个参数分别是：
  • name,规则名称
  • method, 规则方法，该方法返回值为true则表示没有错误，返回值为false则表示有错误。
  • msg, 出错提示文案，可以是一个字符串，也可是一个函数。
    如果是函数，则会调用函数并显示函数的返回值。并且调用函数的时候会传第一个参数就是出错的input。
    如果是字符串，则可以用 $0 变量来表示该规则的值，比如 data-rules='match=pwssword'，则 $0 就是 password
$.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]"}。
中设置messages请参考js文档。 

  1. <form id="form-msg" class="sui-form form-horizontal" novalidate="novalidate">
  2.   <div class="control-group">
  3.     <label for="inputEmail" class="control-label">邮箱：</label>
  4.     <div class="controls">
  5.       <input type="text" id="inputEmail" name="email" placeholder="邮箱" data-rules="required|email">
  6.     </div>
  7.   </div>
  8.   <div class="control-group">
  9.     <label for="inputPassword" class="control-label">密码：</label>
  10.     <div class="controls">
  11.       <input type="password" id="inputPassword" name="password" placeholder="密码" title="密码" data-rules="required|minlength=6|maxlength=12">
  12.     </div>
  13.   </div>
  14.   <div class="control-group">
  15.     <label for="inputNick" class="control-label">昵称：</label>
  16.     <div class="controls">
  17.       <input type="text" id="inputNick" name="nick" placeholder="昵称" data-rules="required|minlength=2|maxlength=6" data-error-msg="昵称必须是2-6位" data-empty-msg="亲，昵称别忘记填了">
  18.     </div>
  19.   </div>
  20.   <div class="control-group">
  21.     <label for="sanwei" class="control-label"></label>
  22.     <div class="controls">
  23.       <button type="submit" class="sui-btn btn-primary">立即注册</button>
  24.     </div>
  25.   </div>
  26. </form>
  27. <script>
  28.   $("#form-msg").validate({
  29.     messages: {
  30.       email: ["亲，你还没填邮箱呢", "邮箱不要瞎填哦"],
  31.       password: "亲，密码必须是6-12位哦"
  32.     }
  33.   })
  34. </script>

手动显示/隐藏错误消息

有时候你可能需要手动操作错误消息，我们提供了 showError 和 hideError 接口可以使用。具体的参数说明见API说明

  1. <form id="form-showerror" class="sui-form form-horizontal sui-validate">
  2.   <div class="control-group">
  3.     <label for="inputEmail" class="control-label">邮箱：</label>
  4.     <div class="controls">
  5.       <input type="text" name="email" placeholder="邮箱" data-rules="required|email">
  6.     </div>
  7.   </div>
  8.   <div class="control-group">
  9.     <label for="inputPassword" class="control-label">密码：</label>
  10.     <div class="controls">
  11.       <input type="password" name="password" placeholder="密码" title="密码" data-rules="required|minlength=6|maxlength=12">
  12.     </div>
  13.   </div>
  14.   <div class="control-group">
  15.     <label for="inputNick" class="control-label">昵称：</label>
  16.     <div class="controls">
  17.       <input type="text" name="nick" placeholder="昵称" data-rules="required|minlength=2|maxlength=6">
  18.     </div>
  19.   </div>
  20.   <div class="control-group">
  21.     <label for="sanwei" class="control-label"></label>
  22.     <div class="controls">
  23.       <button type="submit" class="sui-btn btn-primary">立即注册</button>
  24.     </div>
  25.   </div>
  26.   <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>
  27. </form>
  28. <script>
  29.   (function() {
  30.     var $form = $("#form-showerror");
  31.     
  32.     $("#show-email-error").click(function() {
  33.       $form.validate("showError", "email", "你的邮箱填错啦", "myerror");
  34.     });
  35.     $("#hide-email-error").click(function() {
  36.       $form.validate("hideError", "email", "myerror");
  37.     });
  38.     $("#hide-email-all-error").click(function() {
  39.       $form.validate("hideError", "email");
  40.     });
  41.     $("#hide-all-error").click(function() {
  42.       $form.validate("hideError");
  43.     });
  44.   })()
  45.   
  46. </script>

内置校验规则

校验器内置了一些常用的规则，包括手机号码、email、数字、长度限制等。
校验规则可以带参数，而且参数可以是一个函数。比如minlength的值可以是一个数字也可以是一个函数，如果是函数，则会使用此函数的返回值作为规则值。

  1. <form class="sui-form form-horizontal sui-validate">
  2.   <div class="control-group">
  3.     <label for="name" class="control-label">姓名：</label>
  4.     <div class="controls">
  5.       <input type="text" id="name" placeholder="required" data-rules="required" name="name">
  6.     </div>
  7.   </div>
  8.   <div class="control-group">
  9.     <label for="email" class="control-label">邮箱：</label>
  10.     <div class="controls">
  11.       <input type="text" id="email" placeholder="email" data-rules="required|email" name="email">
  12.     </div>
  13.   </div>
  14.   <div class="control-group">
  15.     <label for="password" class="control-label">密码：</label>
  16.     <div class="controls">
  17.       <input type="password" id="password" placeholder="required" data-rules="required|minlength=8|maxlength=16" name="password">
  18.     </div>
  19.   </div>
  20.   <div class="control-group">
  21.     <label for="repassword" class="control-label">重复密码：</label>
  22.     <div class="controls">
  23.       <input type="password" id="repassword" placeholder="match" data-rules="required|match=password" name="repassword">
  24.     </div>
  25.   </div>
  26.   <div class="control-group">
  27.     <label for="tel" class="control-label">座机号码：</label>
  28.     <div class="controls">
  29.       <input type="text" id="tel" placeholder="tel" data-rules="required|tel" name="tel">
  30.     </div>
  31.   </div>
  32.   <div class="control-group">
  33.     <label for="mobile" class="control-label">手机号码：</label>
  34.     <div class="controls">
  35.       <input type="text" id="mobile" placeholder="mobild" data-rules="required|mobile" name="mobile">
  36.     </div>
  37.   </div>
  38.   <div class="control-group">
  39.     <label for="zip" class="control-label">邮编：</label>
  40.     <div class="controls">
  41.       <input type="text" id="zip" placeholder="zip" data-rules="required|zip" name="zip">
  42.     </div>
  43.   </div>
  44.   <div class="control-group">
  45.     <label for="date" class="control-label">出生年月日：</label>
  46.     <div class="controls">
  47.       <input type="text" id="date" placeholder="date" data-rules="required|date" name="date" data-toggle="datepicker">
  48.     </div>
  49.   </div>
  50.   <div class="control-group">
  51.     <label for="time" class="control-label">睡觉时间：</label>
  52.     <div class="controls">
  53.       <input type="text" id="time" placeholder="time" data-rules="required|time" name="time" data-toggle="timepicker">
  54.     </div>
  55.   </div>
  56.   <div class="control-group">
  57.     <label for="datetime" class="control-label">日期加时间：</label>
  58.     <div class="controls">
  59.       <input type="text" id="datetime" placeholder="datetime" data-rules="required|datetime" name="datetime" data-toggle="datepicker" data-date-timepicker="true">
  60.     </div>
  61.   </div>
  62.   <div class="control-group">
  63.     <label for="age" class="control-label">年龄：</label>
  64.     <div class="controls">
  65.       <input type="text" id="age" placeholder="digits" data-rules="required|digits" name="age">
  66.     </div>
  67.   </div>
  68.   <div class="control-group">
  69.     <label for="url" class="control-label">个人网址(选填)：</label>
  70.     <div class="controls">
  71.       <input type="text" id="url" placeholder="url" data-rules="url" name="url">
  72.     </div>
  73.   </div>
  74.   <div class="control-group">
  75.     <label class="control-label"></label>
  76.     <div class="controls">
  77.       <button type="submit" class="sui-btn btn-primary btn-large">注册</button>
  78.     </div>
  79.   </div>
  80. </form>

内置校验规则包括这些

名称 内容
required 必填，不能为空
prefill 必须先填写另一个输入框，规则值为另一个输入框的name属性
match 和另一个输入框的值保持一致
number 数字
digits 整数
mobile 手机号码
tel 座机号码，包括区号
email 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相同'); 
  1. //添加required规则
  2. var required = function(value, element, param) {
  3.   return trim(value);
  4. };
  5. $.validate.setRule("required", required, function ($input) {
  6.   var tagName = $input[0].tagName.toUpperCase();
  7.   var type = $input[0].type.toUpperCase();
  8.   if ( type == 'CHECKBOX' || type == 'RADIO' || tagName == 'SELECT') {
  9.     return '请选择'
  10.   }
  11.   return '请填写'
  12. });
  13. //添加match规则
  14. var match = function(value, element, param) {
  15.   value = trim(value);
  16.   return value == $(element).parents('form').find("[name='"+param+"']").val()
  17. };
  18. $.validate.setRule("match", match, '必须与$0相同');
通过$.validate.setRule可以添加自定义规则。

setRule 方法有三个参数：
  • name, 规则名
  • method, 规则方法，该方法的返回值为布尔类型，表示是否发生错误，比如返回true则表示没有发生错误。
  • msg，错误消息，可以是字符串，也可以是函数，如果是函数则调用函数并显示函数的返回值，并且在调用函数的时候会传入一个参数就是当前的输入框。具体参加api说明

规则函数也有三个参数：
  • value,当前输入值
  • element,当前输入框
  • param,当前规则值，比如 data-rules="match=password"，则param就是password
  • @time 2014.03.07
  • @author [本站仅为SUI文档保留的镜像站，与官方无关]