URLSearchParams - 定义了操作 URL 查询字符串的实用方法

URLSearchParams 接口定义了操作 URL 查询字符串的实用方法。

可以在 for...of 结构中直接使用实现 URLSearchParams 的对象，例如，以下两行是等效的：

for (const [key, value] of mySearchParams) {}
for (const [key, value] of mySearchParams.entries()) {}

构造函数

URLSearchParams()

返回一个 URLSearchParams 对象实例。

方法

URLSearchParams.append()

将指定的键 / 值对附加为新的搜索参数。

URLSearchParams.delete()

从所有搜索参数的列表中删除给定的搜索参数及其关联的值。

URLSearchParams.entries()

返回一个 iterator，允许迭代此对象中包含的所有键 / 值对。

URLSearchParams.forEach()

允许通过回调函数遍历此对象中包含的所有值。

URLSearchParams.get()

返回与给定搜索参数关联的第一个值。

URLSearchParams.getAll()

返回与给定搜索参数关联的所有值。

URLSearchParams.has()

返回一个 Boolean，指示是否存在给定的参数。

URLSearchParams.keys()

返回一个 iterator，允许迭代此对象中包含的键 / 值对的所有键。

URLSearchParams.set()

将与给定搜索参数关联的值设置为给定值。如果有多个值，则删除其他值。

URLSearchParams.sort()

按所有键 / 值对的键对它们进行排序。

URLSearchParams.toString()

返回一个字符串，其中包含适合在 URL 中使用的查询字符串。

URLSearchParams.values()

返回一个 iterator，允许对该对象中包含的键 / 值对的所有值进行迭代。

实例

var paramsString = "q=URLUtils.searchParams&topic=api";
var searchParams = new URLSearchParams(paramsString);

// 迭代搜索参数。
for (let p of searchParams) {
  console.log(p);
}

searchParams.has("topic") === true; // true
searchParams.get("topic") === "api"; // true
searchParams.getAll("topic"); // ["api"]
searchParams.get("foo") === null; // true
searchParams.append("topic", "webdev");
searchParams.toString(); // "q=URLUtils.searchParams&topic=api&topic=webdev"
searchParams.set("topic", "More webdev");
searchParams.toString(); // "q=URLUtils.searchParams&topic=More+webdev"
searchParams.delete("topic");
searchParams.toString(); // "q=URLUtils.searchParams"

陷阱

URLSearchParams 构造函数不会解析完整的 URL。但是，它会将字符串开头 ? 去掉（如果存在的话）。

var paramsString1 = "http://example.com/search?query=%40";
var searchParams1 = new URLSearchParams(paramsString1);

searchParams1.has("query"); // false 
searchParams1.has("http://example.com/search?query"); // true

searchParams1.get("query"); // null
searchParams1.get("http://example.com/search?query"); // "@" (等于 decodeURIComponent('%40'))

var paramsString2 = "?query=value";
var searchParams2 = new URLSearchParams(paramsString2);
searchParams2.has("query"); // true 

var url = new URL("http://example.com/search?query=%40");
var searchParams3 = new URLSearchParams(url.search);
searchParams3.has("query") // true

规范

规范	状态	备注
URL URLSearchParams 的定义	现行的标准	初始定义。

桌面浏览器兼容性

移动浏览器兼容性

1. 在版本 57 之前，URL 中的单引号会被转义（请参见 bug 1386683）。

2. 仅隐式可用或从 URL 模块导入。

3. 仅支持将字符串作为 init 对象。

4. 从 URL 删除不存在的查询参数不会删除 ?。参见 bug 193022。

相关链接

• URL 接口。
• Google 开发者：使用 URLSearchParams 轻松进行 URL 操作