核心参数

debug - 调试

类型Number
默认0
可用值

  • 0:关闭调试信息
  • 1:开启调试信息(查看浏览器控制台)
  • 2:开启调试,无视验证结果直接触发验证通过事件

timely - 实时验证

类型Number
默认1
可用值

  • 0:关闭实时验证,只在提交表单的时候执行验证
  • 1:输入框失去焦点(focusout)时执行验证
  • 2:输入框改变值(input)时执行验证
  • 3:输入框失去焦点和改变值(综合 1 + 2) (v0.8.0+)
  • 8:同 2,并且详细提示每个规则的结果 (v0.9.0+)
  • 9:同 3,并且详细提示每个规则的结果 (v0.9.0+)
  • 大于 100 的数值:验证延迟时间

theme - 主题

类型String
默认"default"
主题名称,每个表单验证实例可以设置不同的主题。参考自定义主题,以及 zh-CN.js 的主题配置

stopOnError - 在第一次错误时停止验证

类型Boolean
默认false

focusInvalid - 第一个错误字段自动获得焦点

类型Boolean
默认true

focusCleanup - 输入框获得焦点时清除验证消息

类型Boolean
默认false

ignoreBlank - 不验证空值的字段(只针对实时验证)

支持v0.8.0+
类型Boolean
默认false

ignore - 忽略验证 jQuery 选择器选中的字段

类型jqSelector
默认""
示例

//任何不可见的元素,都不作验证
$('form').validator({
    ignore: ':hidden'
});
//id为tab2下的所有子元素都不作验证
$('form').validator({
    ignore: '#tab2'
});
//动态改变要忽略验证的元素
$('form').data('validator').options.ignore = '#tab1';

display - 自定义消息中{0}的替换字符

类型Function(elem)
默认null
示例

$('form').validator({
    display: function(elem){
        return $(elem).closest('.form-item').children('label:eq(0)').text();
    }
});

target - 自定义消息的显示位置

类型Function(elem) | jqSelector
默认null
描述:验证当前字段,但是实际上在 target 的元素上提示错误消息。
1、如果目标元素是输入框(input,textarea、select),将会以目标元素为基准点,插入一条消息;
2、如果目标元素是消息占位(class="msg-box"),这和直接使用消息占位没有区别;
3、其他情况下,直接显示在target指向的消息容器中。

消息容器与消息占位的区别:消息占位只能包含一条消息,消息容器可以容纳很多消息。

示例

$('form').validator({
    // 自己指定消息容器位置
    target: function(elem){
        var $formitem = $(elem).closest('.form-item'),
            $msgbox = $formitem.find('span.msg-box');
        if (!$msgbox.length) {
            $msgbox = $('<span class="msg-box"></span>').appendTo($formitem);
        }
        return $msgbox;
    }
});

$('form').validator({
    // 将所有消息全部提示在 id 为 myContainer 里面
    target: "#myContainer"
});

valid - 表单验证通过时调用此函数

类型Function(form)
默认null
描述:表单验证成功后的回调。也可以使用 valid.form 事件
示例:ajax 提交表单

$('#form1').validator({
    fields: {
        username: "required; email|mobile; remote(/check/username)",
        password: "required; length(6~16)",
        passwordAgain: "match(password)"
    },
    valid: function(form){
        // 表单验证通过,提交表单
        $.post("path/to/server", $(form).serialize())
            .done(function(d){
                // some code
            });
    }
});

invalid - 表单验证不通过时调用此函数

类型Function(form, errors)
默认null
描述:表单验证失败后的回调。也可以使用 invalid.form 事件
示例:摇晃提交按钮(需要 animate.css 支持)

$('#form1').validator({
    invalid: function(form, errors){
        var CLS_ANIMATE = 'shake animated';
        $('#submitBtn').addClass(CLS_ANIMATE)
            .one('animationend webkitAnimationEnd mozAnimationEnd', function(){
                $(this).removeClass(CLS_ANIMATE);
            });
    }
});

