Menu

useSearchParams

useSearchParams ist ein Client Component-Hook, mit dem die Query-Parameter der aktuellen URL ausgelesen werden können.

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

app/dashboard/search-bar.tsx
TypeScript
'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 Lesen der Query-Parameter der URL enthält:

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

    URLsearchParams.get("a")
    /dashboard?a=1'1'
    /dashboard?a=''
    /dashboard?b=3null
    /dashboard?a=1&a=2'1' - verwende getAll() für alle Werte

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

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

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

Hinweis:

  • useSearchParams ist ein Client Component-Hook und wird in Server Components nicht unterstützt, um veraltete Werte während des teilweisen Renderns zu verhindern.
  • 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-Renderings einer Seite, die kein getServerSideProps 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 einzuwickeln. Dies ermöglicht es, dass alle darüber liegenden Client Components statisch gerendert und als Teil des initialen HTMLs gesendet werden. Beispiel.

Zum Beispiel:

app/dashboard/search-bar.tsx
TypeScript
'use client'
 
import { useSearchParams } from 'next/navigation'
 
export default function SearchBar() {
  const searchParams = useSearchParams()
 
  const search = searchParams.get('search')
 
  // Dies wird bei statischem Rendering nicht auf dem Server protokolliert
  console.log(search)
 
  return <>Search: {search}</>
}
app/dashboard/page.tsx
TypeScript
import { Suspense } from 'react'
import SearchBar from './search-bar'
 
// Diese Komponente, die als Fallback an die Suspense-Grenze übergeben wird,
// wird im initialen HTML anstelle der Suchleiste 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 während des initialen Server-Renderings der Client Component auf dem Server verfügbar.

Zum Beispiel:

app/dashboard/search-bar.tsx
TypeScript
'use client'
 
import { useSearchParams } from 'next/navigation'
 
export default function SearchBar() {
  const searchParams = useSearchParams()
 
  const search = searchParams.get('search')
 
  // Dies wird während des initialen Renderns auf dem Server
  // und bei nachfolgenden Navigationen auf dem Client protokolliert.
  console.log(search)
 
  return <>Search: {search}</>
}
app/dashboard/page.tsx
TypeScript
import SearchBar from './search-bar'
 
export const dynamic = 'force-dynamic'
 
export default function Page() {
  return (
    <>
      <nav>
        <SearchBar />
      </nav>
      <h1>Dashboard</h1>
    </>
  )
}

Hinweis: Das Setzen der dynamic-Route-Segment-Konfigurationsoption auf force-dynamic kann verwendet werden, um dynamisches Rendering zu erzwingen.

Server Components

Pages

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

Layouts

Im Gegensatz zu Pages erhalten Layouts (Server Components) nicht die searchParams-Prop. Dies liegt daran, dass ein gemeinsam genutztes 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 Page-searchParams-Prop oder den useSearchParams-Hook in einer Client Component, die auf dem Client mit den aktuellen 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.

app/example-client-component.tsx
TypeScript
'use client'
 
export default function ExampleClientComponent() {
  const router = useRouter()
  const pathname = usePathname()
  const searchParams = useSearchParams()
 
  // Einen neuen searchParams-String durch Zusammenführen der aktuellen
  // searchParams mit einem bereitgestellten Schlüssel/Wert-Paar erhalten
  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>
 
      {/* mit useRouter */}
      <button
        onClick={() => {
          // <pathname>?sort=asc
          router.push(pathname + '?' + createQueryString('sort', 'asc'))
        }}
      >
        ASC
      </button>
 
      {/* mit <Link> */}
      <Link
        href={
          // <pathname>?sort=desc
          pathname + '?' + createQueryString('sort', 'desc')
        }
      >
        DESC
      </Link>
    </>
  )
}

Versionshistorie

VersionÄnderungen
v13.0.0useSearchParams eingeführt.