JavaScript URLSearchParams 入门：轻松获取和设置 URL 参数 – wiki基地

---

JavaScript URLSearchParams 入门：轻松获取和设置 URL 参数

在现代 Web 开发中，与 URL 查询字符串（Query String）打交道几乎是不可避免的任务。无论是从当前页面的 URL 中读取参数以获取用户偏好或页面状态，还是在构建 API 请求或生成带有特定信息的链接时添加参数，高效、安全地处理这些数据都是前端开发者的基本技能。

传统的做法，比如直接操作 window.location.search 字符串，使用字符串方法（如 split、substring、indexOf）进行分割、解析和拼接，然后手动处理 URL 编码/解码（encode/decode），往往会变得非常繁琐、易错且难以维护。想象一下，你需要解析一个包含多个同名参数（例如 ?tag=js&tag=web&page=2&sort=date）、带有特殊字符、或者甚至包含等号（=）或连接符（&）本身的参数值的情况。手动处理这些情况会迅速让代码变得复杂不堪，并且容易引入安全漏洞（例如编码问题）。

幸运的是，现代 Web 标准为我们提供了一个强大且易于使用的内置接口来解决这个问题：URLSearchParams。

URLSearchParams 接口定义了处理 URL 查询字符串的实用方法。它是一个专门用于操作 URL 参数的迭代器对象，能够解析包含 & 和 = 的字符串，并提供方便的方法来访问、修改、添加和删除参数，同时自动处理 URL 编码和解码，极大地简化了与查询字符串相关的开发工作。

本文将带您深入了解 URLSearchParams 的方方面面，从创建实例到掌握其核心方法，并通过丰富的示例展示如何在实际开发中轻松应用它。

1. 为什么选择 URLSearchParams？

在深入学习如何使用它之前，我们先来明确为什么 URLSearchParams 是处理 URL 参数的首选方案：

1. 标准化与规范化： 它是 Web API 的一部分，遵循统一的标准，不同浏览器之间的行为一致（在支持的情况下）。
2. 易用性： 提供了直观的方法（如 get, set, append, delete, has 等），避免了手动字符串分割和拼接的复杂性。
3. 自动编码/解码： URLSearchParams 会自动处理参数名和参数值的 URL 编码（如将空格转为 %20，将 & 转为 %26 等），确保数据安全传输和正确解析，避免了常见的编码错误。
4. 健壮性： 能够正确处理各种复杂的查询字符串格式，包括重复的参数名、空值参数、带 #（哈希）的 URL 等。
5. 可迭代性： 它是可迭代对象，可以轻松地使用 for...of 循环遍历所有参数。
6. 与 URL 对象的集成： 它可以方便地与 URL 对象（另一个处理 URL 的标准接口）配合使用，实现更全面的 URL 操作。

总而言之，使用 URLSearchParams 可以让您的代码更清晰、更安全、更易于维护，告别繁琐易错的字符串手动解析时代。

2. 创建 URLSearchParams 实例

要使用 URLSearchParams 的功能，首先需要创建一个它的实例。URLSearchParams 的构造函数支持多种参数，可以根据您的需求选择最方便的方式。

2.1 创建一个空的 URLSearchParams 对象

如果您打算从零开始构建查询字符串，可以创建一个空的实例：

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

2.2 从一个查询字符串创建

这是最常见的用法，特别是当您需要解析当前 URL 或从其他源获取的 URL 中的查询参数时。构造函数会解析提供的字符串。注意，您可以选择性地包含开头的 ? 符号，URLSearchParams 都能正确处理。

“`javascript
// 从一个标准的查询字符串创建
const params1 = new URLSearchParams(‘?name=Alice&age=30&city=New York’);
console.log(params1.get(‘name’)); // 输出 “Alice”
console.log(params1.get(‘age’)); // 输出 “30”

// 不带问号的字符串也可以
const params2 = new URLSearchParams(‘id=123&category=electronics’);
console.log(params2.get(‘id’)); // 输出 “123”

// 包含特殊字符和重复键的情况
const complexParams = new URLSearchParams(‘query=hello%20world&tag=js&tag=web&empty=’);
console.log(complexParams.get(‘query’)); // 输出 “hello world” (自动解码)
console.log(complexParams.getAll(‘tag’)); // 输出 [“js”, “web”]
console.log(complexParams.get(’empty’)); // 输出 “” (空字符串)
“`

