URLSearchParams

注意：此功能在 Web Workers 中可用。

URLSearchParams 接口定义了用于处理 URL 查询字符串的实用程序方法。

URLSearchParams 对象是可迭代的，因此可以直接在 for...of 结构中使用它们来迭代键/值对，其顺序与它们在查询字符串中出现的顺序相同，例如，以下两行是等效的

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

尽管 URLSearchParams 在功能上类似于 Map，但在迭代时，它可能会遇到 Map 由于其实现方式而不会遇到的某些陷阱。

构造函数

URLSearchParams(): 返回一个 URLSearchParams 对象实例。

实例属性

size 只读: 指示搜索参数条目的总数。

实例方法

URLSearchParams[Symbol.iterator](): 返回一个 迭代器，允许以与它们在查询字符串中出现的顺序相同的顺序迭代此对象中包含的所有键/值对。
URLSearchParams.append(): 将指定的键/值对作为新的搜索参数追加。
URLSearchParams.delete(): 从所有搜索参数列表中删除与名称匹配的搜索参数，以及可选值。
URLSearchParams.entries(): 返回一个 迭代器，允许以与它们在查询字符串中出现的顺序相同的顺序迭代此对象中包含的所有键/值对。
URLSearchParams.forEach(): 允许通过回调函数迭代此对象中包含的所有值。
URLSearchParams.get(): 返回与给定搜索参数关联的第一个值。
URLSearchParams.getAll(): 返回与给定搜索参数关联的所有值。
URLSearchParams.has(): 返回一个布尔值，指示给定的参数或参数和值对是否存在。
URLSearchParams.keys(): 返回一个 迭代器，允许迭代此对象中包含的键/值对的所有键。
URLSearchParams.set(): 将与给定搜索参数关联的值设置为给定值。如果有多个值，则其他值将被删除。
URLSearchParams.sort(): 对所有键/值对（如果有）按其键进行排序。
URLSearchParams.toString(): 返回一个包含适合在 URL 中使用的查询字符串的字符串。
URLSearchParams.values(): 返回一个 迭代器，允许迭代此对象中包含的键/值对的所有值。

示例

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

// Iterating the search parameters
for (const p of searchParams) {
  console.log(p);
}

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

// Search parameters can also be an object
const paramsObj = { foo: "bar", baz: "bar" };
const searchParams = new URLSearchParams(paramsObj);

console.log(searchParams.toString()); // "foo=bar&baz=bar"
console.log(searchParams.has("foo")); // true
console.log(searchParams.get("foo")); // "bar"

重复搜索参数

const paramStr = "foo=bar&foo=baz";
const searchParams = new URLSearchParams(paramStr);

console.log(searchParams.toString()); // "foo=bar&foo=baz"
console.log(searchParams.has("foo")); // true
console.log(searchParams.get("foo")); // bar, only returns the first value
console.log(searchParams.getAll("foo")); // ["bar", "baz"]

无 URL 解析

URLSearchParams 构造函数不解析完整的 URL。但是，如果存在，它将从字符串的开头删除初始的前导 ?。

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

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

console.log(searchParams1.get("query")); // null
console.log(searchParams1.get("http://example.com/search?query")); // "@" (equivalent to decodeURIComponent('%40'))

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

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

保留加号

URLSearchParams 构造函数将加号 (+) 解释为空格，这可能会导致问题。在下面的示例中，我们使用十六进制转义序列来模拟包含二进制数据（其中每个字节都携带信息）的字符串，这些数据需要存储在 URL 搜索参数中。请注意，btoa() 生成的编码字符串包含 +，并且不会被 URLSearchParams 保留。

const rawData = "\x13à\x17@\x1F\x80";
const base64Data = btoa(rawData); // 'E+AXQB+A'

const searchParams = new URLSearchParams(`bin=${base64Data}`); // 'bin=E+AXQB+A'
const binQuery = searchParams.get("bin"); // 'E AXQB A', '+' is replaced by spaces

console.log(atob(binQuery) === rawData); // false

您可以使用 encodeURIComponent() 对数据进行编码来避免这种情况。

const rawData = "\x13à\x17@\x1F\x80";
const base64Data = btoa(rawData); // 'E+AXQB+A'
const encodedBase64Data = encodeURIComponent(base64Data); // 'E%2BAXQB%2BA'

const searchParams = new URLSearchParams(`bin=${encodedBase64Data}`); // 'bin=E%2BAXQB%2BA'
const binQuery = searchParams.get("bin"); // 'E+AXQB+A'

console.log(atob(binQuery) === rawData); // true

空值与无值

URLSearchParams 不区分 = 后没有任何内容的参数和根本没有 = 的参数。

const emptyVal = new URLSearchParams("foo=&bar=baz");
console.log(emptyVal.get("foo")); // returns ''
const noEquals = new URLSearchParams("foo&bar=baz");
console.log(noEquals.get("foo")); // also returns ''
console.log(noEquals.toString()); // 'foo=&bar=baz'

规范

规范
URL 标准 # urlsearchparams

浏览器兼容性

BCD 表格仅在启用了 JavaScript 的浏览器中加载。