urlsearchparams.append 是向 url 查询字符串安全添加参数的方法,自动编码、支持重复键和数组追加,并可结合现有 url 使用。

URLSearchParams.append 是专门用来向 URL 查询字符串中添加参数的方法,它会自动处理编码、重复键的追加,比手动拼接更安全可靠。
基础用法:添加单个参数
创建 URLSearchParams 实例后,直接调用 append(key, value),value 会被自动 URL 编码:
const params = new URLSearchParams();
params.append('q', '前端开发');
params.append('page', '2');
console.log(params.toString()); // "q=%E5%89%8D%E7%AB%AF%E5%BC%80%E5%8F%91&page=2"
动态追加多个参数(对象遍历)
把参数对象的每个键值对循环 append 进去,适合从配置或表单数据生成查询串:
const filters = {
category: 'js',
sort: 'date-desc',
tag: 'es6',
active: true
};
const params = new URLSearchParams();
Object.entries(filters).forEach(([key, value]) => {
params.append(key, String(value));
});
console.log(params.toString()); // "category=js&sort=date-desc&tag=es6&active=true"
处理数组参数(如多选标签)
同一个 key 多次调用 append,会生成多个同名参数,后端通常能识别为数组:
- 比如用户选了 ['react', 'vue', 'svelte'],期望生成
tag=react&tag=vue&tag=svelte - 直接遍历数组并多次 append 即可
const tags = ['react', 'vue', 'svelte'];
const params = new URLSearchParams();
tags.forEach(tag => params.append('tag', tag));
console.log(params.toString()); // "tag=react&tag=vue&tag=svelte"
结合现有 URL 一起使用
如果已有 URL,可以先提取其 search 部分初始化 URLSearchParams,再 append 新参数:
const url = new URL('https://example.com/list?category=web');
const params = new URLSearchParams(url.search);
params.append('limit', '10');
params.append('offset', '20');
url.search = params.toString();
console.log(url.href); // "https://example.com/list?category=web&limit=10&offset=20"










