Bootstrap-validator的使用

翻译官方的文档。

这个插件遵循Bootstrap核心jQuery插件提出的约定，所以一定要检查这些插件，以便更好地理解这个插件的目标和设计。

例子

使用这个简单的插件为表单添加验证。 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
<form data-toggle="validator" role="form">
  <div class="form-group">
    <label for="inputName" class="control-label">Name</label>
    <input type="text" class="form-control" id="inputName" placeholder="Cina Saffary" required>
  </div>
  <div class="form-group has-feedback">
    <label for="inputTwitter" class="control-label">Twitter</label>
    <div class="input-group">
      <span class="input-group-addon">@</span>
      <input type="text" pattern="^[_A-z0-9]{1,}$" maxlength="15" class="form-control" id="inputTwitter" placeholder="1000hz" required>
    </div>
    <span class="glyphicon form-control-feedback" aria-hidden="true"></span>
    <div class="help-block with-errors">Hey look, this one has feedback icons!</div>
  </div>
  <div class="form-group">
    <label for="inputEmail" class="control-label">Email</label>
    <input type="email" class="form-control" id="inputEmail" placeholder="Email" data-error="Bruh, that email address is invalid" required>
    <div class="help-block with-errors"></div>
  </div>
  <div class="form-group">
    <label for="inputPassword" class="control-label">Password</label>
    <div class="form-inline row">
      <div class="form-group col-sm-6">
        <input type="password" data-minlength="6" class="form-control" id="inputPassword" placeholder="Password" required>
        <div class="help-block">Minimum of 6 characters</div>
      </div>
      <div class="form-group col-sm-6">
        <input type="password" class="form-control" id="inputPasswordConfirm" data-match="#inputPassword" data-match-error="Whoops, these don't match" placeholder="Confirm" required>
        <div class="help-block with-errors"></div>
      </div>
    </div>
  </div>
  <div class="form-group">
    <div class="radio">
      <label>
        <input type="radio" name="underwear" required>
        Boxers
      </label>
    </div>
    <div class="radio">
      <label>
        <input type="radio" name="underwear" required>
        Briefs
      </label>
    </div>
  </div>
  <div class="form-group">
    <div class="checkbox">
      <label>
        <input type="checkbox" id="terms" data-error="Before you wreck yourself" required>
        Check yourself
      </label>
      <div class="help-block with-errors"></div>
    </div>
  </div>
  <div class="form-group">
    <button type="submit" class="btn btn-primary">Submit</button>
  </div>
</form>

用法

可以通过data-api或JavaScript在标记中启用表单验证。通过添加data-toggle="validator"到表单元素自动启用表单验证。 

1
2
3
<form role="form" data-toggle="validator">
  ...
</form>

或者通过JavaScript激活验证： 

1
$('#myForm').validator()

标记

按照Bootstrap的示例进行适当的表单标记。重要的是每个输入字段都在其自己的单独.form-group容器中，以便正确显示错误消息。

验证规则通过以下标准HTML5属性在表单输入上指定：

  • type="email"
  • type="url"
  • type="number"，通过附加约束max，min和step属性
  • pattern="Reg(ular )?Exp(ression)?"（用于输入类型的text，search，tel，url或email）
  • required

以及以下非标准属性：

  • data-match="#inputToMatch" 确保两个字段匹配，例如密码确认
  • data-minlength="5" 强制执行最少量的字符
  • data-remote="/path/to/remote/validator"发出AJAX请求以确定该字段是否有效。请务必为输入提供name属性，因为请求将被发送到/path/to/remote/validator?<name>=<value>。200 OK如果字段有效，则远程端点应返回a ，4xx否则返回。这是使用Express 的参考服务器实现。

标准属性验证器

标准HTML5属性的验证规则由浏览器使用HTML5约束验证API完全处理。因此，此插件无法控制有资格作为有效电子邮件地址或URL的内容。如果您发现需要对这些字段进行更严格的验证，则可以使用该pattern属性进一步限制可接受的范围。

但请注意，您不要过于严格，这可能会导致漏报和糟糕的用户体验。例如，根据标准，您会对哪种电子邮件地址被视为有效感到惊讶。

跨浏览器兼容性

由于此插件依赖于HTML5约束验证API，因此不支持Internet Explorer 9及更早版本。如果您需要支持这些浏览器，则必须添加像Ryan Seddon的H5F这样的polyfill。