URLSearchParams 会自动处理 URL 编码（如 %20 会被解码为空格）和解码。

2.3 从另一个 URLSearchParams 对象创建

您可以复制一个现有的 URLSearchParams 对象：

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

2.4 从一个二维数组（或迭代器）创建

您可以提供一个包含键值对数组的数组。这类似于 Map 或 Object.entries() 的结构。

javascript
const paramsFromArray = new URLSearchParams([
['key1', 'value1'],
['key2', 'value2 with spaces'], // 值会自动编码
['key1', 'another value'] // 重复的键
]);
console.log(paramsFromArray.get('key1')); // 输出 "value1" (只会返回第一个值)
console.log(paramsFromArray.getAll('key1')); // 输出 ["value1", "another value"]
console.log(paramsFromArray.toString()); // 输出 "key1=value1&key2=value2%20with%20spaces&key1=another+value" (注意空格编码为 %20 或 +)
补充说明： URLSearchParams 在编码空格时，有些浏览器会使用 +，有些使用 %20。规范允许这两种形式，并且都能被正确解码。URLSearchParams 自身的 toString() 方法通常使用 +，但在解析时都能识别。

2.5 从一个对象创建

您可以提供一个普通 JavaScript 对象，其属性将作为参数的键和值。需要注意的是，这种方式不支持同一个键有多个值。 如果对象中有重复的键，后面的值会覆盖前面的值（这与对象的属性特性一致）。

“`javascript
const paramsFromObject = new URLSearchParams({
name: ‘Bob’,
age: 25,
city: ‘London’
});
console.log(paramsFromObject.get(‘name’)); // 输出 “Bob”
console.log(paramsFromObject.toString()); // 输出 “name=Bob&age=25&city=London”

// 如果对象有重复键（实际中不可能，这里的例子是概念上的，或者说如果你的源数据是 Map 并且有重复 key，转成对象会丢失）
// 强调：普通 JS 对象不能有重复键，所以这个构造函数方式不适合有重复参数名的场景。
// 如果你有 { tag: [‘js’, ‘web’] } 这样的对象，需要自行处理或转换为二维数组。
``
由于普通 JavaScript 对象的特性，如果您的查询字符串可能包含重复键（例如?tag=js&tag=web`），则不适合使用对象作为构造函数参数。二维数组或迭代器的方式更适合处理这种情况。

3. 获取 URL 参数

创建了 URLSearchParams 实例后，就可以使用提供的方法来获取参数的值了。

3.1 get(name) 方法

这是最常用的方法，用于获取指定参数的第一个值。如果参数不存在，则返回 null。

“`javascript
const params = new URLSearchParams(‘name=Alice&role=user&tag=js&tag=web’);

console.log(params.get(‘name’)); // 输出 “Alice”
console.log(params.get(‘role’)); // 输出 “user”
console.log(params.get(‘tag’)); // 输出 “js” (只返回第一个)
console.log(params.get(‘city’)); // 输出 null (参数不存在)
console.log(params.get(‘name_nonexistent’)); // 输出 null
“`

3.2 getAll(name) 方法

如果您知道某个参数可能出现多次（例如标签、筛选条件等），可以使用 getAll() 方法。它返回一个包含指定参数所有值的数组。如果参数不存在，则返回一个空数组 []。

“`javascript
const params = new URLSearchParams(‘name=Alice&tag=js&tag=web&tag=css&category=frontend’);

console.log(params.getAll(‘tag’)); // 输出 [“js”, “web”, “css”]
console.log(params.getAll(‘name’)); // 输出 [“Alice”] (即使只有一个值，也返回数组)
console.log(params.getAll(‘city’)); // 输出 [] (参数不存在)
“`

3.3 has(name) 方法

