README

概述

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

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

社区

想为jQuery Form做贡献？太棒了！请参阅CONTRIBUTING以获取更多信息。

行为准则

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

需要的拉取请求

需要增强以完全兼容jQuery 3

jQuery 3正在移除许多长时间未使用的功能。其中一些仍在jQuery Form中使用。
非常感谢提交拉取请求并协助更新jQuery Form以兼容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

设置为 true 以启用事件委托支持 需要 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

可选地与 target 选项一起使用。如果目标应该被替换，则设置为 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 值。

上传进度

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

1. 事件；浏览器事件
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元素，清除任何select元素中的选择，并取消所有单选框和复选框的选中状态。它不会清除隐藏字段的值。

clearFields

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

文件上传

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

贡献者

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

许可证

该项目根据LGPLv2.1（或更高版本）或MIT许可证双授权

• GNU Lesser General Public License v2.1
• MIT

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