NNext.js 中文网 GitHub

useSearchParams

useSearchParams hook 的 API 参考。

useSearchParams 是一个 Client Component hook,可让你读取当前 URL 的 查询字符串(query string)。

useSearchParams 返回 URLSearchParams 接口的只读版本。

app/dashboard/search-bar.tsx
'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}</>
}
app/dashboard/search-bar.js
'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}</>
}

参数#

tsx
const searchParams = useSearchParams()

useSearchParams 不接受任何参数。

返回值#

useSearchParams 返回 URLSearchParams 接口的只读版本,其中包含用于读取 URL 查询字符串的实用方法:

URLsearchParams.get("a")
/dashboard?a=1'1'
/dashboard?a=''
/dashboard?b=3null
/dashboard?a=1&a=2'1' - 使用 getAll() 获取所有值
URLsearchParams.has("a")
/dashboard?a=1true
/dashboard?b=3false

小知识:

  • useSearchParams 是一个 Client Component hook,在 Server Components 中不受支持,以防止在部分渲染期间出现过期值。
  • 如果你想在 Server Component 中根据搜索参数获取数据,通常更好的做法是读取对应页面的 searchParams prop。然后你可以通过 props 将它传递给该页面中的任何组件(Server 或 Client)。
  • 如果应用程序包含 /pages 目录,useSearchParams 将返回 ReadonlyURLSearchParams | null。null 值是为了迁移期间的兼容性,因为对于不使用 getServerSideProps 的页面,在预渲染期间无法获知搜索参数。

行为#

预渲染#

如果路由是预渲染的,调用 useSearchParams 将导致 Client Component 树直到最近的 Suspense 边界为止的部分都进行客户端渲染。

这使得路由的一部分可以被预渲染,而使用 useSearchParams 的动态部分则进行客户端渲染。

使用 Cache Components 时,只有当路由的其余部分被预渲染时,该边界才会进行客户端渲染。如果路由上的任何组件读取请求数据(例如 cookies()),Next.js 会在请求时在服务端使用该真实搜索参数渲染该边界。要让读取仅浏览器可用 API(例如 sessionStorage)的组件不参与服务端渲染,请改用 use(browser()),而不要依赖 useSearchParams 边界。

我们建议将使用 useSearchParams 的 Client Component 包裹在 <Suspense/> 边界中。这样可以让其之上的任何 Client Component 都被预渲染并作为初始 HTML 的一部分发送。

有关完整的修复选项和权衡,请参阅 Next.js 在 Suspense 之外的 Client Component 中遇到 URL 数据。

例如:

app/dashboard/search-bar.tsx
'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}</>
}
app/dashboard/search-bar.js
'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}</>
}
app/dashboard/page.tsx
import { Suspense } from 'react'
import SearchBar from './search-bar'

// 作为 fallback 传递给 Suspense 边界的这个组件
// 将在初始 HTML 中渲染,以代替搜索栏。
// 当 React hydration 期间该值可用时,fallback
// 将被 `<SearchBar>` 组件替换。
function SearchBarFallback() {
  return <>placeholder</>
}

export default function Page() {
  return (
    <>
      <nav>
        <Suspense fallback={<SearchBarFallback />}>
          <SearchBar />
        </Suspense>
      </nav>
      <h1>Dashboard</h1>
    </>
  )
}
app/dashboard/page.js
import { Suspense } from 'react'
import SearchBar from './search-bar'

// 作为 fallback 传递给 Suspense 边界的这个组件
// 将在初始 HTML 中渲染,以代替搜索栏。
// 当 React hydration 期间该值可用时,fallback
// 将被 `<SearchBar>` 组件替换。
function SearchBarFallback() {
  return <>placeholder</>
}

export default function Page() {
  return (
    <>
      <nav>
        <Suspense fallback={<SearchBarFallback />}>
          <SearchBar />
        </Suspense>
      </nav>
      <h1>Dashboard</h1>
    </>
  )
}

