urlsearchparams 是浏览器原生 url 查询参数操作接口,支持自动编码、增删改查,适用于多选过滤场景;可从当前 url、对象或数组初始化,用 append/delete 精准控制多值参数,配合 pushstate/replacestate 更新地址栏,并通过 popstate 监听变化、getall 获取全部值以同步 ui。

URLSearchParams 是浏览器原生提供的 URL 查询参数操作接口,特别适合处理多选过滤场景(如商品筛选、标签组合、状态叠加等)。它能避免手动拼接字符串的错误,自动编码,且天然支持增删改查,让地址栏参数管理变得清晰可控。
初始化:从当前 URL 或空对象创建参数实例
直接读取当前页面地址中的查询参数,或从零开始构建:
-
从当前 URL 获取:
const params = new URLSearchParams(window.location.search) -
从对象初始化:
const params = new URLSearchParams({ category: 'shoes', brand: 'nike' })(注意:值会自动 URL 编码) -
从数组初始化(适合多值同名参数):
new URLSearchParams([['tag', 'vue'], ['tag', 'react']])→?tag=vue&tag=react
添加/切换多选参数:用 append 和 delete 精准控制
多选过滤的核心是「勾选即追加、取消即移除」,不能用 set()(会覆盖同名所有值):
-
添加一个选项(允许重复):
params.append('color', 'red') -
移除某一项(指定键+值):
params.delete('color', 'red') -
批量移除某个键的所有值:
params.delete('color') -
判断是否已存在某项:
params.has('size', 'xl')(需传值才校验具体项)
例如用户点击「红色」标签:先检查 params.has('color', 'red'),存在则 delete,否则 append —— 实现开关逻辑。
同步更新地址栏:replaceState + pushState 控制历史记录
修改参数后,需显式更新 URL,但不触发页面刷新:
-
替换当前历史条目(不增加记录):
history.replaceState(null, '', `?${params}`) -
新增历史条目(支持后退):
history.pushState(null, '', `?${params}`) -
注意:
params.toString()自动返回合法查询字符串(已编码、& 分隔),无需手动拼接
推荐在筛选交互中使用 pushState,方便用户用浏览器前后按钮回溯不同筛选组合。
解析与响应:监听 URL 变化并还原 UI 状态
用户手动修改地址栏或点击浏览器前进/后退时,需监听 popstate 并同步界面:
-
监听路由变化:
window.addEventListener('popstate', () => { const params = new URLSearchParams(window.location.search); restoreFilters(params); }) -
遍历所有同名参数值:
[...params.getAll('tag')]→ 返回['vue', 'ts']数组,适合渲染多选高亮 -
清空某类筛选时,可批量 delete:
params.delete('price'); params.delete('rating')
还原 UI 时,不要只依赖 get()(只取第一个),多选场景一律用 getAll() 获取完整值列表。










