jQuery.param()

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

jQuery.param( obj )返回类型：String

描述：为数据、扁平对象或者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.jquery.com/jquery-1.10.2.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"