用于检查指定的参数是否存在。返回一个布尔值 (true 或 false)。

“`javascript
const params = new URLSearchParams(‘name=Alice&age=30&empty=’);

console.log(params.has(‘name’)); // 输出 true
console.log(params.has(‘age’)); // 输出 true
console.log(params.has(‘city’)); // 输出 false
console.log(params.has(’empty’)); // 输出 true (即使值是空的，只要键存在就返回 true)
“`

4. 设置和修改 URL 参数

URLSearchParams 提供了几个方法来动态地添加、修改或删除参数。

4.1 set(name, value) 方法

设置指定参数的值。
* 如果参数 name 不存在，则添加该参数及其值。
* 如果参数 name 已存在，则移除所有同名参数，然后添加一个新的同名参数和值。

“`javascript
const params = new URLSearchParams(‘name=Alice&age=30&tag=js&tag=web’);

console.log(params.toString()); // 初始: “name=Alice&age=30&tag=js&tag=web”

params.set(‘name’, ‘Bob’); // 修改现有参数
console.log(params.toString()); // 修改后: “name=Bob&age=30&tag=js&tag=web”

params.set(‘city’, ‘Paris’); // 添加新参数
console.log(params.toString()); // 添加后: “name=Bob&age=30&tag=js&tag=web&city=Paris”

params.set(‘tag’, ‘css’); // 修改一个有多个值的参数，会移除所有旧值
console.log(params.toString()); // 修改后: “name=Bob&age=30&tag=css&city=Paris” (原来的 js 和 web 被移除了)

params.set(‘new_param’, ”); // 设置空值参数
console.log(params.toString()); // 添加空值: “name=Bob&age=30&tag=css&city=Paris&new_param=”
``set()方法的“覆盖”行为是它与append()最主要的区别，适用于你想确保某个键在查询字符串中最多只出现一次（例如分页页码page=X，搜索关键词q=XXX`）。

4.2 append(name, value) 方法

添加指定参数。
* 如果参数 name 不存在，则添加该参数及其值。
* 如果参数 name 已存在，则在现有同名参数的后面再添加一个同名参数和值。

“`javascript
const params = new URLSearchParams(‘name=Alice&tag=js’);

console.log(params.toString()); // 初始: “name=Alice&tag=js”

params.append(‘city’, ‘London’); // 添加新参数
console.log(params.toString()); // 添加后: “name=Alice&tag=js&city=London”

params.append(‘tag’, ‘web’); // 在现有 tag 后面追加
console.log(params.toString()); // 追加后: “name=Alice&tag=js&city=London&tag=web”

params.append(‘tag’, ‘css’); // 再次追加
console.log(params.toString()); // 再次追加后: “name=Alice&tag=js&city=London&tag=web&tag=css”

params.append(‘another_empty’, ”); // 添加空值参数
console.log(params.toString()); // 添加空值: “name=Alice&tag=js&city=London&tag=web&tag=css&another_empty=”
``append()` 方法适用于需要同一个键出现多次的场景，例如多选过滤条件、标签列表等。

4.3 delete(name) 方法

删除指定参数及其所有值。

“`javascript
const params = new URLSearchParams(‘name=Alice&age=30&tag=js&tag=web’);

console.log(params.toString()); // 初始: “name=Alice&age=30&tag=js&tag=web”

params.delete(‘age’); // 删除 age 参数
console.log(params.toString()); // 删除后: “name=Alice&tag=js&tag=web”

params.delete(‘tag’); // 删除所有 tag 参数
console.log(params.toString()); // 删除后: “name=Alice”

params.delete(‘city’); // 删除不存在的参数，不报错，无任何影响
console.log(params.toString()); // 删除不存在的参数后: “name=Alice”
“`

4.4 sort() 方法

按键名的字母顺序对参数进行排序。这对于生成规范化的查询字符串非常有用（例如用于缓存键或签名）。

