大网数据广告活动
Web 标准与前端开发

URLSearchParams

· 52CE 我爱测

`URLSearchParams`** 接口定义了一些实用的方法来处理 URL 的查询字符串。

URL API

URLSearchParams 接口定义了一些实用的方法来处理 URL 的查询字符串。

一个实现了 URLSearchParams 的对象可以直接用在 Statements/for...of 结构中,以键/值对在查询字符串中出现的顺序对它们进行迭代,例如下面两行是等价的:

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

构造函数

  • URLSearchParams.URLSearchParams
    • : 返回一个 URLSearchParams 对象。

实例属性

  • URLSearchParams.size
    • : 返回 URLSearchParams 对象中查询参数的总个数。

实例方法

  • URLSearchParams[Symbol.iterator]()
    • : 返回一个 Iteration_protocols,允许以键/值对在查询字符串中出现的顺序迭代包含在该对象的键/值对。
  • URLSearchParams.append()
    • : 插入一个指定的键/值对作为新的查询参数。
  • URLSearchParams.delete()
    • : 从查询参数列表里删除指定的查询参数及其对应的值。
  • URLSearchParams.entries()
    • : 返回一个Iteration_protocols可以遍历所有键/值对的对象。
  • URLSearchParams.forEach()
    • : 通过回调函数迭代此对象中包含的所有值。
  • URLSearchParams.get()
    • : 获取指定查询参数的第一个值。
  • URLSearchParams.getAll()
    • : 获取指定查询参数的所有值,返回是一个数组。
  • URLSearchParams.has()
    • : 返回 Boolean 判断是否存在此查询参数。
  • URLSearchParams.keys()
    • : 返回Iteration_protocols 此对象包含了键/值对的所有键名。
  • URLSearchParams.set()
    • : 设置一个查询参数的新值,假如原来有多个值将删除其他所有的值。
  • URLSearchParams.sort()
    • : 按键名排序。
  • URLSearchParams.toString()
    • : 返回查询参数组成的字符串,可直接使用在 URL 上。
  • URLSearchParams.values()
    • : 返回Iteration_protocols 此对象包含了键/值对的所有值。

示例

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

// 迭代查询参数
for (let 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"
// 对象也可作为查询参数
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, 仅返回第一个值
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")); // "@"(等价于 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',“+”被替换为空格

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

空值 vs 无值

URLSearchParams 不区分 = 后面没有任何内容的参数和完全没有 = 的参数。

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

规范

浏览器兼容性

参见

来源:MDN Web Docs / Mozilla 贡献者 · 作者与贡献记录 · CC BY-SA 2.5。离线整理了版式、链接和媒体显示。

资料来源与适用范围

资料来源
MDN Web Docs / Mozilla 贡献者
适用范围
请按文中版本与环境说明核对
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-15
授权说明
CC BY-SA 2.5

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。