【译】表单验证插件 jquery validation 参考文档

本文由【咚门】翻译,未经允许,请勿转载

jQuery Validation Plugin是非常受欢迎的一个前端表单验证插件,本文是对其参考文档的翻译。
有一些单词、词组对这个插件本身来说相当于专用名词,如果翻译为中文,反而会适得其反,有碍于阅读者对插件用法的理解,所以对这些单词、词组,我尽量保持不翻译的原则。

General Guidelines

Reference documentation

本章节提供了对这个插件背后的设计和思考的详细讨论,这些讨论可以帮助你“知其所以然”API 文档只是简单地解释各种可用的方法(methods)和配置选项(options),而本节内容涵盖了各功能点更多的细节。

如果你已经决定在你的应用中使用这个插件 并且 想要更好地了解它,那么我们建议你阅读这些指南。


1. Goals 目的

这个插件的首要目的就是让 人们使用表单 变得更加有趣。通过改善交互,它让 填写和提交表单 对用户来说变得更加容易和没那么恼人。

为了达到这个目的,插件部署到世界各地的网站是很重要的,因此我们花了大量精力让这个插件对开发者易于使用。

这个插件从来都不能取代服务器端的验证(serverside validation)并且也不打算这样做。两种验证都做(即浏览器端和服务器端都对数据进行验证) 可以为你的应用提供必要的安全性,以及提升易用性。

2. Markup recommendations 建议

input 元素必须要有name属性,因为如果没有这个属性,这个插件将不会起作用(work)。

3. Methods 方法

validation method 用于实现验证逻辑。提供的是一系列默认的 validation method,例如 required。当一个元素没有值的时候,除了required本身和equalTo,所有的 validation method 都认为它是有效的。这样的话,除非指定了required,否则一个 email 输入框一般是选填的。你可以指定一个元素输入框包含一个有效的 email 地址,或者什么也不指定。使用 jQuery.validator.addMethod 来实现常用的 method。

4. Rules 规则

validation rule 把一个或多个 validation method 应用到一个 input 元素上。你可以通过 metadata(元数据?) 或 插件设置(rules 选项)来指定 validation rules。The decision is often influenced by serverside infrastructure. If a web framework is used, it is often easier to use metadata, which is also good for fast prototyping. Plugin settings produce cleaner markup, though valid markup results from both.

5. Fields with complex names (brackets, dots) 带有复杂name(括弧、圆点)的输入框

如果你的表单由 使用不合法的 JavaScript 标识符的name的输入框 组成,那么当使用rules选项的时候,你必须用引号把这些name包起来。

    $("#myform").validate({
        rules: {
            // no quoting necessary
            name: "required",
            // quoting necessary!
            "user[email]": "email",
            // dots need quoting, too!
            "user.address.street": "required"
        }
    });

6. Refactoring rules 重构规则

只要(whenever)你有几个带有相同 rules 和 messages 的输入框,重构这些 rules 和 messages 可以减少许多重复代码(duplication,重复、成本)。要实现这个,使用 addMethod 和 addClassRules 是最有效率的。

