jQuery.param() 函数详解
原文:http://www.365mini.com/page/jquery_param.htm
jQuery.param()
函数用于将一个JS数组或纯粹的对象序列化为字符串值,以便用于URL查询字符串或AJAX请求。
如果传入的不是数组或"纯粹的对象",则返回空字符串("");如果传入的是null
、undefined
等无法访问属性的值,则直接报错。
所谓"纯粹的对象",就是通过{}
或new Object()
自行创建的对象。JS内置的Boolean、Number、String、Date、RegExp、Function、Window等类型的对象都不算是"纯粹的对象"。
返回的字符串已经过URL编码处理(采用的字符集为UTF-8)。
该函数属于全局的jQuery
对象。
语法
jQuery 1.2 新增该静态函数。
jQuery.param( obj [, traditional ] )
参数
参数 | 描述 |
---|---|
obj | String类型需要被序列化的JS对象。 |
traditional | Boolean类型指示是否执行一个传统的"浅层"序列化。 |
jQuery 1.4 新增支持:jQuery.param()
支持参数traditional
。
从jQuery 1.3开始,如果属性值是一个函数,则使用该函数的返回值来作为真正的值,而不是将函数当作一个字符串值。
从jQuery 1.4开始,jQuery.param()
将递归地序列化深层次的对象(数组始终不会递归处理),以适应诸如PHP、Ruby on Rails等现代脚本语言或框架的需要。参数traditional
的默认值等于全局设置jQuery.ajaxSettings.traditional
的值。因此,你可以通过如下全局设置禁用该功能:
jQuery.ajaxSettings.traditional = true;
从jQuery 1.8开始,jQuery.param()
不再使用jQuery.ajaxSettings.traditional
作为参数traditional
的默认值,而是采用默认值false
。为了最好的跨版本兼容性,请在调用该函数时,明确指定第二个参数traditional
,而不要使用默认值。
如果参数obj
是一个数组,那么它的每个元素都必须是一个包含name
属性和value
属性的对象(value属性可以没有,默认其值为undefined)。例如:
// 每个元素必须是包含name和value属性的对象(也可以有其他属性,但不会被处理)
// jQuery会将name属性值用作参数名,value属性值用做参数值。
[
{ name: "name", value: "CodePlayer" },
{ name: "age", value: 18 },
{ name: "job", value: "Developer", company: "家里蹲" }
]
由于某些框架解析序列化的数组的能力有限,当参数obj
是一个嵌套了其他数组或对象的数组时,开发人员应当尽量小心谨慎。
由于没有一个用于参数字符串的通用规范,使用该方法来编码一些复杂的数据结果可能无法在跨所有语言支持中理想地工作。在编码复杂的数据时,你可以选择使用JSON格式来作为替代。
返回值
jQuery.param()
函数的返回值为String类型,返回解析指定的数组或对象的编码字符串。
示例&说明
以下是与jQuery.param()
函数相关的jQuery示例代码,以演示jQuery.param()
函数的具体用法:运行代码(以下部分代码请自行复制到演示页面运行)
var v1 = $.param( true ); // ""
var v2 = $.param( 100 ); // ""
var v3 = $.param( 12.34 ); // ""
var v4 = $.param( "" ); // ""
var v5 = $.param( function(){ return 18; } ); // ""
var v6 = $.param( /\d+/ ); // ""
var v7 = $.param( new Date() ); // ""
var v8 = $.param( null ); // 报错
var v9 = $.param( undefined ); // 报错
// 字符串将被看作一个字符数组
var v10 = $.param( "name" ); // "0=n&1=a&2=m&3=e"
var v11 = $.param( { name:"CodePlayer", age:18 } ); // "name=CodePlayer&age=18"
var array = [
{ name: "name", value: "张三" },
{ name: "age", value: 18, extra: "忽略该属性" },
{ name: "grade" }, // 没有value属性,则value值为undefined,将被转为空字符串""
{ name: "orderId", value: 2 },
{ name: "orderId", value: 3 },