跳到内容
API 参考函数useSearchParams

useSearchParams

useSearchParams 是一个 客户端组件 Hook，可让您读取当前 URL 的查询字符串。

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}</>
}

参数 

const searchParams = useSearchParams()

useSearchParams 不接受任何参数。

返回值

useSearchParams 返回 URLSearchParams 接口的只读版本，其中包括用于读取 URL 查询字符串的实用程序方法

须知:

  • useSearchParams 是一个 客户端组件 Hook，不支持在 服务器组件 中使用，以防止在部分渲染期间出现过时的值。
  • 如果应用程序包含 /pages 目录，则 useSearchParams 将返回 ReadonlyURLSearchParams | null。null 值是为了在迁移期间保持兼容性，因为在使用 getServerSideProps 的页面的预渲染期间，搜索参数是未知的

行为

静态渲染

如果路由是静态渲染的，则调用 useSearchParams 将导致客户端组件树一直到最近的 Suspense 边界进行客户端渲染。

这允许路由的一部分静态渲染，而使用 useSearchParams 的动态部分在客户端渲染。

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

例如

app/dashboard/search-bar.tsx
'use client'
 
import { useSearchParams } from 'next/navigation'
 
export default function SearchBar() {
  const searchParams = useSearchParams()
 
  const search = searchParams.get('search')
 
  // This will not be logged on the server when using static rendering
  console.log(search)
 
  return <>Search: {search}</>
}
app/dashboard/page.tsx
import { Suspense } from 'react'
import SearchBar from './search-bar'
 
// This component passed as a fallback to the Suspense boundary
// will be rendered in place of the search bar in the initial HTML.
// When the value is available during React hydration the fallback
// will be replaced with the `<SearchBar>` component.
function SearchBarFallback() {
  return <>placeholder</>
}
 
export default function Page() {
  return (
    <>
      <nav>
        <Suspense fallback={<SearchBarFallback />}>
          <SearchBar />
        </Suspense>
      </nav>
      <h1>Dashboard</h1>
    </>
  )
}

动态渲染

如果路由是动态渲染的，则在客户端组件的初始服务器渲染期间，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')
 
  // This will be logged on the server during the initial render
  // and on the client on subsequent navigations.
  console.log(search)
 
  return <>Search: {search}</>
}
app/dashboard/page.tsx
import SearchBar from './search-bar'
 
export const dynamic = 'force-dynamic'
 
export default function Page() {
  return (
    <>
      <nav>
        <SearchBar />
      </nav>
      <h1>Dashboard</h1>
    </>
  )
}

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

服务器组件

页面

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

布局

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

相反，请使用页面 searchParams 属性或客户端组件中的 useSearchParams Hook，它会在客户端使用最新的 searchParams 重新渲染。

示例

更新 searchParams

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

app/example-client-component.tsx
'use client'
 
export default function ExampleClientComponent() {
  const router = useRouter()
  const pathname = usePathname()
  const searchParams = useSearchParams()
 
  // Get a new searchParams string by merging the current
  // searchParams with a provided key/value pair
  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>
 
      {/* using useRouter */}
      <button
        onClick={() => {
          // <pathname>?sort=asc
          router.push(pathname + '?' + createQueryString('sort', 'asc'))
        }}
      >
        ASC
      </button>
 
      {/* using <Link> */}
      <Link
        href={
          // <pathname>?sort=desc
          pathname + '?' + createQueryString('sort', 'desc')
        }
      >
        DESC
      </Link>
    </>
  )
}

版本历史

版本变更
v13.0.0引入 useSearchParams。