useSearchParams

useSearchParams ist ein Client Component Hook, der es ermöglicht, die Query-Parameter der aktuellen 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}</>
}

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 der Query-Parameter 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' - verwende getAll() für alle Werte

• URLSearchParams.has(): Gibt einen booleschen Wert zurück, der angibt, ob der gegebene Parameter existiert. Beispiel:

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

• Erfahre mehr über andere schreibgeschützte Methoden von URLSearchParams, einschließlich getAll(), keys(), values(), entries(), forEach() und toString().

Wissenswert:

• useSearchParams ist ein Client Component-Hook und wird in Server Components nicht unterstützt, um veraltete Werte während des partiellen Renderings 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 Query-Parameter während des Pre-Renderings 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 Client Component-Baum bis zur nächsten Suspense-Grenze clientseitig gerendert wird.

Dies ermöglicht es, einen Teil der Route statisch zu rendern, während der dynamische Teil, der useSearchParams verwendet, clientseitig gerendert wird.

Wir empfehlen, die Client Component, die useSearchParams verwendet, in eine <Suspense/>-Grenze zu wrappen. Dadurch können alle darüber liegenden Client Components statisch gerendert und als Teil des initialen HTML gesendet werden. Beispiel.

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 nicht geloggt, wenn statisches Rendering verwendet wird
  console.log(search)

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

Dynamisches Rendering

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

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
  // und auf dem Client bei nachfolgenden Navigationen geloggt.
  console.log(search)

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

Wissenswert: Die Option dynamic route segment config kann auf force-dynamic gesetzt werden, um dynamisches Rendering zu erzwingen.

Server Components

Seiten

Um in Pages (Server Components) auf Query-Parameter zuzugreifen, verwende die searchParams-Prop.

Layouts

Im Gegensatz zu Seiten erhalten Layouts (Server Components) 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.

Verwende stattdessen die searchParams-Prop der Page oder den useSearchParams-Hook in einer Client Component, die auf dem Client mit den neuesten searchParams neu gerendert wird.

Beispiele

Aktualisieren von searchParams

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

'use client'

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.toString())
      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