JavaScript URLSearchParams 入门与实战 – wiki基地

---

JavaScript URLSearchParams 入门与实战：轻松驾驭 URL 查询字符串

在 Web 开发中，URL (统一资源定位符) 不仅是资源的地址，也常常作为客户端与服务器之间传递数据的载体。URL 的一部分——查询字符串（Query String），即问号 ? 后面的部分，就是一种常用的数据传递方式。例如：https://example.com/search?keyword=javascript&page=1。这里的 keyword=javascript&page=1 就是查询字符串，它由一系列键值对组成，键值对之间用 & 分隔，键与值之间用 = 分隔。

过去，处理 URL 查询字符串常常依赖于手动解析 window.location.search 属性，这涉及字符串分割、解码、以及处理各种边界情况（如特殊字符、重复键等），过程繁琐且容易出错。

为了解决这一痛点，Web API 提供了一个标准接口：URLSearchParams。它提供了一种简单、强大的方式来创建、读取、修改和操作 URL 的查询字符串。本文将带你深入了解 URLSearchParams 的基础知识和实用技巧。

一、为什么需要 URLSearchParams？手动解析的痛点

在 URLSearchParams 出现之前，开发者通常需要自己编写代码来处理查询字符串。以下是一个简单的手动解析示例：

“`javascript
// 假设当前 URL 是 https://example.com/data?category=tech&page=2&tag=js&tag=web
const queryString = window.location.search; // 获取到 “?category=tech&page=2&tag=js&tag=web”

// 手动解析
function parseQueryString(qs) {
const params = {};
// 移除开头的问号（如果存在）
if (qs.startsWith(‘?’)) {
qs = qs.substring(1);
}
// 按 ‘&’ 分割键值对
const pairs = qs.split(‘&’);

pairs.forEach(pair => {
// 按 ‘=’ 分割键和值
let [key, value] = pair.split(‘=’);

// 处理解码 (例如，空格被编码为 %20)
key = decodeURIComponent(key);
value = decodeURIComponent(value || ''); // 值可能为空

// 处理重复的键 (例如上面的 tag=js&tag=web)
if (params.hasOwnProperty(key)) {
  if (Array.isArray(params[key])) {
    params[key].push(value);
  } else {
    params[key] = [params[key], value];
  }
} else {
  params[key] = value;
}

});

return params;
}

const dataParams = parseQueryString(queryString);
console.log(dataParams);
// 输出大致会是：{ category: “tech”, page: “2”, tag: [“js”, “web”] }
“`

这段代码虽然实现了基本功能，但存在诸多问题：

1. 复杂性高： 需要手动处理问号、分隔符 & 和 =, 以及键值不存在的情况。
2. 编码/解码： 必须手动使用 decodeURIComponent 处理 URL 编码，容易遗漏或出错。
3. 重复键处理： 需要额外的逻辑来判断并存储具有相同键但不同值的情况（如上面的 tag）。
4. 健壮性差： 对于格式不规范的查询字符串（如 a=1&&b=2 或只有键没有值 a&b=2），手动解析可能无法正确处理。
5. 难以修改： 如果想要修改或添加参数，需要将对象重新序列化回字符串，同样容易出错。

URLSearchParams正是为了解决这些问题而诞生的。它提供了一个标准、健壮、易用的 API 来管理查询字符串。

二、URLSearchParams 入门：创建实例

URLSearchParams 是一个构造函数，你可以使用 new 关键字来创建它的实例。创建实例时，你可以传入不同的参数来初始化它。

2.1 创建一个空的 URLSearchParams 实例

javascript
const params1 = new URLSearchParams();
console.log(params1.toString()); // 输出空字符串 ""

2.2 从字符串创建实例

你可以传入一个查询字符串作为参数。它可以带 ? 开头，也可以不带。URLSearchParams 会自动解析。

