URLSearchParams 对象

URLSearchParams 对象是浏览器的原生对象，用来构造、解析和处理 URL 的查询字符串（即 URL 问号后面的部分）。

它本身也是一个构造函数，可以生成实例。参数可以为查询字符串，起首的问号 ? 有没有都行，也可以是对应查询字符串的数组或对象。

// 方法一：传入字符串
var params = new URLSearchParams('?foo=1&bar=2');
// 等同于
var params = new URLSearchParams(document.location.search);

// 方法二：传入数组
var params = new URLSearchParams([['foo', 1], ['bar', 2]]);

// 方法三：传入对象
var params = new URLSearchParams({'foo' : 1 , 'bar' : 2});

URLSearchParams 会对查询字符串自动编码。

var params = new URLSearchParams({'foo': '你好'});
params.toString() // "foo=%E4%BD%A0%E5%A5%BD"

上面代码中， foo 的值是汉字， URLSearchParams 对其自动进行 URL 编码。

浏览器向服务器发送表单数据时，可以直接使用 URLSearchParams 实例作为表单数据。

const params = new URLSearchParams({foo: 1, bar: 2});
fetch('https://example.com/api', {
  method: 'POST',
  body: params
}).then(...)

上面代码中， fetch 命令向服务器发送命令时，可以直接使用 URLSearchParams 实例。

URLSearchParams 可以与 URL() 接口结合使用。

var url = new URL(window.location);
var foo = url.searchParams.get('foo') || 'somedefault';

上面代码中，URL 实例的 searchParams 属性就是一个 URLSearchParams 实例，所以可以使用 URLSearchParams 接口的 get 方法。

URLSearchParams 实例有遍历器接口，可以用 for...of 循环遍历（详见《ES6 标准入门》的《Iterator》一章）。

var params = new URLSearchParams({'foo': 1 , 'bar': 2});

for (var p of params) {
  console.log(p[0] + ': ' + p[1]);
}
// foo: 1
// bar: 2

URLSearchParams 没有实例属性，只有实例方法。

URLSearchParams.toString()

toString 方法返回实例的字符串形式。

var url = new URL('https://example.com?foo=1&bar=2');
var params = new URLSearchParams(url.search);

params.toString() // "foo=1&bar=2'

那么需要字符串的场合，会自动调用 toString 方法。

var params = new URLSearchParams({version: 2.0});
window.location.href = location.pathname + '?' + params;

上面代码中， location.href 赋值时，可以直接使用 params 对象。这时就会自动调用 toString 方法。

URLSearchParams.append()

append() 方法用来追加一个查询参数。它接受两个参数，第一个为键名，第二个为键值，没有返回值。

var params = new URLSearchParams({'foo': 1 , 'bar': 2});
params.append('baz', 3);
params.toString() // "foo=1&bar=2&baz=3"

append() 方法不会识别是否键名已经存在。

var params = new URLSearchParams({'foo': 1 , 'bar': 2});
params.append('foo', 3);
params.toString() // "foo=1&bar=2&foo=3"

上面代码中，查询字符串里面 foo 已经存在了，但是 append 依然会追加一个同名键。

URLSearchParams.delete()

delete() 方法用来删除指定的查询参数。它接受键名作为参数。

var params = new URLSearchParams({'foo': 1 , 'bar': 2});
params.delete('bar');
params.toString() // "foo=1"

URLSearchParams.has()

has() 方法返回一个布尔值，表示查询字符串是否包含指定的键名。

var params = new URLSearchParams({'foo': 1 , 'bar': 2});
params.has('bar') // true
params.has('baz') // false

URLSearchParams.set()

set() 方法用来设置查询字符串的键值。

它接受两个参数，第一个是键名，第二个是键值。如果是已经存在的键，键值会被改写，否则会被追加。

var params = new URLSearchParams('?foo=1');
params.set('foo', 2);
params.toString() // "foo=2"
params.set('bar', 3);
params.toString() // "foo=2&bar=3"

上面代码中， foo 是已经存在的键， bar 是还不存在的键。

如果有多个的同名键， set 会移除现存所有的键。

var params = new URLSearchParams('?foo=1&foo=2');
params.set('foo', 3);
params.toString() // "foo=3"

下面是一个替换当前 URL 的例子。

// URL: https://example.com?version=1.0
var params = new URLSearchParams(location.search.slice(1));
params.set('version', '2.0');

window.history.replaceState({}, '', location.pathname + `?` + params);
// URL: https://example.com?version=2.0

URLSearchParams.get()，URLSearchParams.getAll()

get() 方法用来读取查询字符串里面的指定键。它接受键名作为参数。

var params = new URLSearchParams('?foo=1');
params.get('foo') // "1"
params.get('bar') // null

两个地方需要注意。第一，它返回的是字符串，如果原始值是数值，需要转一下类型；第二，如果指定的键名不存在，返回值是 null 。

如果有多个的同名键， get 返回位置最前面的那个键值。

var params = new URLSearchParams('?foo=3&foo=2&foo=1');
params.get('foo') // "3"

上面代码中，查询字符串有三个 foo 键， get 方法返回最前面的键值 3 。

getAll() 方法返回一个数组，成员是指定键的所有键值。它接受键名作为参数。

var params = new URLSearchParams('?foo=1&foo=2');
params.getAll('foo') // ["1", "2"]

上面代码中，查询字符串有两个 foo 键， getAll 返回的数组就有两个成员。

URLSearchParams.sort()

sort() 方法对查询字符串里面的键进行排序，规则是按照 Unicode 码点从小到大排列。

该方法没有返回值，或者说返回值是 undefined 。

var params = new URLSearchParams('c=4&a=2&b=3&a=1');
params.sort();
params.toString() // "a=2&a=1&b=3&c=4"

上面代码中，如果有两个同名的键 a ，它们之间不会排序，而是保留原始的顺序。

URLSearchParams.keys()，URLSearchParams.values()，URLSearchParams.entries()

这三个方法都返回一个遍历器对象，供 for...of 循环遍历。它们的区别在于， keys 方法返回的是键名的遍历器， values 方法返回的是键值的遍历器， entries 返回的是键值对的遍历器。

var params = new URLSearchParams('a=1&b=2');

for(var p of params.keys()) {
  console.log(p);
}
// a
// b

for(var p of params.values()) {
  console.log(p);
}
// 1
// 2

for(var p of params.entries()) {
  console.log(p);
}
// ["a", "1"]
// ["b", "2"]

如果直接对 URLSearchParams 进行遍历，其实内部调用的就是 entries 接口。

for (var p of params) {}
// 等同于
for (var p of params.entries()) {}

返回JavaScript导航