NNext.js 中文网 GitHub

useSearchParams

Pages Router 中 useSearchParams hook 的 API 参考。

useSearchParams 是一个 hook,可让你读取当前 URL 的查询字符串。

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

pages/dashboard.tsx
import { useSearchParams } from 'next/navigation'

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

  if (!searchParams) {
    // 当搜索参数尚不可用时渲染回退 UI
    return null
  }

  const search = searchParams.get('search')

  // URL -> `/dashboard?search=my-project`
  // `search` -> 'my-project'
  return <>Search: {search}</>
}
pages/dashboard.js
import { useSearchParams } from 'next/navigation'

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

  if (!searchParams) {
    // 当搜索参数尚不可用时渲染回退 UI
    return null
  }

  const search = searchParams.get('search')

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

参数#

tsx
const searchParams = useSearchParams()

useSearchParams 不接受任何参数。

返回值#

useSearchParams 返回 URLSearchParams 接口的只读版本,或者在预渲染期间返回 null。

该接口包含用于读取 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 是一个 React Hook,不能与类一起使用。

行为#

预渲染期间的行为#

对于静态优化的页面(不使用 getServerSideProps),useSearchParams 在预渲染期间将返回 null。hydration 之后,该值将更新为实际的搜索参数。

这是因为搜索参数依赖于请求,在静态生成期间无法获知。

pages/dashboard.tsx
import { useSearchParams } from 'next/navigation'

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

  if (!searchParams) {
    // 当搜索参数正在加载时返回回退 UI
    // 这可以防止 hydration 不匹配
    return <DashboardSkeleton />
  }

  const search = searchParams.get('search')

  return <>Search: {search}</>
}
pages/dashboard.js
import { useSearchParams } from 'next/navigation'

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

  if (!searchParams) {
    // 当搜索参数正在加载时返回回退 UI
    // 这可以防止 hydration 不匹配
    return <DashboardSkeleton />
  }

  const search = searchParams.get('search')

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

与 getServerSideProps 一起使用#

使用 getServerSideProps 时,页面会在每次请求时进行服务端渲染,useSearchParams 将立即返回实际的搜索参数:

pages/dashboard.tsx
import { useSearchParams } from 'next/navigation'

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

  // 使用 getServerSideProps 时,这个回退永远不会渲染,因为
  // searchParams 在服务端始终可用。不过,保留
  // 这个回退可以让该组件在其他页面上复用
  // 这些页面可能不使用 getServerSideProps。
  if (!searchParams) {
    return null
  }

  const search = searchParams.get('search')

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

export async function getServerSideProps() {
  return { props: {} }
}
pages/dashboard.js
import { useSearchParams } from 'next/navigation'

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

  // 使用 getServerSideProps 时,这个回退永远不会渲染,因为
  // searchParams 在服务端始终可用。不过,保留
  // 这个回退可以让该组件在其他页面上复用
  // 这些页面可能不使用 getServerSideProps。
  if (!searchParams) {
    return null
  }

  const search = searchParams.get('search')

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

export async function getServerSideProps() {
  return { props: {} }
}

示例#

更新搜索参数#

你可以使用 useRouter hook 来更新搜索参数:

pages/dashboard.tsx
import { useRouter } from 'next/router'
import { useSearchParams } from 'next/navigation'
import { useCallback } from 'react'

export default function Dashboard() {
  const router = useRouter()
  const searchParams = useSearchParams()

  const createQueryString = useCallback(
    (name: string, value: string) => {
      const params = new URLSearchParams(searchParams?.toString())
      params.set(name, value)
      return params.toString()
    },
    [searchParams]
  )

  if (!searchParams) {
    return null
  }

  return (
    <>
      <p>Sort By</p>
      <button
        onClick={() => {
          router.push(router.pathname + '?' + createQueryString('sort', 'asc'))
        }}
      >
        ASC
      </button>
      <button
        onClick={() => {
          router.push(router.pathname + '?' + createQueryString('sort', 'desc'))
        }}
      >
        DESC
      </button>
    </>
  )
}
pages/dashboard.js
import { useRouter } from 'next/router'
import { useSearchParams } from 'next/navigation'
import { useCallback } from 'react'

export default function Dashboard() {
  const router = useRouter()
  const searchParams = useSearchParams()

  const createQueryString = useCallback(
    (name, value) => {
      const params = new URLSearchParams(searchParams?.toString())
      params.set(name, value)
      return params.toString()
    },
    [searchParams]
  )

  if (!searchParams) {
    return null
  }

  return (
    <>
      <p>Sort By</p>
      <button
        onClick={() => {
          router.push(router.pathname + '?' + createQueryString('sort', 'asc'))
        }}
      >
        ASC
      </button>
      <button
        onClick={() => {
          router.push(router.pathname + '?' + createQueryString('sort', 'desc'))
        }}
      >
        DESC
      </button>
    </>
  )
}

与 App Router 共享组件#

来自 next/navigation 的 useSearchParams 在 Pages Router 和 App Router 中都可用。这使你可以创建在任一上下文中都能工作的共享组件:

components/search-bar.tsx
import { useSearchParams } from 'next/navigation'

// 该组件在 pages/ 和 app/ 中都可用
export function SearchBar() {
  const searchParams = useSearchParams()

  if (!searchParams) {
    // Pages Router 在预渲染期间的回退
    return <input defaultValue="" placeholder="Search..." />
  }

  const search = searchParams.get('search') ?? ''

  return <input defaultValue={search} placeholder="Search..." />
}
components/search-bar.js
import { useSearchParams } from 'next/navigation'

// 该组件在 pages/ 和 app/ 中都可用
export function SearchBar() {
  const searchParams = useSearchParams()

  if (!searchParams) {
    // Pages Router 在预渲染期间的回退
    return <input defaultValue="" placeholder="Search..." />
  }

  const search = searchParams.get('search') ?? ''

  return <input defaultValue={search} placeholder="Search..." />
}

小知识:在 App Router 中使用此组件时,请将其包裹在 <Suspense> 边界中,以支持预渲染。

版本历史#

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