“`javascript
const params2 = new URLSearchParams(‘category=frontend&order=desc’);
console.log(params2.toString()); // 输出: “category=frontend&order=desc”

const params3 = new URLSearchParams(‘?lang=zh-CN&version=1.0’);
console.log(params3.toString()); // 输出: “lang=zh-CN&version=1.0”

// 自动处理重复键
const params4 = new URLSearchParams(‘tag=javascript&tag=css&page=1’);
console.log(params4.toString()); // 输出: “tag=javascript&tag=css&page=1”
``
注意，toString()` 方法会自动进行 URL 编码。

2.3 从对象字面量创建实例

你可以传入一个包含键值对的对象来初始化 URLSearchParams。对象的键和值将转换为查询参数。

javascript
const params5 = new URLSearchParams({
id: 123,
name: '张三', // 中文会自动编码
isActive: true
});
console.log(params5.toString()); // 输出: "id=123&name=%E5%BC%A0%E4%B8%89&isActive=true"
注意：对象的属性值会被转换为字符串。非字符串类型（如数字、布尔值）会调用其 toString() 方法。

2.4 从数组的数组创建实例

你可以传入一个由二元数组组成的数组，每个二元数组代表一个键值对 [key, value]。这对于处理具有重复键的情况非常有用。

javascript
const params6 = new URLSearchParams([
['category', 'programming'],
['tag', 'javascript'],
['tag', 'web-development'], // 重复的键
['page', 1]
]);
console.log(params6.toString()); // 输出: "category=programming&tag=javascript&tag=web-development&page=1"

2.5 从 URLSearchParams 实例创建实例（复制）

你可以传入另一个 URLSearchParams 实例来创建一个副本。

javascript
const originalParams = new URLSearchParams('a=1&b=2');
const copiedParams = new URLSearchParams(originalParams);
console.log(copiedParams.toString()); // 输出: "a=1&b=2"

三、URLSearchParams 核心方法：增删改查

URLSearchParams 实例提供了多种方法来方便地操作查询参数。

3.1 添加参数：append(name, value)

append() 方法用于向查询字符串中添加一个键值对。如果查询字符串中已经存在同名的键，append() 不会覆盖，而是会新增一个同名的键值对。

“`javascript
const params = new URLSearchParams();

params.append(‘name’, ‘Alice’);
console.log(params.toString()); // 输出: “name=Alice”

params.append(‘name’, ‘Bob’); // 添加另一个 name
console.log(params.toString()); // 输出: “name=Alice&name=Bob”

params.append(‘age’, 30);
console.log(params.toString()); // 输出: “name=Alice&name=Bob&age=30”
“`

3.2 设置参数：set(name, value)

set() 方法用于设置一个参数的值。如果同名的参数已经存在，set() 会删除所有同名的旧参数，然后添加一个新的参数。如果同名的参数不存在，它会创建一个新的参数。

“`javascript
const params = new URLSearchParams(‘role=user&role=admin&id=10’);

params.set(‘role’, ‘guest’); // 覆盖所有 role 参数
console.log(params.toString()); // 输出: “role=guest&id=10”

params.set(‘status’, ‘active’); // 添加一个新参数
console.log(params.toString()); // 输出: “role=guest&id=10&status=active”

params.set(‘id’, 20); // 覆盖 id 参数
console.log(params.toString()); // 输出: “role=guest&id=20&status=active”
“`

3.3 删除参数：delete(name)

delete() 方法用于删除指定名称的所有参数。

“`javascript
const params = new URLSearchParams(‘tag=js&tag=css&page=1’);

params.delete(‘tag’); // 删除所有 tag 参数
console.log(params.toString()); // 输出: “page=1”

params.delete(‘nonexistent’); // 删除不存在的参数，不会报错
console.log(params.toString()); // 输出: “page=1”
“`

3.4 检查参数是否存在：has(name)

has() 方法用于检查是否存在指定名称的参数，返回布尔值 true 或 false。

“`javascript
const params = new URLSearchParams(‘user=admin&page=5’);

console.log(params.has(‘user’)); // 输出: true
console.log(params.has(‘category’)); // 输出: false
“`

3.5 获取参数值：get(name) 和 getAll(name)

• get(name)：获取指定名称参数的 第一个 值。如果参数不存在，返回 null。
• getAll(name)：获取指定名称参数的 所有 值，返回一个字符串数组。如果参数不存在，返回空数组 []。

