useSearchParams

useSearchParams это хук компонента клиента, который позволяет читать текущую строку запроса URL.

useSearchParams возвращает только для чтения версию интерфейса URLSearchParams.

'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:

• 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, включая getAll(), keys(), values(), entries(), forEach() и toString().

Важно знать:

• useSearchParams — это хук компонента клиента, и он не поддерживается в серверных компонентах для предотвращения устаревших значений во время частичного рендеринга.
• Если приложение включает директорию /pages, useSearchParams вернет ReadonlyURLSearchParams | null. Значение null предназначено для совместимости при миграции, так как параметры поиска нельзя узнать во время предварительного рендеринга страницы, которая не использует getServerSideProps

Статический рендеринг

Если маршрут статически рендерится, вызов useSearchParams приведет к тому, что дерево компонента клиента до ближайшего Suspense будет рендериться на стороне клиента.

Это позволяет статически рендерить часть маршрута, а динамическую часть, использующую useSearchParams, рендерить на стороне клиента.

Рекомендуется оборачивать компонент клиента, использующий useSearchParams, в <Suspense/>. Это позволит статически рендерить все компоненты над ним и отправить их как часть начального HTML. Пример.

Например:

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

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 будет доступен на сервере во время первоначального рендеринга сервера компонента клиента.

Например:

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

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 в компоненте клиента, который перерисовывается на клиенте с последними searchParams.

Примеры

Обновление searchParams

Вы можете использовать useRouter или Link, чтобы установить новые searchParams. После выполнения навигации текущая page.js получит обновленное свойство searchParams.

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

История версий