jQuery Form Plugin

  • jQuery Form Plugin

  • 原文地址:http://jquery.malsup.com/form/
  • Getting Started
  • API
  • Options
  • Examples
  • Form Fields
  • FAQ
  • Download

概观

jQuery表单插件允许您轻松而不显眼地升级HTML表单以使用  AJAX 主要方法,  ajaxForm ajaxSubmit 从表单元素收集信息,以确定如何管理提交过程。这两种方法都支持多种选项,使您可以完全控制数据的提交方式。  用AJAX提交表单并没有比这更容易!

快速入门指南

1 添加一个表单到您的页面。 只是一个正常的形式,不需要特殊的标记:
Name: Comment:
2 包括jQuery和表单插件外部脚本文件和一个简短的脚本,以便在 DOM 准备就绪时初始化表单


    
    

    

...

而已!

提交此表单时,名称注释字段将被发布到comment.php如果服务器返回成功状态,则用户将看到“谢谢”消息。

表单插件API

表单插件API提供了几种方法,可以让您轻松管理表单数据和表单提交。
ajaxForm
通过添加所有必要的事件侦听器来准备要通过 AJAX 提交的表单它并 没有 提交表单。使用 ajaxForm 您的文档 ready 功能来准备您的表单提交AJAX。  ajaxForm 采取零或一个参数。单个参数可以是回调函数或   Options Object。
连锁:是的。

注意:您可以将任何标准$.ajax选项传递 给ajaxForm

例:

$('#myFormId').ajaxForm();
ajaxSubmit
立即通过AJAX提交表单。在最常见的用例中,这是为了响应用户单击表单上的提交按钮而调用的。  ajaxSubmit 采取零或一个参数。单个参数可以是回调函数或   Options Object。
连锁:是的。

注意:您可以将任何标准 $.ajaxoptions参数传递给ajaxSubmit

例:

// attach handler to form's submit event
$('#myFormId').submit(function() {
    // submit the form
    $(this).ajaxSubmit();
    // return false to prevent normal browser submit and page navigation
    return false;
});
formSerialize
将表单序列化为查询字符串。这个方法将返回一个字符串格式:可  name1=value1&name2=value2
连接:不,这个方法返回一个字符串。

例:

var queryString = $('#myFormId').formSerialize();

// the data could now be submitted using $.get, $.post, $.ajax, etc
$.post('myscript.php', queryString);
        
fieldSerialize
将字段元素序列化为查询字符串。当你只需要序列化表单的一部分时,这是很方便的。这个方法将返回一个字符串格式:可  name1=value1&name2=value2
连接:不,这个方法返回一个字符串。

例:

var queryString = $('#myFormId .specialFields').fieldSerialize();
fieldValue
返回数组中匹配集合中元素的值。从版本.91开始,这个方法 总是 返回一个数组。如果没有有效的值可以确定数组将是空的,否则将包含一个或多个值。
可链接:不,这个方法返回一个数组。

例:

// get the value of the password input
var value = $('#myFormId :password').fieldValue();
alert('The password is: ' + value[0]);
resetForm
通过调用表单元素的本地 DOM 方法将表单重置为其原始状态 
连锁:是的。

例:

$('#myFormId').resetForm();
clearForm
清除表单元素。此方法清空所有文本输入,密码输入和textarea元素,清除所有选择元素中的选择,并取消选中所有广播和复选框输入。
连锁:是的。
$('#myFormId').clearForm();
clearFields
清除字段元素。当你只需要清除表格的一部分时,这很方便。
连锁:是的。
$('#myFormId .specialFields').clearFields();

ajaxForm and ajaxSubmit Options

注意:除了下面列出的选项,您还可以将任何标准选项传递 给ajaxForm和ajaxSubmit。 $.ajax

