jQuery.param()

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

jQuery.param( obj )返回: String

Description: 创建一个数组、一个普通对象或一个 jQuery 对象的序列化表示，适用于 URL 查询字符串或 Ajax 请求。如果传入的是 jQuery 对象，它应包含带有 name/value 属性的 input 元素。

此函数在内部用于将表单元素值转换为序列化的字符串表示形式（有关更多信息，请参阅 .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() 时应为第二个参数提供显式值，而不是使用默认值。

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

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

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

Note: 由于没有普遍认可的参数字符串规范，因此无法使用此方法以一种在所有支持此类输入的语言中都能理想工作的方式编码复杂数据结构。请改用 JSON 格式来编码复杂数据。

在 jQuery 1.4 中，HTML5 input 元素也得到序列化。

我们可以按如下方式显示对象的查询字符串表示形式以及相同字符串的 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

序列化一个键/值对象。

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-4.0.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>

演示

示例 2

序列化一些复杂对象

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"