jQuery Form

Posted 2020-09-21 lewo的博客

 

https://github.com/jquery-form/form#type

概念

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

不需要特殊的标记，只是一个正常的形式。 使用AJAX提交表单不会比这更容易！

社区

想要贡献jQuery表单？真棒！ 有关详细信息，请参阅贡献。

行为守则

请注意，这个项目是由“贡献者行为准则”发布的，以确保这个项目是每个人都欢迎的欢迎之地。 通过参与此项目，您同意遵守其条款。

要求

需要jQuery 1.7.2或更高版本。 兼容jQuery 2.x.x和3.x.x.

下载

• Development: src/jquery.form.js
• Production/Minified: dist/jquery.form.min.js

CDN

<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery.form/4.2.1/jquery.form.min.js" integrity="sha384-tIwI8+qJdZBtYYCKwRkjxBGQVZS3gGozr3CtI+5JF/oL1JmPEHzCEnIKbDbLTCer" crossorigin="anonymous"></script>

or

<script src="https://cdn.jsdelivr.net/jquery.form/4.2.1/jquery.form.min.js" integrity="sha384-tIwI8+qJdZBtYYCKwRkjxBGQVZS3gGozr3CtI+5JF/oL1JmPEHzCEnIKbDbLTCer" crossorigin="anonymous"></script>

API

jqXHR

每个ajaxSubmit调用后，jqXHR对象都存储在jqxhr键的元数据缓存中。 它可以像这样访问：

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

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

ajaxForm( options )

准备通过添加所有必要的事件监听器通过AJAX提交的表单。 它不提交表单。 在文档的ready函数中使用ajaxForm来准备AJAX提交的现有表单，或者使用委派选项来处理尚未添加到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‘
    })
});

Options

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

beforeSerialize

回调函数在形成序列化之前调用。 提供在检索其值之前操纵表单的机会。 从回调返回false将阻止提交表单。 使用两个参数调用回调：jQuery包装的表单对象和options对象。

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

beforeSubmit

回调函数在表单提交之前调用。 从回调返回false将阻止提交表单。 使用三个参数调用回调：数组格式的表单数据，jQuery包装的表单对象和options对象。

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
}

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‘: 如果指定，服务器响应将被评估并传递给“成功”回调
• ‘script‘: 在全局环境中评估服务器响应

delegation

真正的支持事件委托需要jQuery v1.7 +

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

error

回调函数在错误时被调用。

forceSync

仅适用于使用iframe选项的明示或在不支持XHR2的浏览器上上传文件时。 设置为true以在上传文件之前发布表单时删除短暂的延迟。 延迟用于允许浏览器在执行本机表单提交之前呈现DOM更新。 这样可以在向用户显示通知时提高可用性，例如“Please Wait ...”

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

回调函数在表单提交后被调用。 如果提供了一个“成功”回调函数，则在从服务器返回响应后调用它。 它传递以下标准jQuery参数：

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

target

标识要使用服务器响应进行更新的页面中的元素。 该值可以被指定为jQuery选择字符串，jQuery对象或DOM元素。

type

用于请求的HTTP方法（例如“POST”，“GET”，“PUT”）。
方法选项的别名。 如果两者都存在，则被方法值覆盖。

uploadProgress

通过上传进度信息调用回调函数（如果浏览器支持）。 回调传递以下参数：

1. event; 浏览器事件
2. position (integer)
3. total (integer)
4. percentComplete (integer)

url

提交表单数据的网址。

实用方法

formSerialize

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

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

fieldSerialize

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

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

fieldValue

返回数组中匹配集中的元素的值。 此方法总是返回一个数组。 如果无法确定有效值，则数组将为空，否则将包含一个或多个值。

resetForm

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

clearForm

清除表单元素。 此方法清除所有文本输入，密码输入和文本区域元素，清除任何选择元素中的选择，并取消选中所有收音机和复选框输入。 它不清除隐藏的字段值。

clearFields

清除所选的字段元素。 当您需要清除表单的一部分时，这很方便。

文件上传

Form Plugin支持在支持这些功能的浏览器上使用XMLHttpRequest Level 2和FormData对象。 截至今天（2012年3月），包括Chrome，Safari和Firefox。 在这些浏览器（以及将来的Opera和IE10）文件上传将通过XHR对象无缝地进行，并且随着上传的进行，进度更新可用。 对于旧版浏览器，使用后备技术，涉及iframe。 更多信息

贡献者

This project has transferred from github.com/malsup/form, courtesy of Mike Alsup.
See CONTRIBUTORS for details.

License

This project is dual licensed under the MIT and LGPLv3 licenses:

• MIT
• GNU Lesser General Public License v3.0

Additional documentation and examples for version 3.51- at: http://malsup.com/jquery/form/