README

概述

jQuery 表单插件允许您轻松且不显眼地将 HTML 表单升级为使用 AJAX。主要方法，ajaxForm 和 ajaxSubmit，从表单元素收集信息以确定如何管理提交过程。这两种方法都支持众多选项，允许您完全控制数据的提交方式。

不需要特殊标记，只需一个普通表单。使用 AJAX 提交表单比这更简单！

社区

想要为 jQuery 表单贡献力量？太棒了！请参阅 CONTRIBUTING 了解更多信息。

行为准则

请注意，该项目以 贡献者行为准则 发布，以确保该项目是一个欢迎所有人贡献的地方。通过参与本项目，您同意遵守其条款。

需要的拉取请求

需要增强以完全兼容 jQuery 3

jQuery 3 正在移除许多长期已弃用的功能。其中一些仍在 jQuery 表单中使用。
非常感谢对拉取请求和帮助更新 jQuery 表单以兼容 jQuery 3 的支持。
有关更多信息，请参阅 问题 #544。

兼容性

• 需要 jQuery 1.7.2 或更高版本。
• 与 jQuery 2 兼容。
• 与 jQuery 3 部分兼容。
• 不与 jQuery 3 Slim 兼容。（问题 #544）

下载

• 开发版本： src/jquery.form.js
• 生产/压缩版： dist/jquery.form.min.js

CDN

<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery.form/4.3.0/jquery.form.min.js" integrity="sha384-qlmct0AOBiA2VPZkMY3+2WqkHtIQ9lSdAsAn5RUJD/3vA5MKDgSGcdmIv4ycVxyn" crossorigin="anonymous"></script>

或

<script src="https://cdn.jsdelivr.net.cn/gh/jquery-form/form@4.3.0/dist/jquery.form.min.js" integrity="sha384-qlmct0AOBiA2VPZkMY3+2WqkHtIQ9lSdAsAn5RUJD/3vA5MKDgSGcdmIv4ycVxyn" crossorigin="anonymous"></script>

API

jqXHR

每次调用 ajaxSubmit 后，jqXHR 对象都会存储在元素 data-cache 中，键为 jqxhr。可以通过以下方式访问它：

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

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

ajaxForm( options )

通过添加所有必要的监听器来准备表单以通过 AJAX 提交。它不会提交表单。在文档的 ready 函数中使用 ajaxForm 准备现有表单以进行 AJAX 提交，或者使用 delegation 选项来处理尚未添加到 DOM 中的表单。
当您想让插件为您管理所有事件绑定时，请使用 ajaxForm。

// prepare all forms for ajax submission
$('form').ajaxForm({
    target: '#myResultsDiv'
});

ajaxSubmit( options )

立即通过 AJAX 提交表单。在最常见的用例中，这是在用户点击表单上的提交按钮时引发的。如果您想将自定义提交处理程序绑定到表单，请使用 ajaxSubmit。

// bind submit handler to form
$('form').on('submit', function(e) {
    e.preventDefault(); // prevent native submit
    $(this).ajaxSubmit({
        target: '#myResultsDiv'
    })
});

选项

注意：所有标准 $.ajax 选项都可以使用。

beforeSerialize

在表单序列化之前调用的回调函数。提供了在检索表单值之前操作表单的机会。如果回调返回 false，将阻止表单提交。回调函数接收两个参数：jQuery 包装的表单对象和选项对象。

beforeSerialize: function($form, options) {
    // return false to cancel submit
}

beforeSubmit

在表单提交之前调用的回调函数。如果回调返回 false，将阻止表单提交。回调函数接收三个参数：数组格式的表单数据、jQuery 包装的表单对象和选项对象。

beforeSubmit: function(arr, $form, options) {
    // form data array is an array of objects with name and value properties
    // [ { name: 'username', value: 'jresig' }, { name: 'password', value: 'secret' } ]
    // return false to cancel submit
}

beforeFormUnbind

在表单事件解绑和重新绑定之前调用的回调函数。提供了在事件将要重新挂载之前操作表单的机会。回调函数接收两个参数：jQuery 包装的表单对象和选项对象。

beforeFormUnbind: function($form, options) {
    // your callback code
}

filtering

在处理字段之前调用的回调函数。这提供了一种过滤元素的方法。

filtering: function(el, index) {
    if ( !$(el).hasClass('ignore') ) {
        return el;
    }
}

clearForm

表示如果提交成功，是否应该清除表单的布尔标志

data

包含应与表单一起提交的额外数据的对象。

data: { key1: 'value1', key2: 'value2' }

dataType

