WebForms

语义化 Web 表单，提供体系完整、灵活高效、高度一致的 Web 表单方案。

设计思想

通过简单、语义化语法来定义表单，简化 Web 表单。
体系化、完整、一致的表单定义。
- 校验、富 UI 控件等只是表单的一部分。
- 用户需要的是一个完整的表单，不会有只需要校验或其他某一小部分的场景。
- 开发、设计、定义的一致性。
- 用户使用的交互、反馈一致性。
灵活、完整定义表单交互反馈的控制权。

使用说明

<form id="loginForm">
  UserName: <input type="text" name="username" required /> * 可以是邮箱或手机号。
  PassWord: <input type="password" name="pwd" required minlength="6" maxlength="30" /> *
</form>

var loginForm = new WebForms(form, {
  rules: {
    "username": function(field){
      return this.RULES.email.test(field.value) ||
             this.RULES.mobile.test(field.value);
    }
  }
})

WebForms 的构造函数中，参数列表如下：

第一个参数是用于指定表单。
- 可以是表单的 ID。（可选添加 # 前缀）
```
new WebForms("formId");
new WebForms("#formId");
```
- 或者是 HTMLFormElement 元素。
```
new WebForms(document.getElementById("formId"));
```
第二个参数用于指定表单的各个可选选项，该参数本身可选。
- rules: Object, 自定义的表单项校验函数。
  - 前缀为 # 的 key 表示是针对特定 id 的表单项的定义。
  - 其他的 key 表示是针对特定 name 的表单项的定义。

HTML API

参考 HTML5 的表单定义，并做了少许补充。

form[novalidate]

指定当前表单不进行输入合法性校验。

field[required]

声明表单项为必填项。

注：field 为表单项统称，包括 input, select, textarea, button 等。下同。

field[maxlength=number]

声明表单项的可填写最大长度为 number。

field[minlength=number]

声明表单项的填写最小长度为 number。

field[max]

指定表单项的最大值。用户可以输入小于或等于这个值的内容。

使用的 field 包括数值和日期型表单项，如：input[type=number], input[type=date], ...

field[min]

指定表单项的最小值。用户可以输入大于或等于这个值的内容。

使用的 field 包括数值和日期型表单项。

field[pattern]

指定表单项的校验规则表达式。

pattern 的值是正则表达式，用户输入的内容必须匹配这个表达式。

field[validated]

异步校验的表单项需要设置这个属性，默认值留空即可。

field[formnovalidate]

指定忽略校验的表单项。

input[type]

指定表单项的类型，支持的类型包括：

text: 文本输入框。
radio: 单选框。
checkbox: 复选框。
password: 密码框。
hidden: 隐藏表单项。
search: 搜索框。
file: 文件选择输入框。
number: 数值输入框。
range: 范围选择、输入框。
date: 日期输入框。
time: 时间输入框。
datetime: 日期时间输入框。
month: 月份输入框。
week: 星期（周）输入框。
datetime-local: 本地日期时间输入框。
url: 网址输入框。
email: 邮箱地址输入框。
tel: 联系电话输入框。
color: 色彩输入框。

input[type=file][accept]

指定文件输入框限制的文件类型。

如：

<input type="file" accept="image/jpg,.png,video/*" />

accept 属性支持 MIME-TYPE 和后缀设定。更多参考：

form[validationRealtime]

定义整个表单是否使用实时校验。

默认不添加 validationRealtime 属性时，整个表单默认不进行实时校验。

field[validationRealtime]

定义单个表单项是否使用实时校验。添加 validationRealtime 属性默认为使用实时校验，除非 field[validationRealtime=nonrealtime]。

JavaScript API

on(String event, Function handler)

绑定事件，在对应事件触发时，执行 handler 函数。

支持的事件请参考 Events 部分。

each(Function handler)

遍历整个表单的所有表单项。

new WebForms("#formId").each(function(field){
  switch(field.name){
  case "username":
    this.RULE.email.test(field.value);
    break;
  }
  // ...
});

String queryString()

根据用户在表单中的输入值，返回整个表单的查询字符串。

Events

WebForms 提供了完整的事件模型，通过监听各种事件就可以几乎所有的表单交互动作。

通过 WebForms 的实例的 on 方法即可绑定事件监听。
on 方法的处理函数 handler 中，提供了对应表单项的常用信息，包括：
- field.name: 表单项名称，即对应的 name 属性，如果没有 name 属性则为 null。
- field.id: 表单项 ID，即对应的 ID 属性，如果没有 ID 则为 null。
- field.type: 表单项的类型，即 input 的 type 属性、textarea、select-one 或 select-multiple。
- field.value: 表单项当前的值。
- field.element: 表单项本身的 HTMLElement。

valid

单个表单项通过校验时触发 valid 事件。

var WebForms = require("WebForms");

var webforms = new WebForms("#formId");
webforms.on("valid", function(field){
  switch(field.name){
  case "username":
    //...
    break;
  }
});

invalid

单个表达项未通过校验时触发 invalid 事件。

change

单个表单项发生变更时触发 change 事件。

focus

单个表单项获得焦点时触发 focus 事件。

blur

单个表单项失去焦点时触发 blur 事件。

mouseover

鼠标进入单个表单项时触发 mouseover 事件。

mouseout

鼠标离开单个表单项时触发 mouseout 事件。

error

WebForms 出现异常时触发 error 事件。

常见异常包括：

尝试 focus 到第一个未通过校验的表单项失败（由于其处于隐藏状态）

validate:complete

整个表单校验完成后触发 complete 事件。

注：针对整个表单的事件，参数上下文与单个表单项不同，如下：

webforms.on("validate:complete", function(certified){
    console.log(certified ? "passed": "failed")
});

submit

表单校验通过，可以提交表单时触发 submit 事件。

绑定 submit 事件的处理函数中，返回 false 可以取消表单提交。希望使用异步方式提交表单时可以使用这种方式。

webforms.on("submit", function(form){
  jQuery.ajax({
    url: form.action,
    data: form.queryString(),
    success: function(){}
  });
  return false;
});

TODO

默认的几种验证反馈
日期相关整理，或切换到 moment.js
placeholder
autofocus
replicable
calendar
range

Webforms

Install / Use

README