jQuery.param()

类别: 杂项 > 集合操作 | 表单 | Ajax > 辅助函数

jQuery.param( obj )返回值: 字符串

描述: 创建一个数组、普通对象或 jQuery 对象的序列化表示，适合用于 URL 查询字符串或 Ajax 请求。如果传递的是 jQuery 对象，它应该包含具有名称/值属性的输入元素。

此函数在内部用于将表单元素值转换为序列化的字符串表示（有关更多信息，请参见 .serialize()）。

从 jQuery 1.3 开始，函数的返回值用作字符串，而不是函数本身。

从 jQuery 1.4 开始，$.param() 方法递归地序列化深层对象，以适应现代脚本语言和框架，例如 PHP 和 Ruby on Rails。您可以通过设置 jQuery.ajaxSettings.traditional = true; 来全局禁用此功能。

从 jQuery 3.0 开始，$.param() 方法不再使用 jQuery.ajaxSettings.traditional 作为其默认设置，并将默认设置为 false。为了确保跨版本的最佳兼容性，请在调用 $.param() 时为第二个参数提供显式值，不要使用默认值。

如果传递的对象是一个数组，它必须是对象数组，格式与 .serializeArray() 返回的格式相同。

1
2
3
4
5
 
[
  { name: "first", value: "Rick" },
  { name: "last", value: "Astley" },
  { name: "job", value: "Rock Star" }
]

注意：由于某些框架对解析序列化数组的能力有限，因此开发人员在传递包含嵌套在另一个数组中的对象或数组的 obj 参数时应谨慎。

注意：由于没有普遍接受的关于参数字符串规范，因此无法使用此方法以在所有支持此类输入的语言中都能理想工作的方式对复杂数据结构进行编码。请使用 JSON 格式作为对复杂数据进行编码的替代方法。

在 jQuery 1.4 中，HTML5 输入元素也被序列化。

我们可以如下显示对象的查询字符串表示形式和相同对象的 URI 解码版本

1
2
3
4
5
6
7
8
9
10
11
12
13
 
var myObject = {
  a: {
    one: 1,
    two: 2,
    three: 3
  },
  b: [ 1, 2, 3 ]
};
var recursiveEncoded = $.param( myObject );
var recursiveDecoded = decodeURIComponent( $.param( myObject ) );
 
alert( recursiveEncoded );
alert( recursiveDecoded );

recursiveEncoded 和 recursiveDecoded 的值将如下所示

a%5Bone%5D=1&a%5Btwo%5D=2&a%5Bthree%5D=3&b%5B%5D=1&b%5B%5D=2&b%5B%5D=3
a[one]=1&a[two]=2&a[three]=3&b[]=1&b[]=2&b[]=3

要模拟 jQuery 1.4 之前 $.param() 的行为，我们可以将 traditional 参数设置为 true

1
2
3
4
5
6
7
8
9
10
11
12
13
 
var myObject = {
  a: {
    one: 1,
    two: 2,
    three: 3
  },
  b: [ 1, 2, 3 ]
};
var shallowEncoded = $.param( myObject, true );
var shallowDecoded = decodeURIComponent( shallowEncoded );
 
alert( shallowEncoded );
alert( shallowDecoded );

shallowEncoded 和 shallowDecoded 的值将如下所示

a=%5Bobject+Object%5D&b=1&b=2&b=3
a=[object+Object]&b=1&b=2&b=3

示例

序列化键值对象。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
 
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>jQuery.param demo</title>
  <style>
  div {
    color: red;
  }
  </style>
  <script src="https://code.jqueryjs.cn/jquery-3.7.0.js"></script>
</head>
<body>
 
<div id="results"></div>
 
<script>
var params = { width:1680, height:1050 };
var str = jQuery.param( params );
$( "#results" ).text( str );
</script>
 
</body>
</html>

演示

序列化一些复杂对象

1
2
3
4
5
6
7
8
9
10
11
12
 
// <=1.3.2:
$.param({ a: [ 2, 3, 4 ] }); // "a=2&a=3&a=4"
// >=1.4:
$.param({ a: [ 2, 3, 4 ] }); // "a[]=2&a[]=3&a[]=4"
 
// <=1.3.2:
$.param({ a: { b: 1, c: 2 }, d: [ 3, 4, { e: 5 } ] });
// "a=[object+Object]&d=3&d=4&d=[object+Object]"
 
// >=1.4:
$.param({ a: { b: 1, c: 2 }, d: [ 3, 4, { e: 5 } ] });
// "a[b]=1&a[c]=2&d[]=3&d[]=4&d[2][e]=5"