“`javascript
const params = new URLSearchParams(‘tag=web&name=Alice&age=30&tag=js’);

console.log(params.toString()); // 初始顺序不确定，可能因浏览器而异，例如: “tag=web&name=Alice&age=30&tag=js”

params.sort(); // 排序

// 排序结果：首先按键名字母顺序排序，同名键保持相对顺序
console.log(params.toString()); // 排序后: “age=30&name=Alice&tag=web&tag=js” (注意 age, name, tag 的顺序，以及 tag=web, tag=js 的相对顺序)
``sort()方法会修改原始的URLSearchParams` 实例。

5. 将 URLSearchParams 转换回字符串

在完成对参数的修改后，通常需要将其转换回一个标准的查询字符串，以便用于构建 URL 或其他目的。

5.1 toString() 方法

toString() 方法是唯一的方法，它返回一个表示查询字符串的字符串，自动处理 URL 编码，并且使用 & 连接参数，使用 = 连接键值。

“`javascript
const params = new URLSearchParams();
params.append(‘query’, ‘search term’);
params.append(‘page’, 1);
params.append(‘tags’, ‘javascript’);
params.append(‘tags’, ‘web’);
params.append(‘空参数’, ”); // 包含中文和空值

console.log(params.toString());
// 输出示例: “query=search+term&page=1&tags=javascript&tags=web&%E7%A9%BA%E5%8F%82%E6%95%B0=”
// 注意：空格被编码为 +，中文字符被编码为 %XX 形式，空值参数键名后直接跟等号。
``
这个方法非常重要，因为它生成的就是可以直接附加到 URL?` 后面的标准查询字符串。

6. 遍历 URLSearchParams

URLSearchParams 实现了迭代器协议，这意味着您可以轻松地使用 for...of 循环来遍历其中的参数。它默认会以 [key, value] 数组的形式迭代每一对参数。

“`javascript
const params = new URLSearchParams(‘name=Alice&tag=js&tag=web&city=London’);

console.log(“使用 for…of 遍历 (默认 [key, value]):”);
for (const param of params) {
console.log(param); // 输出例如: [“name”, “Alice”], [“tag”, “js”], [“tag”, “web”], [“city”, “London”]
}

console.log(“\n使用 for…of 解构遍历:”);
for (const [key, value] of params) {
console.log(键: ${key}, 值: ${value});
// 输出: 键: name, 值: Alice
// 键: tag, 值: js
// 键: tag, 值: web
// 键: city, 值: London
}
“`

此外，URLSearchParams 还提供了专门的方法来遍历键、值或键值对：

6.1 keys() 方法

返回一个迭代器，遍历所有的参数键。

javascript
console.log("\n遍历所有键:");
for (const key of params.keys()) {
console.log(key);
// 输出: name, tag, tag, city
}

6.2 values() 方法

返回一个迭代器，遍历所有的参数值。

javascript
console.log("\n遍历所有值:");
for (const value of params.values()) {
console.log(value);
// 输出: Alice, js, web, London
}

6.3 entries() 方法

返回一个迭代器，遍历所有的 [key, value] 键值对数组。这与默认的 for...of 行为相同。

javascript
console.log("\n遍历所有键值对 (entries):");
for (const entry of params.entries()) {
console.log(entry);
// 输出例如: ["name", "Alice"], ["tag", "js"], ["tag", "web"], ["city", "London"]
}
这些迭代方法对于检查或处理所有参数非常有用。

7. 与 URL 对象的集成

URLSearchParams 与 URL 对象是 Web API 中处理 URL 的两大基石，它们经常协同工作。URL 对象有一个 searchParams 属性，它就是 URLSearchParams 的一个实例，代表了 URL 的查询字符串部分。

这允许您方便地从现有 URL 获取 URLSearchParams 实例，或者构建一个新的 URL 对象并操作其参数。

7.1 从当前页面 URL 获取参数

当前页面的 URL 信息可以通过 window.location 对象访问。window.location.search 属性就是当前 URL 的查询字符串（包括开头的 ?）。

