Skip to content

URLSearchParams ​

URLSearchParams 表示地址里 ? 后面的那一串查询参数。它是一个有顺序的「名字 = 值」列表,同一个名字可以出现多次。它负责参数的编码和解码:写进去的是原文,读出来的也是原文,变成地址文本时才编码。

URLSearchParams 有两种来源:自己用 new 创建的,是一个独立的列表;从 URL 的 searchParams 读到的,和那个地址互相同步,改它就是改地址。fetch() 也接受它作请求体,发送的是 toString() 的结果。

继承关系:URLSearchParams 不继承任何类。

怎么改地址里的查询参数,见指南拼接和解析网址。

构造函数 ​

URLSearchParams()

从查询文本、对象、数组或另一个 URLSearchParams 创建一个列表。

实例属性 ​

属性说明
size 只读参数的个数,同名的分别计数

实例方法 ​

读:

方法说明
get()第一个同名参数的值
getAll()全部同名参数的值
has()有没有这个参数
toString()编码后的查询文本,不带 ?

改:

方法说明
append()在末尾加一个参数
set()把某个名字设成一个值,同名的只留一个
delete()删掉某个名字的参数
sort()按名字排序

遍历:

方法说明
keys()依次给出名字
values()依次给出值
entries()依次给出 [名字, 值]。for...of 直接遍历等于它
forEach()对每个参数调用一次回调

编码规则 ​

查询参数用表单的编码规则,和地址的路径部分不同:

  • 空格编码成 +。路径里的空格是 %20。
  • 中文等非 ASCII 字符按 UTF-8 编码成 %XX。
  • &、=、+ 这些在查询里有含义的字符被编码,不会破坏地址的结构。

'中 文' 写进去得到 %E4%B8%AD+%E6%96%87,读出来还是 '中 文'。

示例 ​

下面的代码改一个地址的查询参数。它不需要界面,直接写在 main.js 顶层就能运行。

js
const url = new URL('https://api.example.com/search?page=1');
url.searchParams.set('page', '2');
url.searchParams.append('q', '中 文');
console.log(url.href);

const params = new URLSearchParams('a=1&b=2&a=3');
console.log(params.getAll('a'), params.size);

结果

  • 输出 https://api.example.com/search?page=2&q=%E4%B8%AD+%E6%96%87。
  • 输出 ['1', '3'] 3。

这段代码没有作为一个整体在模拟器运行过。其中用到的每个 API 都在验收用例里运行过。

和 Web 的差别 ​

和 Web 相同。

参见 ​