双方 ajaxForm ajaxSubmit 支持可使用一个可选参数对象提供多种选择。Options对象只是一个JavaScript对象,它包含的属性值设置如下:
beforeSerialize
在表单序列化之前调用的回调函数。这提供了在检索值之前操纵表单的机会。 beforeSerialize 函数有两个参数调用:表单的jQuery对象和传递给ajaxForm / ajaxSubmit的Options对象。
beforeSerialize: function($form, options) {
    // return false to cancel submit		         
}
默认值:  null
beforeSubmit
在提交表单之前调用回调函数。'beforeSubmit'回调可以作为运行预提交逻辑或验证表单数据的钩子来提供。如果'beforeSubmit'回调返回false,那么表单将不会被提交。'beforeSubmit'回调用三个参数调用:数组格式的表单数据,表单的jQuery对象以及传递给ajaxForm / ajaxSubmit的Options对象。
beforeSubmit: function(arr, $form, options) {
    // The array of form data takes the following form:
    // [ { name: 'username', value: 'jresig' }, { name: 'password', value: 'secret' } ]
    
    // return false to cancel submit		         
}
默认值:  null
clearForm
布尔标志,指示如果提交成功,表单是否应该被清除
默认值: null
数据
包含应与表单一起提交的额外数据的对象。
data: { key1: 'value1', key2: 'value2' }
数据类型
预期的响应数据类型。其中之一:null,“xml”,“script”或“json”。 dataType 选项提供了指定如何处理服务器响应的方法。这直接映射到 jQuery.httpData 方法。支持以下值:

'xml':如果dataType =='xml'服务器响应被视为XML并且'success'回调方法(如果指定)将被传递responseXML值

'json':如果dataType =='json'服务器响应将被评估并传递给'成功'回调,如果指定

'脚本':如果dataType =='脚本'在全局上下文中评估服务器响应

默认值: null

错误
回调函数在错误时被调用。
FORCESYNC
布尔值。设置为true以在上传文件(或使用iframe选项)时发布表单之前删除短暂延迟。延迟用于允许浏览器在执行本地表单提交之前呈现DOM更新。当向用户显示通知时,这提高了可用性,例如“请稍候...” 
默认值: false
在v2.38中添加
IFRAME
布尔标志,指示表单是否应始终将服务器对iframe的响应作为目标。这与文件上传相结合是很有用的。请参阅代码示例 页面 上的 文件上载 文档以获取更多信息。 默认值:
false
iframeSrc
当/ if iframe被使用时,应该用于iframe的src属性的字符串值。 
默认值: about:blank
使用 https 协议的页面的默认值 javascript:false
iframeTarget
标识要用作文件上载的响应目标的iframe元素。默认情况下,插件会在上传文件时创建一个临时的iframe元素来捕获响应。如果您愿意,这个选项允许您使用现有的iframe。使用此选项时,插件将不会尝试处理来自服务器的响应。
默认值: null
在v2.76中添加
replaceTarget
可以随 target 选项一起使用设置为 true 如果目标应该被替换或者 false 只有目标 内容 应该被替换。
默认值: false
在v2.43中添加
重置表格
布尔标志,指示如果提交成功,表单是否应该被重置
默认值: null
语义
布尔标志,指示数据是否必须以严格的语义顺序(较慢)提交。请注意,正常形式的序列化是按照语义顺序进行的,除了输入元素 type="image" 如果服务器有严格的语义要求, 并且 表单包含输入元素,则只应将语义选项设置为true  type="image"
默认值: false
成功
表单提交后调用的回调函数。如果提供“成功”回调函数,则在从服务器返回响应之后调用它。它通过了以下论点:
  1. 1.)responseText或responseXML值(取决于dataType选项的值)。
  2. 2.)statusText
  3. 3.)xhr(或者jQuery包装的表单元素,如果使用jQuery <1.4)
  4. 4.)jQuery包装的表单元素(如果使用jQuery <1.4,则为undefined)

默认值: null

目标
标识要使用服务器响应更新的页面中的元素。该值可以被指定为jQuery选择字符串,jQuery对象或DOM元素。
默认值: null
类型
表单数据应该提交的方法,'GET'或'POST'。
默认值:表单 method 属性的(如果没有找到,则为“GET”)
上传进度
用上传进度信息调用回调函数(如果浏览器支持的话)。回调传递了以下参数:
  1. 1)事件; 浏览器事件
  2. 2)位置(整数)
  3. 3.)总数(整数)
  4. 4.)percentComplete(整数)

默认值: null

网址
表单数据将被提交到的URL。
默认值:表单 action 属性的 

例:

// prepare Options Object
var options = {
    target:     '#divToUpdate',
    url:        'comment.php',
    success:    function() {
        alert('Thanks for your comment!');
    }
};

