URLSearchParams

[TOC]

索引

方法：

new URLSearchParams()：(init?)，创建一个专门用于操作 URL 的查询参数的实例。
params.append()：(key, value)，用于向 URL 的查询参数中添加一个新的键值对，即使键已存在也不会覆盖原有值，而是追加新的值。
params.delete()：(key)，用于删除 URL 查询参数中指定键的所有值。
params.get()：(key)，用于从 URL 的查询参数中获取指定键的第一个值。
params.set()：(key,value)，用于设置指定键的查询参数值。若键已存在，则覆盖其所有值；若不存在，则添加新的键值对。
params.has()：(key)，用于检查 URL 的查询参数中是否存在指定键。
params.getAll()：(key)，用于从 URL 的查询参数中获取指定键的所有值（以数组形式返回）。
params.sort()：()，用于按键名对 URL 的查询参数进行排序，并原地修改参数列表。
params.toString()：()，用于将查询参数序列化为 URL 编码的字符串（即 ? 后的键值对部分）。
params.keys()：()，用于获取 URL 查询参数中所有键的迭代器。它允许你遍历查询字符串中的所有键名。
params.values()：()，用于获取 URL 查询参数中所有值的迭代器。它允许你遍历查询字符串中的所有参数值。
params.entries()：()，用于获取 URL 查询参数中所有键值对的迭代器。它允许遍历查询字符串中的所有参数，并以 [key, value] 数组形式返回每个键值对。
params.forEach()：(callback,thisArg?)，用于遍历 URL 查询参数中的所有键值对，并对每个键值对执行回调函数。

URLSearchParams

方法

new URLSearchParams()

new URLSearchParams()：(init?)，创建一个专门用于操作 URL 的查询参数的实例。

init?：string|array|object，可以是以下类型：
- 字符串：直接解析查询字符串（自动忽略前导的?）。
  js
```
new URLSearchParams("name=John&age=20")
```
  1
- 对象：键值对对象（非字符串值会自动转为字符串，重复键会被覆盖）。
  js
```
new URLSearchParams({ name: "John", age: 20 })
```
  1
- 二维数组：键值对数组（支持重复键）。
  js
```
new URLSearchParams([ ["name", "John"], ["lang", "en"] ])
```
  1
- 其他实例：复制另一个 URLSearchParams 实例的内容。
  js
```
const p1 = new URLSearchParams("a=1&b=2");
const p2 = new URLSearchParams(p1);
```
  1
  2
- 无参数：创建空实例。
返回：
params：URLSearchParams，返回一个专门用于操作 URL 的查询参数的实例。
- 常用方法：
- append()：(key,value)，添加参数（允许重复键）
- delete()：(key)，删除指定键的所有参数
- get()：(key)，返回第一个匹配键的值，无则返回 null）
- getAll()：(key)，返回指定键的所有值的数组（无则返回空数组）
- has()：(key)，检查是否存在指定键，返回 boolean
- set()：(key,value)，设置键的值（删除原有值，若键不存在则添加）
- sort()：()，按键名排序（原地修改）
- toString()：()，返回序列化的查询字符串（如 "name=John&age=20"）

特性：

自动编码/解码：URLSearchParams 自动处理特殊字符的编码和解码。

const params = new URLSearchParams();
params.append("q", "coffee & tea"); // 自动编码为 "coffee%20%26%20tea"
console.log(params.get("q"));       // 解码为 "coffee & tea"

链式操作：方法返回实例本身，支持链式调用。

const params = new URLSearchParams()
  .append("page", "1")
  .delete("filter")
  .sort();

遍历参数：支持迭代器方法遍历键值对

const params = new URLSearchParams("name=John&lang=en");
for (const [key, value] of params) {
  console.log(key, value); // 输出 "name John" 和 "lang en"
}

append()

params.append()：(key, value)，用于向 URL 的查询参数中添加一个新的键值对，即使键已存在也不会覆盖原有值，而是追加新的值。

key：string，要添加的参数的键。
value：string，要添加的参数的值。

特性：

追加键值对：无论键是否已存在，始终在查询参数中追加新的键值对。

