react19中setSearchParams的5种传参实现

 更新时间:2026年08月06日 09:16:14   作者:朝阳39  
本文深入讲解setSearchParams的5种传参写法,包括如何用回调保留原有参数,以及replace配置避免历史记录堆积,掌握这些技巧,轻松实现分页、筛选和搜索功能,告别手动编码和页面跳转的坑

一、基础介绍

import { useSearchParams } from 'react-router-dom'
// 解构:searchParams读取参数,setSearchParams修改URL查询参数
const [searchParams, setSearchParams] = useSearchParams()

作用:原地修改当前页面 ? 后的查询参数,不跳转新页面,组件自动重渲染

  • 自动编码中文/特殊符号(不用手动 encodeURIComponent)
  • 读取时自动解码(不用 decodeURIComponent)
  • 对比 navigate('/?xxx'):navigate 会新增历史记录;setSearchParams 可选择替换历史

二、5种传参写法

1. 传对象(最常用,简单场景)

直接传键值对,会完全覆盖原有所有参数

// URL 变为 /?if_login=true&name=朝阳
setSearchParams({
  if_login: 'true',
  name: '测试&首页' // 内部自动编码
})

2. 回调函数写法(保留原有参数,分页/筛选必备)

重点!直接传对象会清空旧参数;用回调可以基于当前参数修改、保留其他参数

// 当前URL:/?if_login=true&sort=price
setSearchParams(prev => {
  // prev 是原始 searchParams 对象(URLSearchParams)
  prev.set('page', '2') // 新增/修改page,保留if_login、sort
  prev.set('name', '朝阳')
  return prev
})
// 结果:/?if_login=true&sort=price&page=2&name=%E6%9C%9D%E9%98%B3

常用操作:

setSearchParams(prev => {
  prev.set('page', 1) // 修改
  prev.delete('sort') // 删除某个参数
  return prev
})

3. 传 URLSearchParams 实例

适合复杂多参数批量处理

const params = new URLSearchParams()
params.set('if_login', 'true')
params.set('name', '朝阳')
setSearchParams(params)

4. 传查询字符串

setSearchParams("if_login=true&name=朝阳")
setSearchParams("?if_login=true&name=朝阳") // 带?也兼容

5. 传二维数组(支持同一个key多个值)

setSearchParams([
  ['page', '1'],
  ['tag', 'react'],
  ['tag', 'router']
])
// ?page=1&tag=react&tag=router

三、第二个配置参数 { replace: true }

默认:修改参数会新增一条历史记录,点返回会回到上一个参数状态
replace: true:替换当前历史记录,回退直接跳上一页(分页、筛选推荐)

// 替换模式,不增加历史栈
setSearchParams({ page: 3 }, { replace: true })

// 回调搭配replace
setSearchParams(prev => {
  prev.set('page', 3)
  return prev
}, { replace: true })

四、实战完整示例(贴合你之前的 name=朝阳 案例)

import { useSearchParams } from 'react-router-dom'

export default function Page() {
  const [searchParams, setSearchParams] = useSearchParams()
  
  // 读取参数,自动解码
  const name = searchParams.get('name')
  const isLogin = searchParams.get('if_login')

  // 按钮修改参数(保留原有其他参数)
  const updateQuery = () => {
    setSearchParams(prev => {
      prev.set('if_login', 'true')
      prev.set('name', '测试&首页') // 自动编码特殊符号
      return prev
    }, { replace: true })
  }

  // 清空所有参数
  const clearQuery = () => setSearchParams({})

  return (
    <div>
      <p>name参数:{name}</p>
      <button onClick={updateQuery}>设置参数 if_login & name</button>
      <button onClick={clearQuery}>清空所有查询参数</button>
    </div>
  )
}

五、核心坑点(必看)

坑1:直接传对象会清空全部旧参数

// 当前地址 ?a=1&b=2
setSearchParams({ c: 3 })
// 结果:?c=3  a、b直接消失!

✅ 解决:用回调函数 (prev) => {} 操作原有参数

坑2、编解码完全内置,无需手动处理

  • 写入:setSearchParams 自动 encodeURIComponent
  • 读取:searchParams.get() / Object.fromEntries(searchParams) 自动解码
    不要额外套 encode/decode,会出现双重转义bug

坑3、所有值最终都会转为字符串

数字、布尔传入会变成字符串:

