bootstrapValidator表单验证插件使用文档--配置项

下载地址

引入依赖库

<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>

准备form元素

因为bootstrapValidator是基于bootstarp设计，所以form表单的类名必须是bootstarp的结构化的类名。

验证元素和相关标签必须含有form-group类名的父级元素。

<div class="form-group">
       <label>Username</label>
       <input type="text" class="form-control" name="username" />
</div>
<!--如果没有form-group类名，将会报出以下错误：-->
<!--Chrome-->
Uncaught RangeError: Maximum call stack size exceeded
<!--Firefox-->
Too much recursion error

表单内的name属性和id属性不能使用表单元素，例如：submit、reset、length、method等

<!--错误示例-->
<button type="submit" name="submit" class="btn btn-primary">Submit</button>
<!--如果使用以上命名方式，表单即使在验证通过后也无法提交表单-->

验证元素必须有name属性，插件将根据name属性进行验证

<input type="text" class="form-control" name="email" placeholder="Email address" />

正确的表单元素准备

<!--含有lable标签-->
<form class="registerForm">
    <div class="form-group">
        <label>Username</label>
        <input type="text" class="form-control" name="username" />
    </div>
    <div class="form-group">
        <label>Password</label>
        <input type="text" class="form-control" name="Password" />
    </div>
</form>

初始化插件

一、初始化基础

准备好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的属性设置分为表单、验证元素、验证器三个等级，可根据不同的业务需求分别设置属性。

1. 表单级设置

可以通过两种方式对表单进行设置，在初始化的时候进行设置或者在准备form元素的时候在html中进行设置。推荐第一种设置方式。

通过初始化进行设置

$(formSelector).bootstrapValidator({
    ... 在这里书写表单级别的属性 ...
    fields: {}，
});

通过html5的前缀属性data-bv进行设置

<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

container：String

用来设置错误消息的提示

Value	Description
自定义dom及css样式	所有的错误消息提示被自定义的dom及类名所替换，需要自己准备dom元素及所对应的css样式
tooltip组件	使用bootstarp的tooltip组件展示错误消息不需要自己准备dom元素及css样式
popover组件	使用bootstarp的tooltip组件展示错误消息不需要自己准备dom元素及css样式

自定义错误提示示例

<!--自定义错误的html元素-->
<form id="contactForm" method="post" class="form-horizontal">
        <div class="form-group">
        <label class="col-sm-3 control-label">Full name</label>
        <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类名的错误提示

excluded：Boolean

表明那些表单元素不想被验证，默认条件下，以下元素不会被插件验证

disabled
hidden
invisible

该配置项支持三种格式:

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: \dotsdatoe){return !$ filed.is(’:visiable’)}]

feedbackIcon : Object

设置在提示过程中验证失败/验证成功/验证中的icon样式，主要支持两种样式

glyphicons 仅支持bootstarp V3.0及更高版本，使用该样式需要升级bootstarp到3.0版本
FontAwesome 需要在head中加入FontAwesome的css样式表

//使用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'
}

group：String

验证元素父级的css选择器，默认值为 .form-group。根据bootstarp的设计结构，每一个验证元素及其标签都需要被包裹在一个.form-group元素中。当需要改变父级的选择器时需要用到该配置项。

例如以下表单：使用td包裹验证元素，需要更改初始化中的group为td；

<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'
        },
})

live：String

插件的验证模式，默认为enabled

Value	Description
enabled	在验证域发生改变后立刻进行验证
disabled	禁用实时模式，只有表单在点击提交后才会显示错误消息
submitted	在表单被提交后启用实时验证

message：String

对于所有的验证域默认的提示消息，你也可以对于任意的一个验证域单独的指定特定的错误消息，需要在验证域配置项中进行修改。

submitButtons：String

提交按钮的选择器，当表单验证失败后，提交按钮被禁用

threshold：Number

如果验证域的字符少于该数字则该验证域不会实时验证。
！！！！不清楚是验证域的内容还是验证域本身的长度

trigger：String

在实时验证模式可用的情况下触发验证的事件。
trigger=“focus blur” 表示被验证的元素在聚焦或者失去聚焦时触发验证事件

verbose：Boolean

在验证域验证失败后时候要显示所有的错误细节，默认值为显示

Value	Description
true	如果一个验证域有多个验证项，当验证失败后会提示所有的验证细节，显示所有导致验证失败的验证项
false	只有与该字段相关的第一个验证消息会反馈给用户

2、元素级配置项

配置项	等效的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

container

验证项的错误消息提示的地方。（一般用来单独设置某一个配置项时使用）

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 name</label>
        <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:"不能为空"
                    }
                }
            }
        }
    });
});

enabled：Boolean

启用或禁用该字段的验证项

excluded：Boolean

在验证时是否排除该字段

feedbackIcons：Boolean

启用或禁用该字段的提示图标

group:String

被验证项的父级元素所包含的类选择器默认为 .form-group

message:String

该验证项的错误提示消息

selector：String

验证项的css选择器，用于设置没name或无法用name进行验证的验证项

threshold：Number

当验证项的值少于设置的位数的时候不进行实时验证

<form id="fieldContainerForm" class="form-horizontal">
    <div class="form-group">
        <label class="col-sm-3 control-label">phone</label>
        <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'
         }
    }
},

trigger：String

启用实时验证模式时触发的字段事件。（即：什么时候进行再次验证），比如keyup、blur等事件发生时。

verbose：Boolean

当有多个验证项时，其中一个验证项没有通过，是否显示全部的验证项

三、事件（EVENT）

类似于属性设置，事件同样存在form表单级、filed验证项级、和validator验证项级。每一个事件可以通过三种方式去设置：
● 监听jquery事件 on（eventName ， callback）；
● 使用option设置项
● 使用html5属性设置

form事件

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);
});

filed事件

事件	描述
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){};
            }
        }
    })
})

bootstrapValidator表单验证插件使用文档--配置项

下载地址

引入依赖库

准备form元素

初始化插件

一、初始化基础

二、初始化属性设置

1. 表单级设置

container：String

自定义错误提示示例

excluded：Boolean

feedbackIcon : Object

group：String

live：String

message：String

submitButtons：String

threshold：Number

trigger：String

verbose：Boolean

2、元素级配置项

container

enabled：Boolean

excluded：Boolean

feedbackIcons：Boolean

group:String

message:String

selector：String

threshold：Number

trigger：String

verbose：Boolean

三、事件（EVENT）

form事件

filed事件

猜你喜欢