新版本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-msgdata-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. $("#show-email-error").click(function() {
  32. $form.validate("showError", "email", "你的邮箱填错啦", "myerror");
  33. });
  34. $("#hide-email-error").click(function() {
  35. $form.validate("hideError", "email", "myerror");
  36. });
  37. $("#hide-email-all-error").click(function() {
  38. $form.validate("hideError", "email");
  39. });
  40. $("#hide-all-error").click(function() {
  41. $form.validate("hideError");
  42. });
  43. })()
  44. </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