useSearchParams

useSearchParams ist ein Client Component-Hook, der es ermöglicht, die aktuelle Query-String der URL auszulesen.

useSearchParams gibt eine schreibgeschützte Version der URLSearchParams-Schnittstelle zurück.

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

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

Parameter

const searchParams = useSearchParams()

useSearchParams benötigt keine Parameter.

Rückgabewert

useSearchParams gibt eine schreibgeschützte Version der URLSearchParams-Schnittstelle zurück, die Hilfsmethoden zum Auslesen des Query-Strings der URL enthält:

URLSearchParams.get(): Gibt den ersten Wert zurück, der mit dem Suchparameter verknüpft ist. Beispiel:

URL searchParams.get("a")
/dashboard?a=1 '1'
/dashboard?a= ''
/dashboard?b=3 null
/dashboard?a=1&a=2 '1' - verwenden Sie getAll() für alle Werte
URLSearchParams.has(): Gibt einen booleschen Wert zurück, der angibt, ob der Parameter existiert. Beispiel:

URL searchParams.has("a")
/dashboard?a=1 true
/dashboard?b=3 false
Erfahren Sie mehr über andere schreibgeschützte Methoden von URLSearchParams, einschließlich getAll(), keys(), values(), entries(), forEach() und toString().

URL	`searchParams.get("a")`
`/dashboard?a=1`	`'1'`
`/dashboard?a=`	`''`
`/dashboard?b=3`	`null`
`/dashboard?a=1&a=2`	`'1'` - verwenden Sie `getAll()` für alle Werte

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

Wissenswert:

useSearchParams ist ein Client Component-Hook und wird nicht unterstützt in Server Components, um veraltete Werte während des Partial Rendering zu vermeiden.

Wenn eine Anwendung das /pages-Verzeichnis enthält, gibt useSearchParams ReadonlyURLSearchParams | null zurück. Der null-Wert dient der Kompatibilität während der Migration, da Suchparameter während des Pre-Rendering einer Seite, die getServerSideProps nicht verwendet, nicht bekannt sein können.

Verhalten

Statisches Rendering

Wenn eine Route statisch gerendert wird, führt der Aufruf von useSearchParams() dazu, dass der Baum bis zur nächsten Suspense-Grenze clientseitig gerendert wird.

Dadurch kann ein Teil der Seite statisch gerendert werden, während der dynamische Teil, der searchParams verwendet, clientseitig gerendert wird.

Sie können den clientseitig gerenderten Anteil der Route reduzieren, indem Sie die Komponente, die useSearchParams verwendet, in eine Suspense-Grenze einwickeln. Beispiel:

'use client'

import { useSearchParams } from 'next/navigation'

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

  const search = searchParams.get('search')

  // Dies wird nicht auf dem Server protokolliert, wenn statisches Rendering verwendet wird
  console.log(search)

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

'use client'

import { useSearchParams } from 'next/navigation'

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

  const search = searchParams.get('search')

  // Dies wird nicht auf dem Server protokolliert, wenn statisches Rendering verwendet wird
  console.log(search)

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

import { Suspense } from 'react'
import SearchBar from './search-bar'

// Diese Komponente wird als Fallback für die Suspense-Grenze
// anstelle der Suchleiste im initialen HTML gerendert.
// Wenn der Wert während der React-Hydration verfügbar ist, wird der Fallback
// durch die `<SearchBar>`-Komponente ersetzt.
function SearchBarFallback() {
  return <>placeholder</>
}

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

import { Suspense } from 'react'
import SearchBar from './search-bar'

// Diese Komponente wird als Fallback für die Suspense-Grenze
// anstelle der Suchleiste im initialen HTML gerendert.
// Wenn der Wert während der React-Hydration verfügbar ist, wird der Fallback
// durch die `<SearchBar>`-Komponente ersetzt.
function SearchBarFallback() {
  return <>placeholder</>
}

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

Dynamisches Rendering

Wenn eine Route dynamisch gerendert wird, ist useSearchParams auf dem Server während des initialen Server-Renderings der Client-Komponente verfügbar.

Wissenswert: Die Einstellung der dynamic Route Segment Config Option auf force-dynamic kann verwendet werden, um dynamisches Rendering zu erzwingen.

Beispiel:

'use client'

import { useSearchParams } from 'next/navigation'

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

  const search = searchParams.get('search')

  // Dies wird auf dem Server während des initialen Renderings protokolliert
  // und auf dem Client bei nachfolgenden Navigationen.
  console.log(search)

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

'use client'

import { useSearchParams } from 'next/navigation'

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

  const search = searchParams.get('search')

  // Dies wird auf dem Server während des initialen Renderings protokolliert
  // und auf dem Client bei nachfolgenden Navigationen.
  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>
    </>
  )
}

import SearchBar from './search-bar'

export const dynamic = 'force-dynamic'

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

Im Gegensatz zu Seiten erhalten Layouts (Server-Komponenten) keine searchParams-Prop. Dies liegt daran, dass ein gemeinsames Layout während der Navigation nicht neu gerendert wird, was zu veralteten searchParams zwischen Navigationen führen könnte. Siehe detaillierte Erklärung.

Verwenden Sie stattdessen die Page searchParams-Prop oder den useSearchParams-Hook in einer Client-Komponente, die mit den neuesten searchParams auf dem Client neu gerendert wird.

Beispiele

Aktualisieren von `searchParams`

Sie können useRouter oder Link verwenden, um neue searchParams zu setzen. Nach einer Navigation erhält die aktuelle page.js eine aktualisierte searchParams-Prop.

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

  // Erstellt einen neuen searchParams-String durch Zusammenführen der aktuellen
  // searchParams mit einem bereitgestellten Schlüssel/Wert-Paar
  const createQueryString = useCallback(
    (name: string, value: string) => {
      const params = new URLSearchParams(searchParams)
      params.set(name, value)

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

  return (
    <>
      <p>Sortieren nach</p>

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

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

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

  // Erstellt einen neuen searchParams-String durch Zusammenführen der aktuellen
  // searchParams mit einem bereitgestellten Schlüssel/Wert-Paar
  const createQueryString = useCallback(
    (name, value) => {
      const params = new URLSearchParams(searchParams)
      params.set(name, value)

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

  return (
    <>
      <p>Sortieren nach</p>

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

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

Versionsverlauf

Version	Änderungen
`v13.0.0`	`useSearchParams` eingeführt.

On this page