// pass options to ajaxForm
$('#myForm').ajaxForm(options);

请注意,选项对象也可以用来传递值给jQuery的 $.ajax方法。如果您熟悉您所支持的选项,则$.ajax 可以在传递给ajaxForm和 的选项对象中使用它们ajaxSubmit

代码示例

  • 给ajaxForm
  • ajaxSubmit会
  • 验证
  • JSON
  • XML
  • HTML
  • 文件上传

以下代码控制它下面的HTML表单。它用来ajaxForm 绑定表单并演示如何使用提交前和提交后的回调。

// prepare the form when the DOM is ready
$(document).ready(function() {
    var options = {
        target:        '#output1',   // target element(s) to be updated with server response
        beforeSubmit:  showRequest,  // pre-submit callback
        success:       showResponse  // post-submit callback

        // other available options:
        //url:       url         // override for form's 'action' attribute
        //type:      type        // 'get' or 'post', override for form's 'method' attribute
        //dataType:  null        // 'xml', 'script', or 'json' (expected server response type)
        //clearForm: true        // clear all form fields after successful submit
        //resetForm: true        // reset the form after successful submit

        // $.ajax options can be used here too, for example:
        //timeout:   3000
    };

    // bind form using 'ajaxForm'
    $('#myForm1').ajaxForm(options);
});

// pre-submit callback
function showRequest(formData, jqForm, options) {
    // formData is an array; here we use $.param to convert it to a string to display it
    // but the form plugin does this for you automatically when it submits the data
    var queryString = $.param(formData);

    // jqForm is a jQuery object encapsulating the form element.  To access the
    // DOM element for the form do this:
    // var formElement = jqForm[0];

    alert('About to submit: \n\n' + queryString);

    // here we could return false to prevent the form from being submitted;
    // returning anything other than false will allow the form submit to continue
    return true;
}

// post-submit callback
function showResponse(responseText, statusText, xhr, $form)  {
    // for normal html responses, the first argument to the success callback
    // is the XMLHttpRequest object's responseText property

    // if the ajaxForm method was passed an Options Object with the dataType
    // property set to 'xml' then the first argument to the success callback
    // is the XMLHttpRequest object's responseXML property

    // if the ajaxForm method was passed an Options Object with the dataType
    // property set to 'json' then the first argument to the success callback
    // is the json data object returned by the server

    alert('status: ' + statusText + '\n\nresponseText: \n' + responseText +
        '\n\nThe output div should have already been updated with the responseText.');
}
名称:
密码:
多: 一 二三 四五 六
单: 一二 三
Single2: 一个乙 C dË F
检查:   
无线电:   
文本:
          提交5