小知识:

  • 在开发环境中,路由是按需渲染的,因此 useSearchParams 不会 suspend,即使没有 Suspense,一切也可能看起来正常工作。
  • 在生产构建期间,从 Client Component 调用 useSearchParams 的静态页面必须包裹在 Suspense 边界中,否则构建会失败,并出现 Missing Suspense boundary with useSearchParams 错误。
  • 如果你希望路由进行动态渲染,最好先在 Server Component 中使用 connection 函数等待传入的请求,这会将下面的所有内容排除在预渲染之外。请参阅动态渲染指南,了解是什么让路由成为动态路由。
  • 如果你已经在 Server Component 页面中,请考虑使用 searchParams prop 并将值传递给 Client Component。
  • 你也可以将页面的 searchParams prop 直接传递给 Client Component,并使用 React 的 use() 进行解包。尽管这会 suspend,因此该 Client Component 应该包裹在 Suspense 边界中。

动态渲染#

如果路由是动态渲染的,在 Client Component 的初始服务端渲染期间,useSearchParams 在服务端是可用的。

例如:

app/dashboard/search-bar.tsx
'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}</>
}
app/dashboard/search-bar.js
'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}</>
}
app/dashboard/page.tsx
import { connection } from 'next/server'
import SearchBar from './search-bar'

export default async function Page() {
  await connection()
  return (
    <>
      <nav>
        <SearchBar />
      </nav>
      <h1>Dashboard</h1>
    </>
  )
}
app/dashboard/page.js
import { connection } from 'next/server'
import SearchBar from './search-bar'

export default async function Page() {
  await connection()
  return (
    <>
      <nav>
        <SearchBar />
      </nav>
      <h1>Dashboard</h1>
    </>
  )
}

小知识:

  • 以前,在页面上设置 export const dynamic = 'force-dynamic' 用于强制动态渲染。现在更推荐使用 connection(),因为它在语义上将动态渲染与传入的请求关联起来。

Server Components#

页面#

要在页面(Server Components)中访问搜索参数,请使用 searchParams prop。

布局#

与页面不同,布局(Server Components)不会接收 searchParams prop。这是因为共享布局在导航时不会重新渲染,这可能导致导航之间出现过期值。查看详细说明。

相反,请在 Client Component 中使用页面的 searchParams prop 或 useSearchParams hook,它们会在客户端使用最新的 searchParams 重新渲染。

示例#

更新 searchParams#

你可以使用 useRouter 或 Link 来设置新的 searchParams。导航执行后,当前的 page.js 将接收到更新后的 searchParams prop。

app/example-client-component.tsx
'use client'

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>Sort By</p>

      
      <button
        onClick={() => {
          // <pathname>?sort=asc
          router.push(pathname + '?' + createQueryString('sort', 'asc'))
        }}
      >
        ASC
      </button>

      
      <Link
        href={
          // <pathname>?sort=desc
          pathname + '?' + createQueryString('sort', 'desc')
        }
      >
        DESC
      </Link>
    </>
  )
}
app/example-client-component.js
'use client'

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

  // 通过将当前的 searchParams 与提供的键/值对合并,
  // 得到一个新的 searchParams 字符串
  const createQueryString = useCallback(
    (name, value) => {
      const params = new URLSearchParams(searchParams)
      params.set(name, value)

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

  return (
    <>
      <p>Sort By</p>

      
      <button
        onClick={() => {
          // <pathname>?sort=asc
          router.push(pathname + '?' + createQueryString('sort', 'asc'))
        }}
      >
        ASC
      </button>

      
      <Link
        href={
          // <pathname>?sort=desc
          pathname + '?' + createQueryString('sort', 'desc')
        }
      >
        DESC
      </Link>
    </>
  )
}

版本历史#

版本变更
v13.0.0引入 useSearchParams。
Next.js 中文网