const params = new URLSearchParams("tag=js");
params.append("tag", "css");
console.log(params.toString()); // "tag=js&tag=css"

自动类型转换：若 key 或 value 不是字符串，会调用其 toString() 方法转换：
js
```
params.append(123, true); // 转换为 key="123", value="true"
```
1

URL 编码：自动对特殊字符（如空格、&、?）进行编码：

params.append("query", "coffee & tea");
console.log(params.toString()); // "query=coffee%20%26%20tea"

示例：

基本用法：

const params = new URLSearchParams();
params.append("page", "1");
params.append("filter", "latest");
console.log(params.toString()); // "page=1&filter=latest"

重复键操作：

const params = new URLSearchParams();
params.append("color", "red");
params.append("color", "blue");
console.log(params.getAll("color")); // ["red", "blue"]
console.log(params.toString());      // "color=red&color=blue"

非字符串参数：

const params = new URLSearchParams();
params.append(123, 456); // 转换为 name="123", value="456"
params.append({}, []);    // 转换为 name="[object Object]", value=""
console.log(params.toString()); // "123=456&[object+Object]="

delete()

params.delete()：(key)，用于删除 URL 查询参数中指定键的所有值。

key：string，要删除的参数的键名。

特性：

删除所有同名键：无论指定键有多少个值，全部删除。

const params = new URLSearchParams("color=red&color=blue");
params.delete("color");
console.log(params.toString()); // ""（空字符串）

静默处理：若键不存在，不会抛出错误，也不会修改查询参数。

const params = new URLSearchParams("name=John");
params.delete("age"); // 无任何效果
console.log(params.toString()); // "name=John"

自动类型转换：非字符串参数会被隐式转换为字符串：

const params = new URLSearchParams("123=abc");
params.delete(123); // 转换为字符串 "123"，删除对应的键
console.log(params.toString()); // ""

编码处理：键名无需手动编码，URLSearchParams 会自动处理：

const params = new URLSearchParams("q=coffee%20&tea");
params.delete("q"); // 删除键名为 "q" 的参数
console.log(params.toString()); // ""

get()

params.get()：(key)，用于从 URL 的查询参数中获取指定键的第一个值。

key：string，要获取的参数的键名。
返回：
value：string|null，键存在的第一个值（若值无内容则返回空字符串 ""）。键不存在时返回 null。

特性：

获取第一个值：即使键有多个值，仅返回第一个（需获取全部值请使用 getAll()）。
js
```
const params = new URLSearchParams("color=red&color=blue");
console.log(params.get("color")); // "red"
```
1
2

自动解码：返回的值是 URL 解码后的字符串（如 %20 转为空格）。

const params = new URLSearchParams("q=hello%20world");
console.log(params.get("q")); // "hello world"

键名隐式转换：非字符串键名会被转换为字符串：

const params = new URLSearchParams("123=abc");
console.log(params.get(123)); // "abc"（键名转换为字符串 "123"）

键不存在或值为空：

键不存在时返回 null。
键存在但值为空时返回空字符串 ""。

const params1 = new URLSearchParams("name");
console.log(params1.get("name")); // ""（值为空）

const params2 = new URLSearchParams("age=20");
console.log(params2.get("country")); // null（键不存在）

示例：

基本用法：

const params = new URLSearchParams("page=1&filter=latest");
console.log(params.get("page"));    // "1"
console.log(params.get("filter")); // "latest"
console.log(params.get("sort"));   // null

处理多值键：

const params = new URLSearchParams("tag=js&tag=css");
console.log(params.get("tag")); // "js"（仅返回第一个值）

空值与非字符串键：

const params = new URLSearchParams("empty=&id=123");
console.log(params.get("empty")); // ""
console.log(params.get({}));      // null（键名为 "[object Object]"）

set()

params.set()：(key,value)，用于设置指定键的查询参数值。若键已存在，则覆盖其所有值；若不存在，则添加新的键值对。

key：string，要设置的参数的键。
value：string，要设置的参数的值。
特性：
1. 覆盖所有同名键：若键已存在，删除其所有值，仅保留新值；若键不存在，则直接添加。
  js
```
const params = new URLSearchParams("color=red&color=blue");
params.set("color", "green");
console.log(params.toString()); // "color=green"
```
  1
  2
  3
