jquery.form.js 优秀的 Ajax 异步表单提交插件

Question

jquery.form.js 是一个优秀的 Ajax 异步表单提交插件，可以非常容易地、无侵入地升级 HTML 表单以支持 Ajax。jQuery Form 有两个核心方法，ajaxForm() 和 ajaxSubmit()， 它们集合了从控制表单元素到决定如何管理提交进程的功能。另外插件还包括其他的一些方法： formToArray()、formSerialize()、fieldSerialize()、fieldValue()、clearForm()、clearFields() 和 resetForm()等。

下载地址： http://malsup.com/jquery/form/

插件优点

• 简简单单几句代码，我们就可以实现表单的提交，并且可灵活通过ajaxSubmit()函数基于任何事件的触发实现表单异步提交。
• 支持文件上传功能，并在新浏览器中支持进度条更新。
• 与jQuery库完美结合，支持jQuery.ajax()函数触发的各种事件，支持jQuery.ajax()中所传递的参数。

使用方法

1、引入插件文件

<script src="~/Scripts/jquery-1.6.2.js"></script>
<script src="~/Scripts/jQuery.form.js"></script>

2、编写表单代码

<form id="ajaxForm" method="post" action="/Home/Index" enctype="multipart/form-data">
  <input type="text" name="name" />
  <input type="text" name="sex" />
  <input type="file" name="file" />
  <button type="submit" id="btnSubmit">提交1</button>
</form>
<button id="btnButton" type="button">提交2</button>

3、调用插件

有三种方法来调用插件，你可以选择你最喜欢方式

$(function () {
  
  $("#ajaxForm").ajaxForm(function () {
    alert("提交成功1");
  });
  
  $("#ajaxForm").submit(function () {
    $(this).ajaxSubmit(function () {
      alert("提交成功1");
    });
    return false;
  });
  
  $("#btnButton").click(function () {
    $("#ajaxForm").ajaxSubmit(function () {
      alert("提交成功2");
    });
    return false;
  });

});

快速使用

核心方法  ajaxForm() 和 ajaxSubmit()

$('#myForm').ajaxForm(function() {   
  $('#output1').html("提交成功！欢迎下次再来！").show();    
});  
$('#myForm2').submit(function() {
  $(this).ajaxSubmit(function() {   
    $('#output2').html("提交成功！欢迎下次再来！").show();    
  });
  return false; //阻止表单默认提交
});

通过 Form 插件的两个核心方法，都可以在不修改表单的 HTML 代码结构的情况下，轻易地将表单的提交方式升级为 Ajax 提交方式

使用参数

ajaxForm() 和 ajaxSubmit() 都能接受 0 个或 1 个参数，当为单个参数时，该参数既可以是一个回调函数，也可以是一个 options 对象，上面的例子就是回调函数，下面介绍 options 对象，使得它们对表单拥有更多的控制权。

var options = {
  target: '#output',       //把服务器返回的内容放入id为output的元素中  
  beforeSubmit: showRequest,  //提交前的回调函数
  success: showResponse,    //提交后的回调函数
  //url: url,            //默认是form的action， 如果申明，则会覆盖
  //type: type,          //默认是form的method（get or post），如果申明，则会覆盖
  //dataType: null,        //html(默认), xml, script, json...接受服务端返回的类型
  //clearForm: true,       //成功提交后，清除所有表单元素的值
  //resetForm: true,       //成功提交后，重置所有表单元素的值
  timeout: 3000          //限制请求的时间，当请求大于3秒后，跳出请求
}

function showRequest(formData, jqForm, options){
  //formData: 数组对象，提交表单时，Form插件会以Ajax方式自动提交这些数据，格式如：[{name:user,value:val },{name:pwd,value:pwd}]
  //jqForm:  jQuery对象，封装了表单的元素  
  //options:  options对象
  var queryString = $.param(formData);  //name=1&address=2
  var formElement = jqForm[0];          //将jqForm转换为DOM对象
  var address = formElement.address.value;  //访问jqForm的DOM元素
  return true;  //只要不返回false，表单都会提交,在这里可以对表单元素进行验证
};

function showResponse(responseText, statusText){
  //dataType=xml
  var name = $('name', responseXML).text();
  var address = $('address', responseXML).text();
  $("#xmlout").html(name + "  " + address);
  //dataType=json
  $("#jsonout").html(data.name + "  " + data.address);
};

$("#myForm").ajaxForm(options);

