Geting Started
官方API
<link rel="stylesheet" href="/path/to/bootstrap/css/bootstrap.css"/>
<link rel="stylesheet" href="/path/to/dist/css/bootstrapValidator.min.css"/>
<script type="text/javascript" src="/path/to/jquery/jquery-1.10.2.min.js">script>
<script type="text/javascript" src="/path/to/bootstrap/js/bootstrap.min.js">script>
<script type="text/javascript" src="/path/to/dist/js/bootstrapValidator.min.js">script>
因为bootstrapValidator是基于bootstarp设计,所以form表单的类名必须是bootstarp的结构化的类名。
<div class="form-group">
<label>Usernamelabel>
<input type="text" class="form-control" name="username" />
div>
Uncaught RangeError: Maximum call stack size exceeded
Too much recursion error
<button type="submit" name="submit" class="btn btn-primary">Submitbutton>
<input type="text" class="form-control" name="email" placeholder="Email address" />
<form class="registerForm">
<div class="form-group">
<label>Usernamelabel>
<input type="text" class="form-control" name="username" />
div>
<div class="form-group">
<label>Passwordlabel>
<input type="text" class="form-control" name="Password" />
div>
form>
$(document).ready(function() {
$('.registerForm').bootstrapValidator({
feedbackIcons: {
valid: 'glyphicon glyphicon-ok',
invalid: 'glyphicon glyphicon-remove',
validating: 'glyphicon glyphicon-refresh'
},
fields: {
username: {
message: '用户名验证失败',
validators: {
notEmpty: {
message: '用户名不能为空'
},
stringLength: {
min: 6,
max: 30,
message: '用户名的长度必须介于6到30之间'
}
}
},
Password: {
validators: {
notEmpty: {
message: '密码不能为空'
}
}
}
}
});
});
bootstarpValidator的属性设置分为表单、验证元素、验证器三个等级,可根据不同的业务需求分别设置属性。
可以通过两种方式对表单进行设置,在初始化的时候进行设置或者在准备form元素的时候在html中进行设置。推荐第一种设置方式。
$(formSelector).bootstrapValidator({
... 在这里书写表单级别的属性 ...
fields: {},
});
<form data-bv-message="This value is not valid"
data-bv-feedbackicons-valid="glyphicon glyphicon-ok"
data-bv-feedbackicons-invalid="glyphicon glyphicon-remove"
data-bv-feedbackicons-validating="glyphicon glyphicon-refresh"
data-bv-submitbuttons='button[type="submit"]'
data-bv-live="enabled">
...
form>
配置项 | html5属性 | 默认值 |
---|---|---|
container | data-bv-container | n/a |
excluded | data-bv-excluded | [’:disabled’, ‘:hidden’, ‘:not(:visible)’] |
feedbackIcons | data-bv-feedbackicons-valid , data-bv-feedbackicons-invalid , data-bv-feedbackicons-validating |
{valid: null,invalid: null,validating: null} |
group | data-bv-group | ‘.form-group’ |
live | data-bv-live | ‘enabled’ |
message | data-bv-message | ‘This value is not valid’ |
submitButtons | data-bv-submitbuttons | ‘[type=“submit”]’ |
threshold | data-bv-threshold | null |
trigger | data-bv-trigger | null |
verbose | data-bv-verbose | true |
fields | n/a | null |
用来设置错误消息的提示
Value | Description |
---|---|
自定义dom及css样式 | 所有的错误消息提示被自定义的dom及类名所替换,需要自己准备dom元素及所对应的css样式 |
tooltip组件 | 使用bootstarp的tooltip组件展示错误消息 不需要自己准备dom元素及css样式 |
popover组件 | 使用bootstarp的tooltip组件展示错误消息 不需要自己准备dom元素及css样式 |
<form id="contactForm" method="post" class="form-horizontal">
<div class="form-group">
<label class="col-sm-3 control-label">Full namelabel>
<div class="col-sm-6">
<input type="text" class="form-control" name="fullName" />
div>
div>
<div class="form-group">
<div class="col-sm-9 col-sm-offset-3">
<div id="messages">div>
div>
div>
form>
$(document).ready(function() {
$('#contactForm').bootstrapValidator({
//container属性 声明错误提示的地方
container: '#messages',
feedbackIcons: {
valid: 'glyphicon glyphicon-ok',
invalid: 'glyphicon glyphicon-remove',
validating: 'glyphicon glyphicon-refresh'
},
fields: {
//表单验证项
}
});
});
使用自己的类名会在自己准备好的元素下生成help-block类名的错误提示
表明那些表单元素不想被验证,默认条件下,以下元素不会被插件验证
该配置项支持三种格式:
Format | Description |
---|---|
String | ‘:hidden,:disabled,:not(:visible)’ |
Array | [’:hidden’ , ‘disabled’ , ‘:not("visible)’] |
Array of String and callback funtions | [’:hidden’,‘disabled’,function(KaTeX parse error: Expected '}', got 'EOF' at end of input: …datoe){return !filed.is(’:visiable’)}] |
设置在提示过程中 验证失败/验证成功/验证中的icon样式,主要支持两种样式
//使用glyphicon版本
feedbackIcons: {
valid: 'glyphicon glyphicon-ok',
invalid: 'glyphicon glyphicon-remove',
validating: 'glyphicon glyphicon-refresh'
}
//使用fontAwesome版本
feedbackIcons: {
valid: 'fa fa-check',
invalid: 'fa fa-times',
validating: 'fa fa-refresh'
}
验证元素父级的css选择器,默认值为 .form-group。根据bootstarp的设计结构,每一个验证元素及其标签都需要被包裹在一个.form-group元素中。当需要改变父级的选择器时需要用到该配置项。
<form id="groupForm">
<table class="table table-condensed">
<tr>
<td><input type="text" class="form-control" name="project[]" />td>
<td><input type="text" class="form-control" name="role[]" />td>
<td><input type="text" class="form-control" name="url[]" />td>
tr>
table>
form>
$('#groupForm').bootstrapValidator({
container: 'tooltip',
group: 'td',
feedbackIcons: {
valid: 'glyphicon glyphicon-ok',
invalid: 'glyphicon glyphicon-remove',
validating: 'glyphicon glyphicon-refresh'
},
})
插件的验证模式,默认为enabled
Value | Description |
---|---|
enabled | 在验证域发生改变后立刻进行验证 |
disabled | 禁用实时模式,只有表单在点击提交后才会显示错误消息 |
submitted | 在表单被提交后启用实时验证 |
对于所有的验证域默认的提示消息,你也可以对于任意的一个验证域单独的指定特定的错误消息,需要在验证域配置项中进行修改。
提交按钮的选择器,当表单验证失败后,提交按钮被禁用
如果验证域的字符少于该数字则该验证域不会实时验证。
!!!!不清楚是验证域的内容还是验证域本身的长度
在实时验证模式可用的情况下触发验证的事件。
trigger=“focus blur” 表示被验证的元素在聚焦或者失去聚焦时触发验证事件
在验证域验证失败后时候要显示所有的错误细节,默认值为显示
Value | Description |
---|---|
true | 如果一个验证域有多个验证项,当验证失败后会提示所有的验证细节,显示所有导致验证失败的验证项 |
false | 只有与该字段相关的第一个验证消息会反馈给用户 |
配置项 | 等效的H5属性 |
---|---|
container | data-bv-container |
enabled | data-bv-enabled |
excluded | data-bv-excluded |
feedbackIcons | data-bv-feedbackicons |
group | data-bv-group |
message | data-bv-message |
selector | data-bv-selector |
threshold | data-bv-threshold |
trigger | data-bv-trigger |
verbose | data-bv-verbose |
验证项的错误消息提示的地方。(一般用来单独设置某一个配置项时使用)
value | Des |
---|---|
CSS选择器 | 用户自定义元素及样式选择器 |
toolTip | 使用Bootstrap tooltip组件显示 |
popover | 使用bootstrap popover组件显示 |
使用方式类似于对整体表单的设置,只是设置的作用域不同。在表单处设置container属性后,作用域是整体表单,在field下设置的作用域为当前设置的验证项。
<form id="fieldContainerForm" class="form-horizontal">
<div class="form-group">
<label class="col-sm-3 control-label">Full namelabel>
<div class="col-sm-4">
<input type="text" class="form-control" name="firstName" placeholder="First name" />
<span class="help-block" id="firstNameMessage">span>
div>
div>
form>
$(document).ready(function() {
$('#fieldContainerForm').bootstrapValidator({
feedbackIcons: {
valid: 'glyphicon glyphicon-ok',
invalid: 'glyphicon glyphicon-remove',
validating: 'glyphicon glyphicon-refresh'
},
fields: {//验证域配置
firstName: {//单独的验证项名称
container: '#firstNameMessage',//设置验证项的提示
validators: {//配置验证规则;多个规则以逗号隔开
notEmpty: {
message:"不能为空"
}
}
}
}
});
});
启用或禁用该字段的验证项
在验证时是否排除该字段
启用或禁用该字段的提示图标
被验证项的父级元素所包含的类选择器 默认为 .form-group
该验证项的错误提示消息
验证项的css选择器,用于设置没name或无法用name进行验证的验证项
当验证项的值少于设置的位数的时候不进行实时验证
<form id="fieldContainerForm" class="form-horizontal">
<div class="form-group">
<label class="col-sm-3 control-label">phonelabel>
<div class="col-sm-4">
<input type="text" class="form-control" name="phone" placeholder="phone" />
div>
div>
form>
phone: {
threshold: 5,//当输入的手机号小于5位时不进行实时验证 优化体验
validators: {
notEmpty: {
message: 'The phone number is required'
},
phone: {
message: 'The phone number is not valid'
}
}
},
启用实时验证模式时触发的字段事件。(即:什么时候进行再次验证),比如keyup、blur等事件发生时。
当有多个验证项时,其中一个验证项没有通过,是否显示全部的验证项
类似于属性设置,事件同样存在form表单级、filed验证项级、和validator验证项级。每一个事件可以通过三种方式去设置:
● 监听jquery事件 on(eventName , callback);
● 使用option设置项
● 使用html5属性设置
EVENT | DES |
---|---|
init.form.bv | 插件初始化后触发 |
error.form.bv | 插件验证失败后触发 |
success.form.bv | 插件验证成功后触发 |
added.form.bv | 动态添加验证项后触发 |
removed.form.bv | 动态删除验证项后触发 |
//1. jquery监听事件
$(document).ready(function(){
$(form)
.on('init.form.bv',function(e,data){dosonmeThing....})
.bootstrapValidator(options)
.on('error.form.bv',function(e){doSomething....})
.on('success.form.bv',function(e){dosomethinh...})
})
//2. bootstrapValitor作为初始化选项使用
$(document).ready({
$(form).bootstrapValidator({
onError:function(e){doSome};
onSuccess:function(e){doSome};
})
})
//3. 使用html5属性设置
<form data-bv-onerror="onFormError" data-bv-onsuccess="onFormSuccess"></form>
function onFormError(e) {
// Do something ...
};
function onFormSuccess(e) {
// Do something ...
};
$(document).ready(function() {
$(form).bootstrapValidator(options);
});
事件 | 描述 |
---|---|
init.field.bv | 在验证项被插件初始化之后触发 |
error.field.bv | 在任何一个验证域验证失败后触发 |
success.field.bv | 在任何一个验证域验证成功后触发 |
status.field.bv | 在验证域的状态发生改变时触发 |
每一个验证项含有四种状态:
● NOT_VALIDATED 该验证域还没有被验证
●VALIDATED 该验证域已经被验证
●INVALID 该验证项是无效的
●VALID 该验证域验证成功
使用方式同form的使用方式,同样含有三种调用方式:jquery监听,设置option属性,设置html5属性。如果只针对某一个表单验证项进行设置,可使用以下方式(以对name=email为例):
//jquery事件监听
$(document).ready(function(){
$(form).on('init.field.bv','[name="email"]',function(e,data){Do Something});
})
//设置初始化选项
$(document).ready(function(){
$form.bootstrapValidator({
fields:{
email:{
onSuccess:function(e){};
}
}
})
})