2. 自动编码：自动对键和值的特殊字符（如空格、&）进行 URL 编码：
  js
```
params.set("query", "coffee & tea"); // 转为 "query=coffee%20%26%20tea"
```
  1
3. 避免二次编码：若值已手动编码，会被二次编码导致错误：
  js
```
// ❌ 错误：手动编码后再调用 set()
params.set("q", encodeURIComponent("coffee & tea")); // q=coffee%2520%2526%2520tea
// ✅ 正确：直接传递原始值
params.set("q", "coffee & tea"); // q=coffee%20%26%20tea
```
  1
  2
  3
  4
4. 空值处理：值可以是空字符串，此时参数仍会被保留（值为空）：
  js
```
params.set("flag", "");
console.log(params.get("flag")); // ""
```
  1
  2
5. 隐式类型转换：非字符串的键或值会被转换为字符串：
  js
```
params.set(123, true); // 转换为 name="123", value="true"
```
  1
6. 对比 append()：
  方法行为示例（原参数：tag=js）
  set() 覆盖所有同名键的值 set("tag", "html") → tag=html
  append() 追加新值（保留原有值） append("tag", "css") → tag=js&tag=css

方法	行为	示例（原参数：`tag=js`）
`set()`	覆盖所有同名键的值	`set("tag", "html")` → `tag=html`
`append()`	追加新值（保留原有值）	`append("tag", "css")` → `tag=js&tag=css`

has()

params.has()：(key)，用于检查 URL 的查询参数中是否存在指定键。

key：string，要检查的参数的键名。
返回：
exists：boolean，若键存在（无论是否有值），返回 true；否则返回 false。

特性：

存在性检查：仅检查键是否存在，不关心值的内容（即使值为空字符串，仍返回 true）。

const params = new URLSearchParams("name=&age=20");
console.log(params.has("name")); // true（键存在，值为空）
console.log(params.has("age"));  // true
console.log(params.has("city")); // false

隐式类型转换：非字符串键名会被转换为字符串后进行匹配：

const params = new URLSearchParams("123=abc");
console.log(params.has(123)); // true（数字 123 转为字符串 "123"）
console.log(params.has({}));        // false（对象转为 "[object Object]"）

严格区分大小写：键名区分大小写且完全匹配（如 "Key" 和 "key" 视为不同键）：

const params = new URLSearchParams("Key=1&key=2");
console.log(params.has("Key")); // true
console.log(params.has("key")); // true（两者视为不同键）

编码处理：直接匹配原始键名字符串，不会自动解码 URL 编码的键名：

const params = new URLSearchParams("q%3D=hello"); // 键名为 "q%3D"
console.log(params.has("q="));  // false（需匹配编码后的键名）
console.log(params.has("q%3D")); // true

复杂键名：

const params = new URLSearchParams("flag=&test.key=value");
console.log(params.has("flag"));    // true（值为空）
console.log(params.has("test.key"));// true（键名含特殊字符）

getAll()

params.getAll()：(key)，用于从 URL 的查询参数中获取指定键的所有值（以数组形式返回）。

key：string，要获取的参数的键名。
返回：
values：[]，键存在返回匹配的所有值数组。键不存在返回[]。

特性：

获取所有值：返回指定键的所有值的数组（即使键只有一个值）。

const params = new URLSearchParams("color=red&color=blue");
console.log(params.getAll("color")); // ["red", "blue"]

自动解码：数组中的每个值均为 URL 解码后的字符串（如 %20 转为空格）。

const params = new URLSearchParams("q=hello%20world&q=test");
console.log(params.getAll("q")); // ["hello world", "test"]

键名隐式转换：非字符串键名会被转换为字符串后进行匹配：

const params = new URLSearchParams("123=abc&123=def");
console.log(params.getAll(123)); // ["abc", "def"]（键名转换为 "123"）

键不存在或值为空：

键不存在时返回空数组 []。
键存在但值为空时返回包含空字符串的数组 [""]。

const params1 = new URLSearchParams("name");
console.log(params1.getAll("name")); // [""]（值为空）

