useSearchParams

useSearchParams 是一个客户端组件 (Client Component) 钩子，用于读取当前 URL 的查询字符串 (query string)。

useSearchParams 返回 URLSearchParams 接口的只读 (read-only) 版本。

'use client'

import { useSearchParams } from 'next/navigation'

export default function SearchBar() {
  const searchParams = useSearchParams()

  const search = searchParams.get('search')

  // URL -> `/dashboard?search=my-project`
  // `search` -> 'my-project'
  return <>Search: {search}</>
}

参数

const searchParams = useSearchParams()

useSearchParams 不接受任何参数。

返回值

useSearchParams 返回 URLSearchParams 接口的只读 (read-only) 版本，包含用于读取 URL 查询字符串的实用方法：

URLSearchParams.get()：返回与搜索参数关联的第一个值。例如：

URL searchParams.get("a")
/dashboard?a=1 '1'
/dashboard?a= ''
/dashboard?b=3 null
/dashboard?a=1&a=2 '1' - 使用 getAll() 获取所有值
URLSearchParams.has()：返回一个布尔值，表示给定参数是否存在。例如：

URL searchParams.has("a")
/dashboard?a=1 true
/dashboard?b=3 false
了解更多关于 URLSearchParams 的其他只读 (read-only) 方法，包括 getAll()、keys()、values()、entries()、forEach() 和 toString()。

URL	`searchParams.get("a")`
`/dashboard?a=1`	`'1'`
`/dashboard?a=`	`''`
`/dashboard?b=3`	`null`
`/dashboard?a=1&a=2`	`'1'` - 使用 `getAll()` 获取所有值

URL	`searchParams.has("a")`
`/dashboard?a=1`	`true`
`/dashboard?b=3`	`false`

须知：

useSearchParams 是一个客户端组件 (Client Component) 钩子，不支持在服务端组件 (Server Components) 中使用，以防止部分渲染 (partial rendering) 期间出现陈旧值。

如果应用程序包含 /pages 目录，useSearchParams 将返回 ReadonlyURLSearchParams | null。null 值是为了兼容迁移期间的场景，因为在不使用 getServerSideProps 的页面预渲染期间无法获知搜索参数。

静态渲染 (Static Rendering)

如果路由是静态渲染 (statically rendered) 的，调用 useSearchParams 将导致从最近的 Suspense 边界 (boundary) 开始的客户端组件树在客户端渲染。

这样可以在使用 useSearchParams 的动态部分进行客户端渲染的同时，静态渲染路由的一部分。

我们建议将使用 useSearchParams 的客户端组件包裹在 <Suspense/> 边界中。这将允许其上的任何客户端组件作为初始 HTML 的一部分进行静态渲染和发送。示例。

例如：

'use client'

import { useSearchParams } from 'next/navigation'

export default function SearchBar() {
  const searchParams = useSearchParams()

  const search = searchParams.get('search')

  // 使用静态渲染时，这不会在服务器端记录
  console.log(search)

  return <>Search: {search}</>
}

行为

动态渲染 (Dynamic Rendering)

如果路由是动态渲染 (dynamically rendered) 的，useSearchParams 将在客户端组件的初始服务器渲染期间在服务器端可用。

例如：

'use client'

import { useSearchParams } from 'next/navigation'

export default function SearchBar() {
  const searchParams = useSearchParams()

  const search = searchParams.get('search')

  // 这将在初始渲染期间在服务器端记录，
  // 并在后续导航时在客户端记录。
  console.log(search)

  return <>Search: {search}</>
}

须知：将dynamic 路由段配置选项 (route segment config option) 设置为 force-dynamic 可用于强制动态渲染。

服务端组件 (Server Components)

页面 (Pages)

要在页面 (Pages)（服务端组件）中访问搜索参数，请使用 searchParams 属性。

布局 (Layouts)

与页面不同，布局 (Layouts)（服务端组件）不会接收 searchParams 属性。这是因为共享布局在导航期间不会重新渲染，可能导致导航之间的 searchParams 陈旧。查看详细解释。

相反，可以在客户端组件中使用页面 searchParams 属性或 useSearchParams 钩子，这些组件会在客户端重新渲染并获取最新的 searchParams。

示例

更新 `searchParams`

可以使用 useRouter 或 Link 设置新的 searchParams。执行导航后，当前的 page.js 将接收更新的 searchParams 属性。

export default function ExampleClientComponent() {
  const router = useRouter()
  const pathname = usePathname()
  const searchParams = useSearchParams()

  // 通过将当前 searchParams 与提供的键/值对合并，
  // 获取新的 searchParams 字符串
  const createQueryString = useCallback(
    (name: string, value: string) => {
      const params = new URLSearchParams(searchParams.toString())
      params.set(name, value)

      return params.toString()
    },
    [searchParams]
  )

  return (
    <>
      <p>排序方式</p>

      {/* 使用 useRouter */}
      <button
        onClick={() => {
          // <pathname>?sort=asc
          router.push(pathname + '?' + createQueryString('sort', 'asc'))
        }}
      >
        升序
      </button>

      {/* 使用 <Link> */}
      <Link
        href={
          // <pathname>?sort=desc
          pathname + '?' + createQueryString('sort', 'desc')
        }
      >
        降序
      </Link>
    </>
  )
}

版本历史

版本	变更
`v13.0.0`	引入 `useSearchParams`。

On this page