$("#myForm2").submit(funtion(){
  $(this).ajaxSubmit(options);
  return false;  //阻止表单默认提交
});

表单验证

表单提交之前进行验证： beforeSubmit 会在表单提交前被调用，如果 beforeSubmit 返回 false，则会阻止表单提交。

beforeSubmit: validate

function validate(formData, jqForm, options) { //在这里对表单进行验证，如果不符合规则，将返回false来阻止表单提交，直到符合规则为止
  //方式一：利用formData参数
  for (var i=0; i < formData.length; i++) {
    if (!formData[i].value) {
      alert('用户名,地址和自我介绍都不能为空!');
      return false;
    }
  } 

 //方式二：利用jqForm对象
 var form = jqForm[0]; //把表单转化为dom对象
    if (!form.name.value || !form.address.value) {
      alert('用户名和地址不能为空，自我介绍可以为空！');
      return false;
    }

 //方式三：利用fieldValue()方法，fieldValue 是表单插件的一个方法，它能找出表单中的元素的值，返回一个集合。
 var usernameValue = $('input[name=name]').fieldValue();
 var addressValue = $('input[name=address]').fieldValue();
 if (!usernameValue[0] || !addressValue[0]) {
    alert('用户名和地址不能为空，自我介绍可以为空！');
    return false;
 }

  var queryString = $.param(formData); //组装数据
  //alert(queryString); //类似 ： name=1&add=2  
  return true;
}

API 方法函数

jqXHR

jqxHR 对象存储在元素的 data-cache 中。可以通过下面的方式调用：

var form = $('#myForm').ajaxSubmit({ /* options */ });
var xhr = form.data('jqxhr');

xhr.done(function() {
...
});

ajaxForm

增加所有需要的事件监听器，为ajax提交表单做准备。ajaxForm并不能提交表单。在document的ready函数中，使用ajaxForm来为ajax提交表单进行准备。
接受0个或1个参数。参数可以是一个回调函数，也可以是一个Options对象。

$("#formid").ajaxForm();

ajaxSubmit

使用ajax提交表单，接受0个或1个参数。参数可以是一个回调函数，也可以是一个 Options 对象。

$("#formid").ajaxSubmit();

或

$("#formid").submit(function(){
    $(this).ajaxSubmit();
    return false;
});

formSerialize

将表单串行化（或序列化）为一个查询字符串。这个方法将返回以下格式的字符串：name1=value1&name2=value2。参数：无

$("#formid").formSerialize();

fieldSerialize

将表单的字段元素串行化（或序列化）为一个查询字符串。当只有部分表单字段需要进行串行化（或序列化）时，使用这个就很方便了。返回以下格式的字符串：name=value1&name2=value2。参数：无

$("#formid .specialFields").fieldSerialize();

fieldValue

返回匹配插入数组中的表单元素值。该方法以数组的形式返回数据。如果元素值被判定可能无效，则数组为空。参数：无

$("#formid :password").fieldValue();

resetForm

将表单恢复到初始状态。参数：无

$("#formid").resetForm();

clearForm

清除表单元素。该方法将所有的text、password、textarea置空，清除select元素中的选定，以及所有radio按钮和checkbox按钮重置为非选定状态。参数：无

$("#formid").clearForm();

clearFields

清除字段元素。只有部分表单元素需要清除时方便使用。参数：无

$("#formid .specialFields").clearFields();

Options 可选参数对象

ajaxForm 和 ajaxSubmit 都支持众多的选项参数，这些选项参数可以使用一个 Options 对象来提供。

target

指明页面中由服务器响应进行更新的元素。元素的值可能被指定为一个jQuery选择器字符串、一个jquery对象、一个DOM元素。默认值：null

url

指定提交表单数据的URL。默认值：表单的 action 属性值

type

指定提交表单数据的方法（method）：“GET”或“POST”。默认值：GET

beforeSubmit

表单提交前被调用的回调函数。如果回调函数返回false表单将不被提交。回调函数带三个调用参数：数组形式的表单数据，jQuery表单对象，以及传入ajaxForm/ajaxSubmit中的Options对象。默认值：null

success

表单成功提交后调用的回调函数。然后dataType选项值决定传回responseText还是responseXML的值。默认值：null

dataType

返回的数据类型：null、"xml"、"script"、"json"其中之一。默认值：null

resetForm

表示如果表单提交成功是否进行重置。默认值：null

clearForm

表示如果表单提交成功是否清除表单数据。默认值：null

github 地址：https://github.com/jquery-form/form