const params2 = new URLSearchParams("age=20");
console.log(params2.getAll("country")); // []（键不存在）

对比 get()：
方法返回值类型行为
get(name) string 或 null 返回第一个值（不存在时返回 null）
getAll(name) string[] 返回所有值（不存在时返回空数组）

方法	返回值类型	行为
`get(name)`	`string` 或 `null`	返回第一个值（不存在时返回 `null`）
`getAll(name)`	`string[]`	返回所有值（不存在时返回空数组）

示例：

获取多值参数的实际应用：

// 用户多选标签后生成 URL：?tags=js&tags=css&tags=html
const params = new URLSearchParams(window.location.search);
const selectedTags = params.getAll("tags"); // ["js", "css", "html"]
selectedTags.forEach(tag => applyFilter(tag));

与 append() 的配合：使用 append() 添加多值参数后，可用 getAll() 获取完整列表。

const params = new URLSearchParams();
params.append("lang", "en");
params.append("lang", "fr");
console.log(params.getAll("lang")); // ["en", "fr"]

sort()

params.sort()：()，用于按键名对 URL 的查询参数进行排序，并原地修改参数列表。

特性：

按键名排序：按键名的 Unicode 码点顺序升序排列（类似 Array.sort() 默认行为）。

const params = new URLSearchParams("b=2&a=1&c=3");
params.sort();
console.log(params.toString()); // "a=1&b=2&c=3"

原地修改：直接修改原 URLSearchParams 实例，而非返回新实例。

const params = new URLSearchParams("z=3&x=1&y=2");
params.sort();
console.log(params.toString()); // "x=1&y=2&z=3"（原实例被修改）

多值键处理：相同键的多个值保持原有顺序，仅按键名排序。

const params = new URLSearchParams("b=2&b=1&a=3");
params.sort();
console.log(params.toString()); // "a=3&b=2&b=1"

特殊字符排序：非字母数字的键名（如 _、%）按 Unicode 顺序参与排序。

const params = new URLSearchParams("_key=1&5star=2&%20=3");
params.sort();
console.log(params.toString()); // "%20=3&5star=2&_key=1"

注意：
1. 不可逆操作：排序后无法撤销，需提前备份原始数据（如有需要）：
  js
```
const original = new URLSearchParams("b=2&a=1");
const backup = new URLSearchParams(original);
original.sort();
```
  1
  2
  3
2. 与 URL 对象的结合使用：排序后需手动更新 URL 的 search 属性以反映变化：
  js
```
const url = new URL("https://example.com?b=2&a=1");
url.searchParams.sort();
console.log(url.href); // "https://example.com/?a=1&b=2"
```
  1
  2
  3
3. 性能影响：对大型参数列表排序可能影响性能，建议在必要时使用。
使用场景：
1. 规范化参数顺序：确保相同参数集生成的 URL 一致（如用于缓存、签名验证等）。
  js
```
const params = new URLSearchParams(window.location.search);
params.sort();
const canonicalURL = `${location.pathname}?${params}`;
```
  1
  2
  3
2. 提升可读性：按字母顺序排列参数，便于调试和日志记录。
3. API 请求要求：某些 API 要求参数按特定顺序排列（如 OAuth 签名）。

toString()

params.toString()：()，用于将查询参数序列化为 URL 编码的字符串（即 ? 后的键值对部分）。

返回：
queryString：string，返回 URL 编码的查询字符串（不含前导的 ?）。
特性：
1. 序列化规则：
  - 键值对按顺序拼接，格式为 key1=value1&key2=value2。
  - 键和值中的特殊字符（如空格、&、=）会进行 URL 编码（如空格 → %20）。
  - 值为空时保留键名（如 key=）。
  - 多值键会保留所有值（如 color=red&color=blue）。
2. 排序影响：若之前调用过 params.sort()，则键按排序后的顺序输出；否则保持添加顺序。
  js
```
const params = new URLSearchParams("b=2&a=1");
params.sort();
console.log(params.toString()); // "a=1&b=2"
```
  1
  2
  3
3. 编码处理：自动对键和值进行编码（无需手动调用 encodeURIComponent）：
  js