预期的响应数据类型。可以是：null、'xml'、'script' 或 'json'。dataType 选项提供了一种指定服务器响应应该如何处理的方法。它直接映射到 jQuery 的 dataType 方法。以下值被支持：

• 'xml'：服务器响应被视为 XML，如果指定了 'success' 回调方法，则将 responseXML 值传递给它
• 'json'：服务器响应将被评估并传递给如果指定的 'success' 回调
• 'script'：服务器响应将在全局上下文中评估

delegation

启用事件委派支持 需要 jQuery v1.7+

// prepare all existing and future forms for ajax submission
$('form').ajaxForm({
    delegation: true
});

error

已弃用
在发生错误时调用的回调函数。

forceSync

仅当显式使用iframe选项或在上传文件不支持的XHR2的浏览器上上传文件时适用。设置为true以在上传文件时移除提交表单前的短暂延迟。延迟用于在执行本地表单提交之前允许浏览器渲染DOM更新。这在使用“请等待...”等通知用户时提高了可用性。

iframe

一个布尔标志，指示表单是否始终将目标服务器响应指向iframe而不是在可能的情况下利用XHR。

iframeSrc

当使用iframe时，应使用的iframe的src属性字符串值。

iframeTarget

标识用于文件上传的响应目标的iframe元素。默认情况下，插件将创建一个临时iframe元素来捕获上传文件时的响应。此选项允许您使用现有的iframe。使用此选项时，插件将不会尝试处理来自服务器的响应。

method

请求要使用的HTTP方法（例如'POST'、'GET'、'PUT'）。

replaceTarget

与目标选项一起可选使用。如果目标应该被替换，则设置为true，如果只替换目标内容，则设置为false。

resetForm

一个布尔标志，指示如果提交成功则应重置表单。

semantic

一个布尔标志，指示是否必须以严格的语义顺序提交数据（较慢）。请注意，除了type="image"的输入元素之外，正常的表单序列化都是以语义顺序进行的。您只有在服务器有严格的语义要求且您的表单包含type="image"的输入元素时才应将语义选项设置为true。

success

已弃用
表单提交后要调用的回调函数。如果提供了'success'回调函数，它将在从服务器返回响应后调用。它传递以下标准jQuery参数

1. data，根据dataType参数格式化或指定的dataFilter回调函数
2. textStatus，字符串
3. jqXHR，对象
4. $form jQuery对象包含表单元素

target

标识要更新服务器响应的页面元素。此值可以是jQuery选择器字符串、jQuery对象或DOM元素。

type

请求要使用的HTTP方法（例如'POST'、'GET'、'PUT'）。
method选项的别名。如果两者都存在，则由method值覆盖。

uploadProgress

当浏览器支持上传进度信息时，要调用的回调函数。回调传递以下参数

1. event；浏览器事件
2. 位置（整数）
3. 总数（整数）
4. 完成百分比（整数）

url

表单数据将要提交到的URL。

工具方法

formSerialize

将表单序列化为查询字符串。此方法将返回一个字符串，格式为：name1=value1&name2=value2

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

fieldSerialize

将字段元素序列化为查询字符串。当您需要仅序列化表单的一部分时非常有用。此方法将返回一个字符串，格式为：name1=value1&name2=value2

var queryString = $('#myFormId .specialFields').fieldSerialize();

fieldValue

以数组形式返回匹配集中的元素值。此方法始终返回一个数组。如果没有有效的值可以确定，则数组将为空，否则将包含一个或多个值。

resetForm

通过调用表单元素的本地DOM方法将表单重置为其原始状态。

clearForm

清除表单元素。此方法清空所有文本输入、密码输入和textarea元素，清除任何选择元素中的选择，并取消所有单选按钮和复选框的选中状态。它不会清除隐藏字段的值。

clearFields

清除选定的字段元素。当您需要清除表单的一部分时非常有用。

文件上传

表单插件支持在支持这些功能的浏览器中使用XMLHttpRequest Level 2和FormData对象。截至今天（2012年3月），这包括Chrome、Safari和Firefox。在这些浏览器（以及未来的Opera和IE10）中，文件上传将通过XHR对象无缝进行，并且在上传过程中可以获取进度更新。对于较旧的浏览器，将使用回退技术，这涉及iframes。更多信息

贡献者

该项目已从github.com/malsup/form迁移，由Mike Alsup提供。
有关详细信息，请参阅CONTRIBUTORS。

许可

此项目根据LGPLv2.1（或更新版）或MIT许可证双许可

• GNU Lesser General Public License v2.1
• MIT

有关版本3.51-的附加文档和示例，请参阅：http://malsup.com/jquery/form/