URLSearchParams 生成重复参数怎么保留多个值

在筛选页里，用户可能同时选择多个标签，最终地址希望是 ?tag=js&tag=web&tag=api。要保留这种重复参数，关键是对同一个键连续调用 URLSearchParams.append()，读取时用 getAll()；不要用 set() 反复写入，因为它会把旧值替换掉。

用 append 逐个加入同名参数

URLSearchParams 不是只能保存一个键对应一个值的普通对象。它维护的是有顺序的键值条目，因此同一个键可以出现多次。

const params = new URLSearchParams();

// 同一个键逐项追加，保留用户选择的顺序。
for (const tag of ["js", "web", "api"]) {
  params.append("tag", tag);
}

// 把编码后的查询串交给 URL，而不是手写 & 和转义字符。
const url = new URL("https://example.com/search");
url.search = params;

console.log(params.toString());
console.log(url.href);

输出：tag=js&tag=web&tag=api
地址：https://example.com/search?tag=js&tag=web&tag=api

append、set 和 getAll 的语义不要混用

遇到“后一次选择覆盖前一次选择”的代码，通常是把 append 写成了 set。两者都接收键和值，但目的不同。

因此，服务端或前端状态确实允许多选时，读取代码应明确表达“全量”：

const selected = params.getAll("tag");

// getAll 返回数组；空数组表示查询串里没有这个键。
if (selected.length === 0) {
  console.log("没有筛选标签");
} else {
  console.log(selected.join("、"));
}

从数组或表单选项构造重复参数

最容易踩的坑是直接写 new URLSearchParams({ tag: ["js", "web"] })。这种对象初始化会把数组当成一个普通值，常见结果是 tag=js%2Cweb，它不是两个独立的 tag。

多选表单应把每个值单独追加。键名是否需要写成 tag[]，取决于后端框架的解析约定；URLSearchParams 只负责生成查询字符串，不替你决定服务端的数据结构。

const checkedTags = ["js", "web"];
const query = new URLSearchParams();

// 每个选项都是一条独立记录，避免数组被隐式转成逗号字符串。
for (const value of checkedTags) {
  query.append("tag", value);
}

const requestUrl = `/api/articles?${query.toString()}`;
console.log(requestUrl);

把参数交给 URL 或 fetch 并检查后端约定

如果已有基础地址，优先让 URL 管理查询串；如果直接用于请求，也可以把 params 转成字符串。这样空格、中文和特殊字符会按 URL 规则编码。

const params = new URLSearchParams();
params.append("tag", "前端");
params.append("tag", "性能");

// fetch 发送的是已经编码好的重复参数。
const response = await fetch(`/api/articles?${params}`);
if (!response.ok) {
  throw new Error(`请求失败：${response.status}`);
}
const data = await response.json();

后端联调时重点确认三件事：它是否支持重复键；它把重复键解析成数组还是只取最后一个；空数组和缺少参数是否有不同业务含义。前端生成正确，不代表后端一定按多值读取。

相关问题

为什么 get 只拿到一个值？

get 的语义就是返回第一个匹配值。需要多选结果时使用 getAll，不要在读取之后再猜测是否还有重复键。

重复参数可以保持顺序吗？

可以。连续 append 的条目会按插入顺序出现在查询串中，迭代和 getAll 也会保留这个顺序。

什么时候应该用 set？

当一个键在业务上只能有一个当前值，例如分页页码、排序方式或单选状态时，用 set 更能表达覆盖意图。