让我们看一个例子(Let's consider an example),你有十个客户输入框(customer fields,这里的 customer 不太好理解),每一个要遵守两个 rule:必填的并且最小长度为 2。你需要为这两个 rule 定制不同的 message。为了避免一次又一次地指定那些 rules 和 messages,我们可以化名为 带有不同 messages 的 已存在的 method 并且把它们分组到一个单独的类(即下面代码中的 customer 类)(we can alias existing methods with different messages and group them into a single class):

// alias required to cRequired with new message
$.validator.addMethod("cRequired", $.validator.methods.required,"Customer name required");

// alias minlength, too
$.validator.addMethod("cMinlength", $.validator.methods.minlength,
// leverage parameter replacement for minlength, {0} gets replaced with 2
$.validator.format("Customer name must have at least {0} characters"));

// combine them both, including the parameter for minlength
$.validator.addClassRules("customer", { cRequired: true, cMinlength: 2 });

这样做好之后,我们可以把 customer 类添加到所有的客户输入框,将像下面这样(With that in place, we can add a class customer to all customer fields and be done with it):

<inputname="customer1" class="customer">
<input name="customer2" class="customer">
<input name="customer3" class="customer">

你也可以复用(reuse)在其他 custom method 内的 已存在的 method ,以复用某些实现(implementation)。例如,如果你正在写一个用于验证一个单独的输入框内的 email 地址的 custom method。你可以调用(call)适用于所有 email 的 已存在的 email method:

jQuery.validator.methods.email.call(this, email, element)

7. Error messages 错误信息

error message 为用户显示 关于无效元素和错误 的提示信息。有四种方式可以提供 error message通过 input 元素的title属性来验证功能,通过data属性,通过 error 标签,和通过插件设置(messages选项)

这里的所有 validation rules 都提供一个默认的 error message,它可以用于 prototype (原型机制造),因为当没有指定的 message 的时候才会用到它。

优先顺序是这样子的(are as follows):定制的 message (由插件选项传递),元素的 title,默认的 message。

使用data 属性的时候,你可以为所有 rules 设置一个通用的(generic,一般的,类的,属性的)message,或者每个 rule 分别指定 message:

<input required data-msg="Please fill this field">
<input data-rule-minlength="2" data-rule-maxlength="4" data-msg-minlength="At least two chars" data-msg-maxlength="At most fours chars">

8. Error message display

error message 是通过一个带有额外的类(errorClass选项)<label>元素来处理的。message 和 无效元素 之间的联系是通过<label>标签的for属性提供的。当在标记(markup)中提供 error message 时,它们会相应地被显示和隐藏,否则按需创建(created on demand)。默认地,<label>是被创建在无效元素后面的,这也是可以定制的(errorPlacement选项)。也可以把这些 error message 放到一个 error container 错误容器中(errorLabelContainer选项)。如果要使用一个不同的元素而不是<label>,请指定选项errorElement

9. General messages

除了输入框指定的 message 之外,你可以在页面中任何地方的一个 container(容器)里显示一条通用的信息:“your form is invalid, please fix the highlighted fields!”,例如在表单的正上方(选项errorContainer)。当 error 出现或被修复时,这个 container(容器)也相应地被显示和被隐藏。error 标签的 container(容器)也可以被嵌入到 error container 里。(有点乱。。。)

10. Focusing of invalid elements

默认地,提交表单之后,如果表单中含有无效的元素,那么表单中第一个无效元素会被聚焦。为了避免与用户冲突,这个插件会记住表单被提交时正在被聚焦的那个元素,并重新聚焦到那个元素上。这样的话,用户就可以尝试填写表单末尾的元素,而不是被迫一次又一次地重新聚焦(到想要填写的元素上)。这个设置是可以被禁止的(focusInvalid选项)。

11. Form submit 表单提交

默认地,当表单是无效的时候,表单提交时被阻止的,并且当它是有效的时候,正常提交。你也可以手动地处理提交(submitHandler选项)。

12. Skipping validation on submit

当使用type="submit"的按钮的时候,为了跳过验证,请添加formnovalidate属性到那个表单上:

<input type="submit" name="go" value="Submit">
<input type="submit" formnovalidate name="cancel" value="Cancel">

这曾经通过添加class="cancel"来实现,但现在不赞成这样子做。(This used to work by adding class="cancel" to the input, this is now deprecated.)

Demo for the cancel button

13. Validation event “验证”事件

默认地,forms are validated on submit,可以由两种操作出发:用户点击提交按钮,或当表单输入框被聚焦的时候 用户按下 Enter 键(onsubmit选项)。另外,一旦一个输入框被强调为(was highlighted as)无效的,接下来,只要(whenever)用户在输入框输入任何字符,这个输入框都会被验证一遍。当用户输入了一些无效的内容到一个有效的输入框内,当输入框失去焦点的时候(onblur选项),这个输入框同样也会被验证一遍。

这些交互的目的是为了尽可能早地提供反馈,同时避免用户苦恼。在用户还有机会输入一些内容之前 就展示 error message 是不好的。

14. Developing and debugging a form

在开发和 debug 表单的同时,你应该把debug选项设置为 true。这可以防止提交两个有效的和无效的表单(prevents form submission on both valid and invalid forms),并且 输出一些有帮助的信息到window.console(通过 Firebug 或 Firebug Lite 可以获取),这有助于 debug。当你把一切都设置好了以后,却没有显示任何 error message,请检查你的 rule 是否都接受空的元素位(empty elements)有效的(像 email method 和 url method 一样)。

有一些问题是由某些表单元素的name导致的。你应该避免把(提交按钮或其他任何元素的)name设为“submit”。Browsers expose form elements as properties of the form element, by their name, in this case hiding native methods like submit(). 只要记住不要使用name="submit",你的人生就会很美好~~~

15. Validating multiple forms on one page 验证一个页面内的多个表单

这个插件每次调用只能处理一个表单。在一个页面内有多个表单的情形下,你不得不一个一个地初始化这些表单(initialise them all individually):

$( "form" ).each( function() {
    $( this ).validate( options );
});

通过修改默认设置,用 jQuery.validator.setDefaults 来一次性覆盖多个设置,你可以免于重复插件设置。


其它

太多的递归:

另一个常见的问题常常出现在下面这种代码中:

$("#myform").validate({
    submitHandler: function(form) {
        // some other code
        // maybe disabling submit button
        // then:
        $(form).submit();
    }
});

这会导致 too-much-recursion 错误:$(form).submit()会触发下一轮验证,导致对submitHandler的另一次调用,也就是递归。

正确的做法是:用form.submit()替上面代码中的$(form).submit(),因为form.submit()会触发本地(应该是指插件本身)的提交事件,而不是验证。正确的代码如下:

    $("#myform").validate({
        submitHandler: function(form) {
            form.submit();
        }
    });
最后编辑于
©著作权归作者所有,转载或内容合作请联系作者
  • 序言:七十年代末,一起剥皮案震惊了整个滨河市,随后出现的几起案子,更是在滨河造成了极大的恐慌,老刑警刘岩,带你破解...
    沈念sama阅读 202,607评论 5 476
  • 序言:滨河连续发生了三起死亡事件,死亡现场离奇诡异,居然都是意外死亡,警方通过查阅死者的电脑和手机,发现死者居然都...
    沈念sama阅读 85,047评论 2 379
  • 文/潘晓璐 我一进店门,熙熙楼的掌柜王于贵愁眉苦脸地迎上来,“玉大人,你说我怎么就摊上这事。” “怎么了?”我有些...
    开封第一讲书人阅读 149,496评论 0 335
  • 文/不坏的土叔 我叫张陵,是天一观的道长。 经常有香客问我,道长,这世上最难降的妖魔是什么? 我笑而不...
    开封第一讲书人阅读 54,405评论 1 273
  • 正文 为了忘掉前任,我火速办了婚礼,结果婚礼上,老公的妹妹穿的比我还像新娘。我一直安慰自己,他们只是感情好,可当我...
    茶点故事阅读 63,400评论 5 364
  • 文/花漫 我一把揭开白布。 她就那样静静地躺着,像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上,一...
    开封第一讲书人阅读 48,479评论 1 281
  • 那天,我揣着相机与录音,去河边找鬼。 笑死,一个胖子当着我的面吹牛,可吹牛的内容都是我干的。 我是一名探鬼主播,决...
    沈念sama阅读 37,883评论 3 395
  • 文/苍兰香墨 我猛地睁开眼,长吁一口气:“原来是场噩梦啊……” “哼!你这毒妇竟也来了?” 一声冷哼从身侧响起,我...
    开封第一讲书人阅读 36,535评论 0 256
  • 序言:老挝万荣一对情侣失踪,失踪者是张志新(化名)和其女友刘颖,没想到半个月后,有当地人在树林里发现了一具尸体,经...
    沈念sama阅读 40,743评论 1 295
  • 正文 独居荒郊野岭守林人离奇死亡,尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 35,544评论 2 319
  • 正文 我和宋清朗相恋三年,在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 37,612评论 1 329
  • 序言:一个原本活蹦乱跳的男人离奇死亡,死状恐怖,灵堂内的尸体忽然破棺而出,到底是诈尸还是另有隐情,我是刑警宁泽,带...
    沈念sama阅读 33,309评论 4 318
  • 正文 年R本政府宣布,位于F岛的核电站,受9级特大地震影响,放射性物质发生泄漏。R本人自食恶果不足惜,却给世界环境...
    茶点故事阅读 38,881评论 3 306
  • 文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹,春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 29,891评论 0 19
  • 文/苍兰香墨 我抬头看了看天上的太阳。三九已至,却和暖如春,着一层夹袄步出监牢的瞬间,已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 31,136评论 1 259
  • 我被黑心中介骗来泰国打工, 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留,地道东北人。 一个月前我还...
    沈念sama阅读 42,783评论 2 349
  • 正文 我出身青楼,却偏偏与公主长得像,于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子,可洞房花烛夜当晚...
    茶点故事阅读 42,316评论 2 342

推荐阅读更多精彩内容

  • Spring Cloud为开发人员提供了快速构建分布式系统中一些常见模式的工具(例如配置管理,服务发现,断路器,智...
    卡卡罗2017阅读 134,579评论 18 139
  • HTML表单 在HTML中,表单是 ... 之间元素的集合,它们允许访问者输入文本、选择选项、操作对象等等,然后将...
    兰山小亭阅读 3,408评论 2 14
  • Spring Boot 参考指南 介绍 转载自:https://www.gitbook.com/book/qbgb...
    毛宇鹏阅读 46,717评论 6 342
  • 表单基础知识 在HTML中,表单是由 元素来表示的,而在JS中,表单对应的则是HTMLFormElement类型。...
    oWSQo阅读 902评论 0 1
  • 人的一生知道的东西是有数的 跟电脑这种没点B数的不一样 从现在开始睁开眼也不晚~
    缴智商税阅读 165评论 0 0