```
params.append("query", "coffee & tea");
console.log(params.toString()); // "query=coffee%20%26%20tea"
```
  1
  2
4. 与 URL 对象的结合：可直接将 toString() 结果赋值给 URL 的 search 属性：
  js
```
const url = new URL("https://example.com");
const params = new URLSearchParams({ page: "1" });
url.search = params.toString(); // URL 变为 "https://example.com?page=1"
```
  1
  2
  3
5. 空参数处理：无参数的 URLSearchParams 实例返回空字符串：
  js
```
const params = new URLSearchParams();
console.log(params.toString()); // ""
```
  1
  2

使用场景：

动态构建 URL：

const baseURL = "https://api.example.com/data";
const params = new URLSearchParams({ page: "1", filter: "latest" });
const fullURL = `${baseURL}?${params.toString()}`;
// 结果：https://api.example.com/data?page=1&filter=latest

提交表单数据：将表单数据序列化为 x-www-form-urlencoded 格式：

const formData = new FormData(formElement);
const params = new URLSearchParams(formData);
const encodedData = params.toString();

修改当前页面 URL：

const params = new URLSearchParams(window.location.search);
params.set("page", "2");
window.history.replaceState(null, "", `?${params.toString()}`);

keys()

params.keys()：()，用于获取 URL 查询参数中所有键的迭代器。它允许你遍历查询字符串中的所有键名。

返回：
keyIterator：Iterator，返回一个迭代器对象，可通过 for...of 循环或手动调用 next() 遍历键名。
特性：
1. 迭代器特性：
  - 每次调用 next() 返回 { value: string, done: boolean }。
  - 迭代结束后，done 为 true。
2. 顺序一致性：键的遍历顺序与参数在 URL 中的原始顺序一致（除非调用了 sort()）。
3. 重复键处理：即使键有多个值，迭代器仍按出现次数遍历键名：
  js
```
const params = new URLSearchParams("color=red&color=blue");
const keys = Array.from(params.keys());
console.log(keys); // ["color", "color"]
```
  1
  2
  3
4. 空键值处理：键存在但值为空时，仍会返回键名：
  js
```
const params = new URLSearchParams("flag=");
console.log(Array.from(params.keys())); // ["flag"]
```
  1
  2
5. 对比 values() 和 entries()：
  方法返回值示例（参数：?a=1&b=2）
  keys() 所有键的迭代器 "a", "b"
  values() 所有值的迭代器 "1", "2"
  entries() 所有键值对的迭代器 ["a", "1"], ["b", "2"]

方法	返回值	示例（参数：`?a=1&b=2`）
`keys()`	所有键的迭代器	`"a", "b"`
`values()`	所有值的迭代器	`"1", "2"`
`entries()`	所有键值对的迭代器	`["a", "1"], ["b", "2"]`

使用场景：

批量参数验证：遍历所有键名，检查是否存在非法参数。

const validKeys = new Set(["page", "filter"]);
for (const key of params.keys()) {
  if (!validKeys.has(key)) throw new Error("无效参数");
}

动态生成 UI：根据键名渲染筛选条件标签。

const params = new URLSearchParams("color=red&size=M");
Array.from(params.keys()).forEach(key => {
  createFilterTag(key); // 创建 "color" 和 "size" 标签
});

日志记录：记录 URL 中所有传入的键名。

console.log("请求参数键名：", Array.from(params.keys()));

示例：

for...of 遍历键名：

const params = new URLSearchParams("name=John&age=20&lang=en");
for (const key of params.keys()) {
  console.log(key); // 依次输出 "name", "age", "lang"
}

转换为数组：

const params = new URLSearchParams("tag=js&tag=css");
const keys = Array.from(params.keys());
console.log(keys); // ["tag", "tag"]（保留重复键）

手动操作迭代器：

const params = new URLSearchParams("a=1&b=2");
const iterator = params.keys();
console.log(iterator.next().value); // "a"
console.log(iterator.next().value); // "b"
console.log(iterator.next().done);  // true

values()

params.values()：()，用于获取 URL 查询参数中所有值的迭代器。它允许你遍历查询字符串中的所有参数值。

返回：
valueIterator：Iterator，返回一个迭代器对象，可通过 for...of 循环或手动调用 next() 遍历所有值。
特性/使用场景/示例：与 keys() 一致