“`javascript
// 假设当前页面 URL 是: https://example.com/page?id=123&status=active&tags=new&tags=featured

const currentSearchParams = new URLSearchParams(window.location.search);

console.log(currentSearchParams.get(‘id’)); // 获取 id
console.log(currentSearchParams.get(‘status’)); // 获取 status
console.log(currentSearchParams.getAll(‘tags’)); // 获取所有 tags

// 检查参数是否存在
if (currentSearchParams.has(‘id’)) {
console.log(‘URL 中包含 id 参数’);
}

// 遍历所有参数
console.log(“当前页面 URL 参数:”);
for (const [key, value] of currentSearchParams) {
console.log(${key}: ${value});
}
“`
这是获取当前页面 URL 参数的最推荐方式。

7.2 构建带有参数的新 URL

您可以使用 URL 构造函数来构建 URL，并方便地添加或修改参数。

“`javascript
const baseUrl = ‘https://api.example.com/data’;

// 方法 1: 先创建 URLSearchParams，再构建 URL
const params = new URLSearchParams();
params.append(‘userId’, 456);
params.append(‘type’, ‘report’);
params.append(‘dateRange’, ‘lastMonth’);

const url1 = new URL(baseUrl); // 创建基础 URL 对象
url1.search = params.toString(); // 将 searchParams 转换为字符串赋给 search 属性
console.log(url1.href); // 输出: https://api.example.com/data?userId=456&type=report&dateRange=lastMonth

// 方法 2: 直接在 URL 构造函数中提供参数对象或字符串
const url2 = new URL(‘https://api.example.com/data?existing=param’);
url2.searchParams.set(‘userId’, 456); // 使用 searchParams 属性操作
url2.searchParams.append(‘type’, ‘report’);
url2.searchParams.append(‘type’, ‘summary’);

console.log(url2.href); // 输出: https://api.example.com/data?existing=param&userId=456&type=report&type=summary
``
使用URL对象的searchParams属性是操作 URL 查询字符串参数最现代、最灵活的方式。您可以像操作独立的URLSearchParams实例一样使用get,set,append,delete` 等方法。

7.3 修改现有 URL 的参数

获取到 URL 对象后，修改其 searchParams 属性的内容会自动反映到 URL 的 search 和 href 属性上。

“`javascript
const url = new URL(‘https://example.com/search?q=initial&page=1&category=all’);

console.log(“初始 URL:”, url.href); // 初始 URL: https://example.com/search?q=initial&page=1&category=all

// 修改参数
url.searchParams.set(‘q’, ‘new search term’); // 搜索词修改
url.searchParams.set(‘page’, 2); // 页码改为 2
url.searchParams.delete(‘category’); // 删除分类参数
url.searchParams.append(‘filter’, ‘price’); // 添加过滤参数

console.log(“修改后 URL:”, url.href); // 修改后 URL: https://example.com/search?q=new+search+term&page=2&filter=price
// 注意：修改会自动处理编码，例如空格转为 +
``
这种方式是修改当前页面 URL 或构建新 URL 进行导航（例如window.location.href = url.href）或 Fetch 请求（例如fetch(url)`）的理想方式。

8. 实际应用场景

URLSearchParams 在 Web 开发中有广泛的应用：

• 读取页面状态： 从 URL 参数中读取用户 ID、产品 ID、分页信息、排序方式、筛选条件等，用于初始化页面内容或组件状态。
• 构建 API 请求 URL： 为 GET 请求构建带有查询参数的 URL，例如 fetch('/api/products?' + params.toString())。
• 生成分享链接： 生成带有特定参数的链接，用户点击后可以直接到达具有预设状态的页面。
• 表单提交处理： 虽然 FormData 更常用于 POST 请求，但在处理 GET 请求的表单时，可以将表单数据转换为 URLSearchParams。实际上，new URLSearchParams(new FormData(formElement)) 是一个非常方便的用法。
• 单页应用 (SPA) 路由： 在基于 History API 的前端路由中，可以通过监听 popstate 事件，并解析 location.search 来获取路由参数。

示例：从当前 URL 读取并处理参数