“`javascript
const params = new URLSearchParams(‘item=apple&item=banana&color=red’);

console.log(params.get(‘item’)); // 输出: “apple” (只返回第一个值)
console.log(params.get(‘color’)); // 输出: “red”
console.log(params.get(‘price’)); // 输出: null

console.log(params.getAll(‘item’)); // 输出: [“apple”, “banana”] (返回所有值组成的数组)
console.log(params.getAll(‘color’)); // 输出: [“red”]
console.log(params.getAll(‘price’)); // 输出: []
“`

四、遍历 URLSearchParams

URLSearchParams 实例是可迭代的（iterable），你可以使用 for...of 循环或者 forEach 方法来遍历所有的参数。

4.1 使用 for...of 遍历

for...of 循环默认会遍历键值对数组 [key, value]。

“`javascript
const params = new URLSearchParams(‘a=1&b=2&a=3’);

console.log(“使用 for…of 遍历:”);
for (const [key, value] of params) {
console.log(${key}: ${value});
}
// 输出:
// a: 1
// b: 2
// a: 3
“`

4.2 使用 forEach 方法遍历

forEach 方法接收一个回调函数，该函数会为每个参数调用一次，并传入 (value, key, searchParams) 作为参数。

“`javascript
const params = new URLSearchParams(‘x=10&y=20’);

console.log(“\n使用 forEach 遍历:”);
params.forEach((value, key) => {
console.log(${key}: ${value});
});
// 输出:
// x: 10
// y: 20
``
注意forEach回调函数的参数顺序是(value, key, …), 与for…of的[key, value]` 不同。

4.3 使用 keys(), values(), entries() 迭代器

URLSearchParams 也提供了返回迭代器的方法，类似于 Map 对象：

• keys(): 返回一个迭代器，遍历所有参数的键。
• values(): 返回一个迭代器，遍历所有参数的值。
• entries(): 返回一个迭代器，遍历所有参数的 [key, value] 对（与 for...of 默认行为相同）。

“`javascript
const params = new URLSearchParams(‘c=hello&d=world’);

console.log(“\n使用 keys() 遍历:”);
for (const key of params.keys()) {
console.log(key);
}
// 输出:
// c
// d

console.log(“\n使用 values() 遍历:”);
for (const value of params.values()) {
console.log(value);
}
// 输出:
// hello
// world

console.log(“\n使用 entries() 遍历:”);
for (const entry of params.entries()) {
console.log(entry); // entry 是 [key, value] 数组
}
// 输出:
// [“c”, “hello”]
// [“d”, “world”]
“`

五、转换为字符串：toString()

toString() 方法是 URLSearchParams 的重要用途之一，它将内部的键值对结构序列化回一个符合 URL 查询字符串规范的字符串，并且会自动进行 URL 编码。

“`javascript
const params = new URLSearchParams();
params.append(‘query’, ‘搜索关键词’); // 中文
params.append(‘page’, 1);
params.append(‘tags’, ‘前端’);
params.append(‘tags’, ‘JavaScript’); // 重复键

const queryString = params.toString();
console.log(queryString); // 输出: “query=%E6%90%9C%E7%B4%A2%E5%85%B3%E9%94%AE%E8%AF%8D&page=1&tags=%E5%89%8D%E7%AB%AF&tags=JavaScript”
``
可以看到，toString()自动将中文、空格等特殊字符进行了%` 编码。这是构建 URL 或发送网络请求时非常重要的步骤。

六、集成应用：与 URL API 结合

URLSearchParams 经常与 URL Web API 一起使用，以便更方便地解析和构建完整的 URL。

URL 构造函数可以接受一个完整的 URL 字符串，并将其解析成各个部分（如 origin, pathname, search, hash 等）。URL 对象的 searchParams 属性就是 一个 URLSearchParams 实例，它代表了该 URL 的查询字符串部分。

