jQuery form插件的使用--ajaxForm()和ajaxSubmit()的可选参数项对象

一、前提说明

Form Plugin API 里提供了很多有用的方法可以让你轻松的处理表单里的数据和表单的提交过程。

测试环境：部署到Tomcat中的web项目。

二、简单介绍

本文演示的是：jQuery form插件的使用--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;
}

三、详细介绍参数

ajaxForm()和ajaxSubmit()的可选参数项对象

 ajaxForm 和 ajaxSubmit 都支持大量的可选参数，它们通过可选参数项对象传入。可选参数项对象只是一个简单的 JavaScript对象，里边包含了一些属性和一些值:

target

用server端返回的内容更换指定的页面元素的内容。 这个值可以用jQuery 选择器来表示, 或者是一个jQuery 对象， 一个 DOM 元素。
缺省值： null

url

表单提交的地址。
缺省值： 表单的action的值

type

表单提交的方式，'GET' 或 'POST'.
缺省值： 表单的 method 的值 (如果没有指明则认为是 'GET')

beforeSubmit

表单提交前执行的方法。这个可以用在表单提交前的预处理，或表单校验。如果'beforeSubmit'指定的函数返回false，则表单不会被提交。 'beforeSubmit'函数调用时需要3个参数：数组形式的表单数据，jQuery 对象形式的表单对象，可选的用来传递给ajaxForm/ajaxSubmit 的对象。

数组形式的表单数据是下面这样的格式：[ { name: 'username', value: 'jresig' }, { name: 'password', value: 'secret' } ]

缺省值： null

success

当表单提交后执行的函数。 如果'success' 回调函数被指定，当server端返回对表单提交的响应后，这个方法就会被执行。 responseText 和 responseXML 的值会被传进这个参数 (这个要依赖于dataType的类型).
缺省值： null

dataType

指定服务器响应返回的数据类型。其中之一: null, 'xml', 'script', 或者 'json'. 这个 dataType 选项用来指示你如何去处理server端返回的数据。 这个和 jQuery.httpData 方法直接相对应。

下面就是可以用的选项：

'xml': 如果 dataType == 'xml' 则 server 端返回的数据被当作是 XML 来处理， 这种情况下'success'指定的回调函数会被传进去 responseXML 数据

'json': 如果 dataType == 'json' 则server端返回的数据将会被执行，并传进'success'回调函数

'script': 如果 dataType == 'script' 则server端返回的数据将会在上下文的环境中被执行

缺省值： null

semantic

一个布尔值，用来指示表单里提交的数据的顺序是否需要严格按照语义的顺序。一般表单的数据都是按语义顺序序列化的，除非表单里有一个type="image"元素. 所以只有当表单里必须要求有严格顺序并且表单里有type="image"时才需要指定这个。
缺省值： false

resetForm

布尔值，指示表单提交成功后是否需要重置。
缺省值： null

clearForm

布尔值，指示表单提交成功后是否需要清空。
缺省值： null

iframe

布尔值，用来指示表单是否需要提交到一个iframe里。 这个用在表单里有file域要上传文件时。更多信息请参考 代码示例 页面里的File Uploads 文档。
缺省值： false

四、案例

1、引入依赖的js

<script src="jquery-1.3.1.js" type="text/javascript"></script>
<script src="jquery.form.js" type="text/javascript"></script>

2、编写页面

<form id="myForm" action="ajax2.jsp" method="post">
    名称： <input type="text" name="name" /> <br /> 
    地址： <input type="text" name="address" /><br /> 
    自我介绍： <textarea name="comment"></textarea><br /> 
    <input type="submit" id="test" value="提交" /> <br />
    <div id="output1"></div>
</form>

3、调用方法

<script type="text/javascript">
    $(function() {
        var options = {
            target:        '#output1',   // 用服务器返回的数据 更新 id为output1的内容.
            beforeSubmit:  showRequest,  // 提交前
            success:       showResponse,  // 提交后 
            //另外的一些属性: 
            //url:       url         // 默认是form的action，如果写的话，会覆盖from的action. 
            //type:      type        // 默认是form的method，如果写的话，会覆盖from的method.('get' or 'post').
            //dataType:  null        // 'xml', 'script', or 'json' (接受服务端返回的类型.) 
            //clearForm: true        // 成功提交后，清除所有的表单元素的值.
            resetForm: true        // 成功提交后，重置所有的表单元素的值.
            //由于某种原因,提交陷入无限等待之中,timeout参数就是用来限制请求的时间,
            //当请求大于3秒后，跳出请求. 
            //timeout:   3000 
        }; 
     
        //'ajaxForm' 方式的表单 .
        $('#myForm').ajaxForm(options);  
        //或者 'ajaxSubmit' 方式的提交.
        //$('#myForm').submit(function() { 
        //    $(this).ajaxSubmit(options); 
        //    return false; //来阻止浏览器提交.
        //}); 
    });

    // 提交前
    function showRequest(formData, jqForm, options) {
        // formdata是数组对象,在这里，我们使用$.param()方法把他转化为字符串.
        var queryString = $.param(formData); //组装数据，插件会自动提交数据
        alert(queryString); //类似 ： name=1&add=2  
        return true;
    }

    //  提交后
    function showResponse(responseText, statusText) {
        alert('状态: ' + statusText + '
 返回的内容是: 
' + responseText);
    }
</script>