要显示错误消息，请在输入字段后面包含容器help-block和with-errors类。 

1
2
3
4
5
6
7
<form role="form" data-toggle="validator">
  <div class="form-group">
    <label for="inputEmail">Email</label>
    <input type="email" id="inputEmail">
    <div class="help-block with-errors"></div>
  </div>
</form>

验证字段

默认情况下，验证程序仅验证插件初始化时存在的字段。如果表单具有动态字段集，则需要调用$(...).validator('update')以通知插件要验证的字段集已更改。

用于确定验证哪些字段的默认选择器是：

1
$.fn.validator.Constructor.INPUT_SELECTOR = ':input:not([type="hidden"], [type="submit"], [type="reset"], button)'

如果需要更改此默认行为，可以在代码中覆盖此值。或者，您可以添加data-validate="true"/ data-validate="false"到特定输入以强制将其包含/排除在已验证字段集中。

选项

选项可以通过数据属性或JavaScript传递。对于数据属性，请将选项名称附加到data-，如data-delay=""。

名称 类型 默认 描述
delay number 500 在表单字段上显示错误之前要等待的毫秒数。
html boolean false 将HTML插入错误消息中。如果为false，则使用jQuery的文本方法将内容插入DOM。如果您担心XSS攻击，请使用文本。
disable boolean true 禁用提交按钮，直到表单有效并且所有必填字段都已完成。
focus boolean true 在验证表单时，滚动并聚焦第一个字段并显示错误。例如，如果页面顶部有一个固定的导航栏，并且需要调整窗口顶部和焦点字段之间的填充量，则可以覆盖以下变量：$.fn.validator.Constructor.FOCUS_OFFSET默认为20（px）。
feedback object glyphicon classes 覆盖用于表单反馈图标的类。默认为Bootstrap的glyphicons：feedback: { success: 'glyphicon-ok', error: 'glyphicon-remove' }
custom object {} 添加要运行的自定义验证程序。验证器应该是接收jQuery元素作为参数的函数，如果字段无效则返回错误消息。这是一个自定义验证器的示例，它检查输入是否等于某个指定值：custom: { equals: function($el) { var matchValue = $el.data("equals") // foo if ($el.val() !== matchValue) { return "Hey, that's not valid! It's gotta be " + matchValue } } }通过将其名称作为数据属性引用，将验证器添加到输入中就像完成其他操作一样：<input data-equals="foo">。在这种情况下，如果用户输入除以外的任何内容，该字段将显示错误foo。 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
// feedback

{
    feedback: {   
        success: 'glyphicon-ok',   
        error: 'glyphicon-remove'
    }
}

// custom
{
    custom: {   
        equals: function($el) {     
            var matchValue = $el.data("equals") // foo     
            if ($el.val() !== matchValue) {       
                return "Hey, that's not valid! It's gotta be " + matchValue     
            }   
        } 
    }
}

各个表单字段的错误消息

可以通过使用数据属性来指定单个表单字段的错误消息。您可以在字段中的每个类型的验证，即指定一个错误信息data-pattern-error=""，data-required-error=""，data-match-error=""，等…或者使用data-error=""用于衬垫的错误消息，以显示该字段的任何错误。

方法

.validator(options)

将验证器附加到表单集合。

.validator('update')

更新将验证的输入集合。如果需要验证的字段集已更改，请调用此方法。

.validator('validate')

立即验证整个表格。

.validator('destroy')

销毁形式验证器并清理留下的数据。

事件

所有事件都在表单元素上触发，并提供对事件所属的表单字段的引用event.relatedTarget。

事件类型 描述
validate.bs.validator 验证表单字段时，此事件立即触发。
invalid.bs.validator 当表单字段变为无效时会触发此事件。通过提供字段错误event.detail。
valid.bs.validator 当表单字段变为有效时，将触发此事件。之前的字段错误通过提供event.detail。
validated.bs.validator 在验证表单字段后触发此事件。

有条件地处理提交事件

当表单无效时，.preventDefault()将在提交事件上调用。因此，如果您想要挂钩提交事件并根据表单是否有效而有条件地执行某些操作，则可以检查事件是否有效.isDefaultPrevented()。在表单上初始化插件后，请确保您的提交处理程序已绑定。

1
2
3
4
5
6
7
$('#form').validator().on('submit', function (e) {
  if (e.isDefaultPrevented()) {
    // handle the invalid form...
  } else {
    // everything looks good!
  }
})