“`javascript
const urlString = ‘https://example.com/path/to/resource?id=42&sort=asc&filter=active’;
const url = new URL(urlString);

// url.searchParams 是一个 URLSearchParams 实例
const params = url.searchParams;

console.log(params.get(‘id’)); // 输出: “42”
console.log(params.get(‘sort’)); // 输出: “asc”
console.log(params.getAll(‘filter’));// 输出: [“active”]

// 使用 URLSearchParams 修改参数
params.set(‘sort’, ‘desc’); // 将 sort 改为 desc
params.append(‘tag’, ‘new’); // 添加一个 tag 参数
params.delete(‘filter’); // 删除 filter 参数

// url 对象的 search 属性会自动更新为 params.toString() 的结果
console.log(url.search); // 输出: “?id=42&sort=desc&tag=new”

// 获取修改后的完整 URL
console.log(url.toString()); // 输出: “https://example.com/path/to/resource?id=42&sort=desc&tag=new”
// 或者 url.href
console.log(url.href); // 输出: “https://example.com/path/to/resource?id=42&sort=desc&tag=new”
“`
这种结合方式极大地简化了 URL 的解析和构建工作。

七、实战案例

7.1 解析当前页面的查询参数

这是最常见的用法之一。你可以通过 window.location.search 获取当前页面的查询字符串，然后用 URLSearchParams 解析。

“`javascript
// 假设当前页面 URL 为: https://myapp.com/products?category=electronics&page=3&sort=price
const currentParams = new URLSearchParams(window.location.search);

const category = currentParams.get(‘category’);
const page = currentParams.get(‘page’); // 获取到的是字符串 “3”
const sort = currentParams.get(‘sort’);

console.log(当前分类: ${category}); // 输出: “当前分类: electronics”
console.log(当前页码: ${page}); // 输出: “当前页码: 3”
console.log(排序方式: ${sort}); // 输出: “排序方式: price”

// 如果需要数字类型的页码，需要手动转换
const pageNumber = parseInt(page, 10);
if (!isNaN(pageNumber)) {
console.log(页码 (数字): ${pageNumber}); // 输出: “页码 (数字): 3”
}
“`

7.2 构建 API 请求的查询字符串

当你需要向后端 API 发送 GET 请求，并携带查询参数时，URLSearchParams 是理想的工具。

“`javascript
const apiBaseUrl = ‘https://api.example.com/v1/items’;
const queryFilters = {
status: ‘published’,
authorId: 101,
limit: 20
};

const searchParams = new URLSearchParams(queryFilters);

// 添加一个额外的参数
searchParams.append(‘tags’, ‘javascript’);
searchParams.append(‘tags’, ‘api’);

const requestUrl = ${apiBaseUrl}?${searchParams.toString()};

console.log(“构建的 API 请求 URL:”);
console.log(requestUrl);
// 输出: “https://api.example.com/v1/items?status=published&authorId=101&limit=20&tags=javascript&tags=api”

// 使用 fetch 发送请求
/
fetch(requestUrl)
.then(response => response.json())
.then(data => {
console.log(‘API 响应数据:’, data);
})
.catch(error => {
console.error(‘请求出错:’, error);
});
/
“`

7.3 从 HTML 表单数据创建查询参数

如果有一个 HTML 表单，你可以直接使用 new URLSearchParams(new FormData(formElement)) 来创建包含表单数据的 URLSearchParams 实例。这对于构建 GET 请求的查询字符串或作为 POST 请求体的一部分非常方便。

“`html

DateRelevance

“`

“`javascript
const form = document.getElementById(‘searchForm’);

form.addEventListener(‘submit’, function(event) {
event.preventDefault(); // 阻止表单默认提交

// 直接从 FormData 创建 URLSearchParams
const formData = new FormData(form);
const searchParams = new URLSearchParams(formData);

console.log(“从表单数据构建的查询字符串:”);
console.log(searchParams.toString());
// 如果用户输入 “web dev”, 勾选 “strict”, 选择 “Relevance”
// 输出可能为: “search=web+dev&options=strict&sort_by=relevance”
// 注意：FormData 会正确处理重复的 name (如 options) 和编码 (如空格转为 + 或 %20)

// 你可以用这个字符串来更新 URL (需要使用 history API 避免刷新)
// history.pushState({}, ”, ${window.location.pathname}?${searchParams.toString()});

// 或者用于构建 fetch 请求
// fetch(/api/search?${searchParams.toString()})…
});
“`
这是一个非常便捷的特性，大大简化了表单数据的处理。