validation - 验证每个字段后调用此函数

类型Function(form)
默认null
描述:验证完每个字段时的回调。也可以使用 validation 事件
示例:只有在全部字段都验证通过时,提交按钮才可用

$('#form1').validator({
    validation: function(element, result){
        $("#submitBtn").prop('disabled', !element.form.isValid)
    }
});

rules - 自定义规则

类型Object
默认null
示例:自定义用于当前实例的规则,支持两种定义方式

$('form').validator({
    rules: {
        // 自定义验证函数,具有最大的灵活性
        myRule: function(el, param, field){
            //do something...
        },
        // 简单配置正则及错误消息
        another: [/^\w*$/, 'Please enter the letters or underscore.']
    },
    fields: {
        //调用前面定义的两个规则
        foo: 'required; myRule[param]; another'
    }
});

messages - 自定义消息

类型Object
默认null
描述:自定义用于当前实例的规则消息。当有多个字段使用同一个规则,而这个规则没有消息或需要覆盖它的消息,则使用 messages 统一配置比较方便。消息中可以包含{0}模板变量,会自动替换成 display 的值
示例

$('form').validator({
    messages: {
        required: "Please fill in this field",
        email: "Please enter a valid email address.",
    },
    fields: {
        'email': 'required;email;'
    }
});

fields - 配置字段规则及参数

类型Object - 待验证的字段集合,键为字段的 name 值或者 #id
默认null
参数

  • fields[key].rule
    字段规则,多个规则用分号 “;” 分隔,支持使用圆括号 “( )” 或者方括号 “[ ]” 传参
  • fields[key].msg
    自定义字段中每个规则的错误消息
  • fields[key].tip
    自定义获得焦点时的友好提示信息
  • fields[key].ok
    自定义字段验证成功后显示的消息
  • fields[key].valid
    字段验证通过的回调
  • fields[key].invalid
    字段验证失败的回调
  • fields[key].timely
    是否启用实时验证,默认继承
  • fields[key].target
    验证当前字段,但是实际上在 target 的元素上提示错误消息,
    如果目标元素是输入框(input,textarea、select),将会以目标元素为基准点,插入一条消息;
    如果目标元素是消息占位(className 为 msg-box),这和直接使用消息占位没有区别
    其他情况下,直接显示在target指向的容器中
  • fields[key].dataFilter
    使用 dataFilter 回调可以转换 ajax 返回的结果为 nice-validator 支持的格式
  • fields[key].must
    是否强制验证该字段
  • fields[key].msgWrapper
    自定义该字段的消息容器的标签名
  • fields[key].msgMaker
    自定义该字段的消息生成器
  • fields[key].msgClass
    自定义该字段的消息Class
  • fields[key].msgStyle
    自定义该字段的消息 CSS 样式
  • fields[key].getValuev1.0.0+
    自定义 value 的 getter
  • fields[key].setValuev1.0.0+
    自定义 value 的 setter

示例:快捷传参和对象传参

fields: {
    //name 字段使用对象传参
    name: {
        rule: "姓名: required; rule2; rule3",
        msg: {
            required: "请填写姓名",
            rule2: "xxxx",
            rule3: "xxxx"
        },
        tip: "填写真实姓名有助于朋友找到你",
        ok: "",
        timely: false,
        target: "#msg_holder"
    },
    //email 和 mobile 字段使用快捷传参
    email: "required; email",
    mobile: "mobile"
}

beforeSubmit - 在提交表单之前调用此函数

类型Function(form)
默认null

一次 submit 事件触发的流程:

  1. 接收 form 的 submit 事件;
  2. 执行 beforeSubmit 回调,如果 beforeSubmit 返回值为 false,将取消本次验证与提交;
  3. 验证整个表单;
  4. 根据表单验证结果决定执行 valid 回调还是 invalid 回调

dataFilter - 转换ajax返回数据为插件支持的格式