“`javascript
// 假设当前 URL 是: https://mywebapp.com/items?category=electronics&sort=price_asc&page=3&tags=sale&tags=popular

// 获取当前页面的 searchParams 实例
const currentParams = new URLSearchParams(window.location.search);

// 获取单个参数值
const category = currentParams.get(‘category’);
const sortOrder = currentParams.get(‘sort’);
const currentPage = parseInt(currentParams.get(‘page’) || ‘1’, 10); // 获取页码，如果不存在默认为 1

// 获取多个参数值
const tags = currentParams.getAll(‘tags’);

console.log(当前分类: ${category}); // 输出: 当前分类: electronics
console.log(排序方式: ${sortOrder}); // 输出: 排序方式: price_asc
console.log(当前页码: ${currentPage}); // 输出: 当前页码: 3
console.log(标签: ${tags.join(', ')}); // 输出: 标签: sale, popular

// 根据参数值执行相应操作，例如发起数据请求
// fetchData({ category, sortOrder, page: currentPage, tags });
“`

示例：构建一个复杂的 API 请求 URL

“`javascript
const apiEndpoint = ‘/api/filter’;
const filters = {
status: ‘active’,
priority: [‘high’, ‘medium’], // 假设 priority 参数可以有多个值
assigneeId: 101,
keywords: ‘urgent tasks’,
limit: 20,
offset: 0
};

const requestParams = new URLSearchParams();

// 添加简单的键值对
requestParams.set(‘status’, filters.status);
requestParams.set(‘assigneeId’, filters.assigneeId);
requestParams.set(‘limit’, filters.limit);
requestParams.set(‘offset’, filters.offset);

// 添加可能重复的键值对（遍历数组）
if (Array.isArray(filters.priority)) {
filters.priority.forEach(p => {
requestParams.append(‘priority’, p);
});
}

// 添加带有空格或其他特殊字符的键值对
if (filters.keywords) {
requestParams.set(‘keywords’, filters.keywords);
}

// 构建最终的 URL
const requestUrl = ${apiEndpoint}?${requestParams.toString()};

console.log(“构建的 API URL:”);
console.log(requestUrl);
// 输出示例: /api/filter?status=active&assigneeId=101&limit=20&offset=0&priority=high&priority=medium&keywords=urgent+tasks
``
这个例子清晰地展示了如何根据不同的数据结构（单值、多值数组）使用set()和append()来灵活地构建查询字符串，并自动处理了keywords` 中的空格编码。

9. 浏览器兼容性

URLSearchParams 在现代浏览器中（包括 Chrome, Firefox, Safari, Edge 的最新版本）都有良好的支持。对于一些老旧的浏览器（如 IE11），可能需要引入 Polyfill 来提供支持。

您可以通过 caniuse.com 查看详细的兼容性信息。如果您的目标用户群体包含不支持 URLSearchParams 的旧浏览器，建议使用成熟的 Polyfill 库（例如 core-js）来确保兼容性。

10. 总结与优势重申

URLSearchParams 是 JavaScript 中处理 URL 查询字符串参数的现代、标准且强大的工具。与手动进行字符串分割、解析和拼接相比，它具有以下显著优势：

• 代码简洁与可读性： 使用直观的方法名，代码意图清晰，易于理解和维护。
• 避免手动编码/解码： 自动处理 URL 参数的编码和解码，防止了常见的编码错误和潜在的安全问题。
• 健壮性： 能够正确处理各种复杂的查询字符串格式，包括重复参数、空值等。
• 与 URL 对象的无缝集成： 方便地进行更全面的 URL 操作。
• 标准化： 跨浏览器行为一致，减少了兼容性问题（现代浏览器）。

通过本文的详细介绍，您应该已经掌握了 URLSearchParams 的核心概念和常用方法，包括如何创建实例、获取参数（get, getAll, has）、修改参数（set, append, delete, sort）、转换为字符串（toString）以及与 URL 对象的结合使用。

在今后的 Web 开发工作中，无论何时需要处理 URL 查询字符串，强烈推荐您优先考虑使用 URLSearchParams。它将帮助您编写更高效、更健壮、更易于维护的代码。现在就开始在您的项目中实践使用 URLSearchParams 吧，体验它带来的便利！

---