7.4 更新当前 URL 的查询参数 (结合 History API)

直接修改 window.location.search 会导致页面重新加载。如果想在不刷新页面的情况下更新 URL，可以使用 History API 的 pushState 或 replaceState 方法。

“`javascript
// 假设当前 URL 是 /items?page=1&sort=asc
const currentUrl = new URL(window.location.href);
const params = currentUrl.searchParams;

// 修改参数
params.set(‘page’, 2);
params.set(‘sort’, ‘desc’);
params.append(‘filter’, ‘new’); // 添加一个新参数

// 使用 History API 更新 URL，不刷新页面
// 第一个参数: state对象 (可用于存储与新URL关联的状态信息)
// 第二个参数: title (目前大多数浏览器忽略此参数)
// 第三个参数: 新的URL
history.pushState(null, ”, currentUrl.toString());

console.log(“更新后的 URL:”);
console.log(window.location.href); // 现在 URL 变成了 /items?page=2&sort=desc&filter=new
console.log(“页面不会刷新”);
“`
这种技术常用于实现筛选、分页等功能，同时保持 URL 的状态同步。

八、编码与解码的自动化处理

URLSearchParams 最重要的优点之一是它自动处理 URL 编码和解码。

• 当你使用 append(), set(), 或者通过构造函数传入带有特殊字符（如空格、中文、&, =, ?, # 等）的键或值时，URLSearchParams 会自动使用 encodeURIComponent 对它们进行编码。
• 当你使用 get(), getAll(), 或者通过迭代器获取参数值时，URLSearchParams 会自动使用 decodeURIComponent 对它们进行解码。

“`javascript
const params = new URLSearchParams();
params.append(‘name’, ‘李 四’); // 包含空格和中文
params.append(‘url’, ‘https://example.com/?a=1&b=2’); // 包含特殊符号

console.log(params.toString());
// 输出: “name=%E6%9D%8E+%E5%9B%9B&url=https%3A%2F%2Fexample.com%2F%3Fa%3D1%26b%3D2”
// 注意空格被编码成了 %20 或者 + (取决于实现，多数浏览器中 URLSearchParams 会用 %20，FormData可能会用+，但两者都是有效的 URL 编码)
// 中文、问号、等号、&号等都被正确编码

// 获取值时自动解码
console.log(params.get(‘name’)); // 输出: “李 四”
console.log(params.get(‘url’)); // 输出: “https://example.com/?a=1&b=2”
“`
这极大地减轻了开发者手动处理编码问题的负担，减少了出错的可能性。

九、浏览器兼容性

URLSearchParams 是一个现代 Web API，在主流的现代浏览器（Chrome, Firefox, Safari, Edge, Opera）以及 Node.js 环境中都有很好的支持。对于需要兼容非常老的浏览器（如 IE）的情况，可能需要使用 Polyfill。但在大多数现代 Web 应用场景下，可以直接放心使用。

十、总结

URLSearchParams 是 JavaScript 中处理 URL 查询字符串的强大而便捷的标准工具。它将繁琐的手动字符串解析、编码、解码、重复键处理等工作封装起来，提供了清晰易用的 API。

使用 URLSearchParams 的核心优势：

• 标准化： 遵循 Web 标准，代码可移植性好。
• 易用性： 提供直观的 append, set, delete, get, getAll, has 等方法。
• 健壮性： 自动处理 URL 编码和解码，减少错误。
• 迭代能力： 方便遍历所有参数。
• 集成性： 与 URL 对象以及 FormData 无缝集成。

无论是解析当前页面的 URL、构建发送给 API 的请求参数、处理表单数据，还是在不刷新页面的情况下更新 URL 状态，URLSearchParams 都能让你事半功倍。掌握 URLSearchParams 是现代 JavaScript 开发中处理 URL 不可或缺的技能。开始在你的项目中使用它吧，你会发现它能让你的代码更简洁、更健壮！

---