setSearchParams({ page: 2 })
searchParams.get('page') // "2" 字符串,不是数字

坑4、删除参数方式

// 方式1:回调delete(推荐,保留其他参数)
setSearchParams(prev => {
  prev.delete('name')
  return prev
})
// 方式2:重新传对象覆盖(会清空其他参数)
setSearchParams({ if_login: 'true' })

六、对比 navigate 修改参数

  1. navigate(/?page=2)
    • 完整跳转,新增历史记录
    • 必须手动拼接字符串,自己处理编码
  2. setSearchParams({page:2})
    • 原地更新URL,组件刷新
    • 内置编解码,可保留旧参数、可替换历史
      分页、筛选、搜索框联动优先用 setSearchParams

七、配合 Object.fromEntries 一键获取所有参数

const [searchParams] = useSearchParams()
const query = Object.fromEntries(searchParams)
console.log(query.name, query.if_login)

到此这篇关于react19中setSearchParams的5种传参实现的文章就介绍到这了,更多相关react19 setSearchParams内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家!

相关文章

  • 详解react-router-dom v6版本基本使用介绍

    详解react-router-dom v6版本基本使用介绍

    本文主要介绍了react-router-dom v6版本基本使用介绍,文中通过示例代码介绍的非常详细,具有一定的参考价值,感兴趣的小伙伴们可以参考一下
    2022-03-03
  • 用React实现一个完整的TodoList的示例代码

    用React实现一个完整的TodoList的示例代码

    本篇文章主要介绍了用React实现一个完整的TodoList的示例代码,小编觉得挺不错的,现在分享给大家,也给大家做个参考。一起跟随小编过来看看吧
    2017-10-10
  • 在React Router中使用JWT的实现

    在React Router中使用JWT的实现

    本文主要介绍了在React Router中使用JWT的实现,包括创建AuthProvider和AuthContext,实现ProtectedRoute组件,以及在React项目中处理公共路由和受校验保护路由,下面就来详细的介绍一下
    2026-06-06
  • react-router-dom入门使用教程(前端路由原理)

    react-router-dom入门使用教程(前端路由原理)

    这篇文章主要介绍了react-router-dom入门使用教程,主要包括react路由相关理解,本文通过实例代码给大家介绍的非常详细,对大家的学习或工作具有一定的参考借鉴价值,需要的朋友可以参考下
    2022-08-08
  • React的组件协同使用实现方式

    React的组件协同使用实现方式

    这篇文章主要介绍了React的组件协同使用,文中给大家提到在React开发中,有哪些场景的组件协同?又如何去实现组件的协同使用呢?本文都给大家提到,感兴趣的朋友跟随小编一起看看吧
    2021-09-09
  • 解读useState第二个参数的"第二个参数"

    解读useState第二个参数的"第二个参数"

    这篇文章主要介绍了useState第二个参数的"第二个参数",具有很好的参考价值,希望对大家有所帮助,如有错误或未考虑完全的地方,望不吝赐教
    2024-03-03
  • React Use Hook 库使用指南

    React Use Hook 库使用指南

    React Use 是一个包含了大量实用React Hook的开源库,由streamich开发并维护,这个库旨在提供一系列用于处理常见功能如动画、传感器、副作用管理等的React Hooks,通过使用这些Hooks,开发者可以更简洁地在函数组件中实现复杂逻辑,提升开发效率
    2026-06-06
  • react+antd.3x实现ip输入框

    react+antd.3x实现ip输入框

    这篇文章主要为大家详细介绍了react+antd.3x实现ip输入框,文中示例代码介绍的非常详细,具有一定的参考价值,感兴趣的小伙伴们可以参考一下
    2021-10-10
  • Redux模块化拆分reducer函数流程介绍

    Redux模块化拆分reducer函数流程介绍

    Reducer是个纯函数,即只要传入相同的参数,每次都应返回相同的结果。不要把和处理数据无关的代码放在Reducer里,让Reducer保持纯净,只是单纯地执行计算,这篇文章主要介绍了Redux拆分reducer函数流程
    2022-09-09
  • 解决React报错Property 'X' does not exist on type 'HTMLElement'

    解决React报错Property 'X' does not 

    这篇文章主要为大家介绍了解决React报错Property 'X' does not exist on type 'HTMLElement',有需要的朋友可以借鉴参考下,希望能够有所帮助,祝大家多多进步,早日升职加薪
    2022-12-12

最新评论