entries()

params.entries()：()，用于获取 URL 查询参数中所有键值对的迭代器。它允许遍历查询字符串中的所有参数，并以 [key, value] 数组形式返回每个键值对。

返回：
entriesIterator：Iterator，返回一个迭代器对象，可通过 for...of 循环或手动调用 next() 遍历所有键值对。每个键值对为 [key, value] 形式的数组。
特性：与 keys() 一致

示例：

for...of 遍历键值对：

const params = new URLSearchParams(window.location.search);
for (const [key, value] of params.entries()) {
  console.log(`参数 ${key} 的值为 ${value}`);
}

动态构建参数对象：将键值对转换为普通对象（注意重复键会被覆盖）：

Object.fromEntries()：(entries)，

const params = new URLSearchParams("a=1&a=2");
const obj = Object.fromEntries(params.entries());
console.log(obj); // { a: "2" }（重复键仅保留最后的值）

forEach()

params.forEach()：(callback,thisArg?)，用于遍历 URL 查询参数中的所有键值对，并对每个键值对执行回调函数。

callback：(value,key,parent)=>void，遍历每个键值对时执行的回调函数。
- value：string，当前键的值（解码后的字符串）。
- key：string，当前键的名称（解码后的字符串）。
- parent：URLSearchParams，调用 forEach() 的 URLSearchParams 实例。
thisArg?：any，执行回调函数时使用的 this 值（若需指定上下文）。
特性：
1. 处理重复键：重复的键如 ?key=1&key=2 会触发两次回调。
  js
```
const params = new URLSearchParams("color=red&color=blue");
params.forEach((value, key) => {
  console.log(key, ":", value);
});
// 输出：
// color : red
// color : blue
```
  1
  2
  3
  4
  5
  6
  7
2. 空值处理：若参数无值（如 ?flag），value 为空字符串：
  js
```
const params = new URLSearchParams("flag");
params.forEach((value, key) => {
  console.log(key, value); // 输出：flag ""
});
```
  1
  2
  3
  4
3. 遍历顺序：按查询参数的原始顺序（或调用 sort() 后的顺序）执行回调。
4. 自动解码：键和值中的 URL 编码字符（如 %20）自动解码（如空格）。
5. 无法中断遍历：不支持像 Array.forEach() 中通过 return 提前终止遍历（若需中断，改用 for...of 循环）。
6. 修改参数时的风险：在回调中修改 params（如删除或添加参数）可能导致意外行为：
  js
```
// ❌ 危险操作（可能导致死循环或遗漏参数）
params.forEach((value, key) => {
  params.delete(key); 
});
```
  1
  2
  3
  4

示例：

指定 thisArg 上下文：

const logger = {
  log(key, value) {
    console.log(this.prefix, key, "=", value);
  },
  prefix: "[参数]"
};

const params = new URLSearchParams("page=1");
params.forEach(function(value, key) {
  this.log(key, value); // this 指向 logger
}, logger);
// 输出：[参数] page = 1

参数校验：遍历所有参数，检查值是否符合要求：

const validKeys = new Set(["page", "filter"]);
params.forEach((value, key) => {
  if (!validKeys.has(key)) throw new Error(`非法参数: ${key}`);
});

动态渲染 UI：根据参数生成筛选条件标签：

const filters = document.getElementById("filters");
params.forEach((value, key) => {
  const tag = document.createElement("div");
  tag.textContent = `${key}: ${value}`;
  filters.appendChild(tag);
});

日志记录：记录所有参数键值对：

params.forEach((value, key) => {
  console.log(`[请求参数] ${key}=${value}`);
});

URLSearchParams ​

索引 ​

URLSearchParams ​

方法 ​

new URLSearchParams() ​

append() ​

delete() ​

get() ​

set() ​

has() ​

getAll() ​

sort() ​

toString() ​

keys() ​

values() ​

entries() ​

forEach() ​

URLSearchParams

索引

URLSearchParams

方法

new URLSearchParams()

append()

delete()

get()

set()

has()

getAll()

sort()

toString()

keys()

values()

entries()

forEach()