类型Function(data)
默认null
示例:如果服务端返回格式无法更改,可以用 dataFilter 参数转换

/* 假设服务端返回结果为: {"status":600, "msg":"名字已被占用"}
 */
$('#form1').validator({
    dataFilter: function(data) {
        if (data.status === 200) return "";
        else return data.msg;
    },
    fields: {
        name: "required; length(4~12); remote(/user/check/name)"
    }
});

主题相关参数

showOk - 是否显示成功提示

类型Boolean|String
默认true

是否显示成功提示(注意:前提是有传ok的消息),如果设置成false在字段验证通过后将只是简单的隐藏消息。
还有另一种用法:如果传递一个字符串,在验证通过后将提示这个消息,如果设置成空字符串,将只显示一个成功的图标

//字段验证通过后提示“正确”
$('form').validator({
    showOk: "正确"
});
//对于simple_right主题,验证通过后默认不会提示,只是单纯的隐藏错误消息
//加上 showOk: "" 这个配置后,将显示一个通过的图标
$('form').validator({
    theme: "simple_right",
    showOk: ""
});

validClass - 给验证通过的输入框添加的class名

类型String
默认n-valid

invalidClass - 给验证不通过的输入框添加的class名

类型String
默认n-invalid

bindClassTo - 设置 validClass 和 invalidClass 添加到的位置

支持v0.9.0+
类型jqSelector
默认:verifiable
示例:适配 Bootstrap 样式

<form id="form1">
    <div class="form-group">
        <label for="email">Email address</label>
        <input type="email" name="email" id="email" class="form-control" placeholder="Email">
    </div>
</form>
$('#form1').validator({
    validClass: "has-succes",
    invalidClass: "has-error",
    bindClassTo: ".form-group",
    fields: {
        email: "required; email"
    }
});

formClass - 主题的 class 名称,添加在 form 上

类型String
默认n-default

msgClass - 字段消息的 class 名称,添加在消息容器上

类型String
默认n-right
示例

msgClass: "n-top"     //消息将自动显示在输入框上边
msgClass: "n-right"   //消息将自动显示在输入框右边
msgClass: "n-bottom"  //消息将自动显示在输入框下边
msgClass: "n-left"    //消息将自动显示在输入框左边
msgClass: "n-right myclass"    //消息将自动显示在输入框右边,你还可以通过myclass来定义更多样式

msgStyle - 自定义 CSS 样式,添加在消息容器上

类型String
默认""
示例

// 有时候主题定义的消息样式的位置没有达到预期,就可以通过 msgStyle 参数传递 css 来精确控制消息位置
$('form').validator({
    theme: "simple_right",
    msgStyle: "margin-left:-10px; margin-top:10px;",
    fields: {
        'email': 'required;email;'
    }
});

msgWrapper - 消息容器的 tagName

类型String
默认span

msgMaker - 自定义消息 HTML 结构

类型Function(obj) | Boolean
默认null
说明:msgMaker 生成的消息 HTML 会插入到对应的 msgWrapper 中,如果不想生成消息,可以设置msgMaker:false
示例

$('#form').validator({
    fields: {
        'user[name]': 'required;username'
        ,'user[pwd]': 'required;password'
    },
    msgWrapper: 'div',
    msgMaker: function(opt){
        return '<span class="'+ opt.type +'">' + opt.msg + '</span>';
    }
});

以上 msgMaker 配置,将生成如下消息结构

<div class="msg-box n-right" for="user[name]">
    <span class="n-error">Please fill this field.</span>
</div>

msgIcon - 自定义消息图标的 HTML 模板

类型String
默认"<span class="n-icon"></span>"

msgArrow- 自定义消息箭头的 HTML 模板

类型String
默认""

msgShow - 消息提示之前调用此函数

类型Function($msgbox, type)
默认null

msgHide - 消息隐藏之前调用此函数

类型Function($msgbox, type)
默认null