输出Div(#输出1):

AJAX响应将取代这个内容。

以下代码控制它下面的HTML表单。ajaxSubmit 用来提交表单。

// prepare the form when the DOM is ready
$(document).ready(function() {
    var options = {
        target:        '#output2',   // target element(s) to be updated with server response
        beforeSubmit:  showRequest,  // pre-submit callback
        success:       showResponse  // post-submit callback

        // other available options:
        //url:       url         // override for form's 'action' attribute
        //type:      type        // 'get' or 'post', override for form's 'method' attribute
        //dataType:  null        // 'xml', 'script', or 'json' (expected server response type)
        //clearForm: true        // clear all form fields after successful submit
        //resetForm: true        // reset the form after successful submit

        // $.ajax options can be used here too, for example:
        //timeout:   3000
    };

    // bind to the form's submit event
    $('#myForm2').submit(function() {
        // inside event callbacks 'this' is the DOM element so we first
        // wrap it in a jQuery object and then invoke ajaxSubmit
        $(this).ajaxSubmit(options);

        // !!! Important !!!
        // always return false to prevent standard browser submit and page navigation
        return false;
    });
});

// pre-submit callback
function showRequest(formData, jqForm, options) {
    // formData is an array; here we use $.param to convert it to a string to display it
    // but the form plugin does this for you automatically when it submits the data
    var queryString = $.param(formData);

    // jqForm is a jQuery object encapsulating the form element.  To access the
    // DOM element for the form do this:
    // var formElement = jqForm[0];

    alert('About to submit: \n\n' + queryString);

    // here we could return false to prevent the form from being submitted;
    // returning anything other than false will allow the form submit to continue
    return true;
}

// post-submit callback
function showResponse(responseText, statusText, xhr, $form)  {
    // for normal html responses, the first argument to the success callback
    // is the XMLHttpRequest object's responseText property

    // if the ajaxSubmit method was passed an Options Object with the dataType
    // property set to 'xml' then the first argument to the success callback
    // is the XMLHttpRequest object's responseXML property

    // if the ajaxSubmit method was passed an Options Object with the dataType
    // property set to 'json' then the first argument to the success callback
    // is the json data object returned by the server

    alert('status: ' + statusText + '\n\nresponseText: \n' + responseText +
        '\n\nThe output div should have already been updated with the responseText.');
}
名称:
密码:
多: 一二三四五六
单: 一二三
Single2: 一个乙CdËF
检查:   
无线电:   
文本:
   

输出Div(#输出2):

AJAX响应将取代这个内容。

这个页面给出了几个例子,说明表单数据在发送到服务器之前如何验证。秘密在beforeSubmit选择。如果这个预先提交的回调返回false,则提交进程被中止。

以下登录表单用于以下每个示例。每个示例都将验证用户填写用户名密码字段。

表格标记:

Username: Password:

首先,我们初始化表单并给它一个beforeSubmit 回调函数 - 这是验证函数。

// prepare the form when the DOM is ready
$(document).ready(function() {
    // bind form using ajaxForm
    $('#myForm2').ajaxForm( { beforeSubmit: validate } );
});

使用formData参数进行验证

用户名:   密码:   
function validate(formData, jqForm, options) {
    // formData is an array of objects representing the name and value of each field
    // that will be sent to the server;  it takes the following form:
    //
    // [
    //     { name:  username, value: valueOfUsernameInput },
    //     { name:  password, value: valueOfPasswordInput }
    // ]
    //
    // To validate, we can examine the contents of this array to see if the
    // username and password fields have values.  If either value evaluates
    // to false then we return false from this method.

    for (var i=0; i < formData.length; i++) {
        if (!formData[i].value) {
            alert('Please enter a value for both Username and Password');
            return false;
        }
    }
    alert('Both fields contain values.');
}

使用jqForm参数进行验证

用户名:   密码:   
function validate(formData, jqForm, options) {
    // jqForm is a jQuery object which wraps the form DOM element
    //
    // To validate, we can access the DOM elements directly and return true
    // only if the values of both the username and password fields evaluate
    // to true

    var form = jqForm[0];
    if (!form.username.value || !form.password.value) {
        alert('Please enter a value for both Username and Password');
        return false;
    }
    alert('Both fields contain values.');
}

使用fieldValue方法验证

用户名:   密码:   
function validate(formData, jqForm, options) {
    // fieldValue is a Form Plugin method that can be invoked to find the
    // current value of a field
    //
    // To validate, we can capture the values of both the username and password
    // fields and return true only if both evaluate to true

    var usernameValue = $('input[name=username]').fieldValue();
    var passwordValue = $('input[name=password]').fieldValue();

    // usernameValue and passwordValue are arrays but we can do simple
    // "not" tests to see if the arrays are empty
    if (!usernameValue[0] || !passwordValue[0]) {
        alert('Please enter a value for both Username and Password');
        return false;
    }
    alert('Both fields contain values.');
}

注意

您可以在 jQuery插件页面 上找到专门处理字段验证的jQuery插件

此页面显示如何处理从服务器返回的JSON数据。

下面的表单向服务器提交消息,服务器以JSON格式回显消息。 
表格标记:

Message:

信息:   

服务器代码在  json-echo.php
JavaScript的:
// prepare the form when the DOM is ready
$(document).ready(function() {
    // bind form using ajaxForm
    $('#jsonForm').ajaxForm({
        // dataType identifies the expected content type of the server response
        dataType:  'json',

        // success identifies the function to invoke when the server response
        // has been received
        success:   processJson
    });
});
回调函数
function processJson(data) {
    // 'data' is the json object returned from the server
    alert(data.message);
}

此页面显示如何处理从服务器返回的XML数据。

下面的表格向服务器提交消息,服务器以XML格式回显消息。 
表格标记:

Message:

信息:   

服务器代码在  xml-echo.php
' . $_POST['message'] . '';
?>
JavaScript的:
// prepare the form when the DOM is ready
$(document).ready(function() {
    // bind form using ajaxForm
    $('#xmlForm').ajaxForm({
        // dataType identifies the expected content type of the server response
        dataType:  'xml',

        // success identifies the function to invoke when the server response
        // has been received
        success:   processXml
    });
});
回调函数
function processXml(responseXML) {
    // 'responseXML' is the XML document returned by the server; we use
    // jQuery to extract the content of the message node from the XML doc
    var message = $('message', responseXML).text();
    alert(message);
}

此页面显示如何处理从服务器返回的HTML数据。

下面的表单向服务器提交消息,服务器在HTML div中回显。响应添加到htmlExampleTarget下面div中的这个页面。 
表格标记:

Message:

信息:   

服务器代码在  html-echo.php
' . $_POST['message'] . '
'; ?> JavaScript的:
// prepare the form when the DOM is ready
$(document).ready(function() {
    // bind form using ajaxForm
    $('#htmlForm').ajaxForm({
        // target identifies the element(s) to update with the server response
        target: '#htmlExampleTarget',

        // success identifies the function to invoke when the server response
        // has been received; here we apply a fade-in effect to the new content
        success: function() {
            $('#htmlExampleTarget').fadeIn('slow');
        }
    });
});

htmlExampleTarget(输出将在下面添加):

这个页面演示了表单插件的文件上传功能。没有特殊的编码需要处理文件上传。文件输入元素会自动检测并为您处理。

支持XMLHttpRequest Level 2的浏览器 将能够无缝地上传文件,甚至可以在上传过程中获得进度更新。对于较老的浏览器,使用涉及iframe的回退技术,因为不可能使用XMLHttpRequest对象的1级实施上传文件。这是一种常见的回退技术,但它有固有的局限性。iframe元素被用作表单提交操作的目标,这意味着服务器响应被写入iframe。如果响应类型是HTML或XML,那么这很好,但如果响应类型是脚本或JSON,那么这两个函数通常都不包含需要在HTML标记中使用实体引用来重复使用的字符。

为了解决使用iframe模式时脚本和JSON响应的挑战,表单插件允许将这些响应嵌入到textarea元素中,建议您在与文件上传和较旧的浏览器结合使用时对这些响应类型执行此操作。

需要注意的是,即使dataType选项设置为'script',并且服务器实际上是用一些javascript对多部分表单提交作出响应,应该强制响应的Content-Type标题text/html,否则Internet Explorer将提示用户下载一个“文件”。

另外请注意,如果表单中没有文件输入,那么请求使用普通的XHR来提交表单(而不是iframe)。这会让你的服务器代码的负担知道什么时候使用textarea,什么时候不使用textarea。如果你喜欢,你可以使用iframe 插件选项强制它总是使用iframe模式,然后你的服务器总是可以将响应嵌入到textarea中。但推荐的解决方案是测试“X-Requested-With”请求头。如果这个头的值是'XMLHttpRequest',那么你知道表单是通过ajax发布的。以下PHP片段显示了如何确保成功返回内容:

';
?>

// main content of response here
				
';
?>

下面的表单提供了一个类型为“file”的输入元素以及一个select元素来指定响应的dataType。提交的表单 files.php使用dataType来确定返回的响应类型。

文件:   返回类型:  HTML JSON脚本 XML   

输出:

显示如何显示上传进度的示例:

  • 进度演示1
  • 进度演示2
  • 进度演示3

与领域一起使用

本页面描述并演示了表单插件 fieldValue 和  fieldSerialize 方法。

fieldValue方法

fieldValue  允许您检索字段的当前值。例如,要在ID为“myForm”的表单中检索密码字段的值,可以这样写:
var pwd = $('#myForm :password').fieldValue()[0];
这个方法 总是 返回一个数组。如果没有有效的值可以确定数组将是空的,否则将包含一个或多个值。

fieldSerialize这个

fieldSerialize 允许您将表单的子集序列化为查询字符串。当您只需要处理某些字段时,这非常有用。例如,要仅序列化表单的文本输入,您可以编写:
var queryString = $('#myForm :text').fieldSerialize();
示范

在下面的文本框中输入一个jQuery表达式,然后点击'Test'查看fieldValuefieldSerialize 方法的结果这些方法是针对下面的测试表单运行的。

jQuery表达式:  (即:textarea,[@ type ='hidden'],:radio,:复选框等) 
只有成功的控制[1]


测试表格

name =“Hidden” value =“secret”/>  
name =“Name” type =“text”value =“MyName1”/>
name =“Password” type =“password”/>
name =“Multiple” multiple =“multiple”> 一二 三
name =“Single” > 一二 三
name =“Check” value =“1”/>
name =“Check” value =“2”/>
name =“Check” value =“3”/>
name =“Check2” value =“4”/>
name =“Check2” value =“5”/>
name =“Check3” />
name =“Radio” value =“1”/>
name =“Radio” value =“2”/>
name =“Radio” value =“3”/>
name =“Radio2” value =“4”/>
name =“Radio2” value =“5”/>
name =“Text” rows =“2”cols =“20”>
name =“resetButton” value =“Reset”/>
name =“sub” value =“Submit”/>

[1] http://www.w3.org/TR/html4/interact/forms.html#successful-controls

默认情况下,fieldValuefieldSerialize在“成功控制”的唯一功能。这意味着如果您在未选中的复选框上运行以下代码,结果将是一个空数组。

// value will be an empty array if checkbox is not checked:
var value = $('#myUncheckedCheckbox').fieldValue();
// value.length == 0
但是,如果您确实想知道复选框元素的“值”,即使未选中,您也可以这样写:
// value will hold the checkbox value even if it's not checked:
var value = $('#myUncheckedCheckbox').fieldValue(false);
// value.length == 1

经常问的问题

什么版本的jQuery是与表格插件兼容?
表单插件与jQuery v1.5及更高版本兼容。
表单插件是否有其他插件的依赖?
没有。
表单插件是否快速?它准确地序列化表单吗?
是! 查看我们的 比较页面 ,了解Form Plugin与其他库(包括Prototype和dojo)的比较。
什么是便捷的方式来使用表格插件?
ajaxForm 提供了最简单的方法来使您的HTML表单使用AJAX。这是准备表格的一站式购物方法。
ajaxForm 之间有什么区别 ajaxSubmit
这些方法有两个主要区别:
  1. ajaxSubmit提交表格,ajaxForm不。当您ajaxSubmit 立即调用它时,会将表单数据序列化并将其发送到服务器。当你调用ajaxForm它时,将必要的事件监听器添加到表单中,以便它可以检测用户提交表单的时间。当发生这种情况ajaxSubmit是为你而调用的。
  2. 当使用ajaxForm提交的数据时,将包括提交元素的名称和值(或者如果提交元素是图像,则其点击坐标)。
我怎样才能取消表单提交?
您可以通过添加“beforeSubmit”回调函数并从该函数返回false来阻止提交表单。有关示例,请参见代码示例页面。
是否有一个单元测试套件的表格插件?
是! 表单插件有一套广泛的测试用来验证其功能。  运行单元测试。
表单插件是否支持文件上传?
是!
为什么不是我所有的输入值都发布了?
jQuery表单序列化与HTML规范密切相关。只有  成功的控件  才能提交。
如何显示上传进度信息?
演示

下载

官方表单插件可以在这里找到:jquery.form.js或从插件的Github仓库

缩小版本: jquery.form.min.js

jQuery插件页面 提供了 许多其他有用的表单插件。 

支持

通过 jQuery Google组 可以获得对插件的支持 这是许多jQuery开发人员和用户订阅的一个非常活跃的组织。

贡献者

Form Plugin的开发是一个社区的努力,许多人提供了想法和代码。下面的人有这样或那样的贡献:

  • 约翰Resig
  • 迈克·阿尔苏普
  • 马克警员
  • 克劳斯·哈特尔
  • 马特·格林
  • 耶胡达·卡茨
  • JörnZaefferer
  • Sam Collett
  • Gilles van den Hoven
  • 凯文Glowacz
  • Alex Andrienko

如果我忘记了某人,请给我发电子邮件。



你可能感兴趣的:(jQuery,工具类)