useSearchParams

useSearchParams geçerli URL'nin sorgu dizesini okumanızı sağlayan bir İstemci Bileşeni kancasıdır.

useSearchParams 'nin salt okunur bir sürümünü döndürür. URLSearchParams arayüz.

app/dashboard/search-bar.tsx
'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}</>
}

Parameters 

const searchParams = useSearchParams()

useSearchParams herhangi bir parametre almaz.

Returns

useSearchParams 'nin salt okunur bir sürümünü döndürür. URLSearchParams arayüzü, URL'nin sorgu dizesini okumak için yardımcı yöntemler içerir:

Bildiğim iyi oldu:

  • useSearchParams bir İstemci Bileşe ni kancasıdır ve kısmi oluşturma sırasında eski değerleri önlemek için Sunucu Bileşenlerinde desteklenmez.
  • Bir uygulama /pages dizinini içeriyorsa, useSearchParams değeri ReadonlyURLSearchParams | null değerini döndürür. null değeri geçiş sırasında uyumluluk içindir, çünkü arama parametreleri kullanmayan bir sayfanın ön oluşturma işlemi sırasında bilinemez getServerSideProps

Static Rendering

Bir rota statik olarak işleniyorsa, useSearchParams çağrısı, en yakın Suspense sınırına kadar olan İstemci Bileşeni ağacının istemci tarafında işlenmesine neden olur.

Bu, rotanın bir kısmının statik olarak işlenmesini sağlarken, useSearchParams adresini kullanan dinamik kısım istemci tarafında işlenir.

useSearchParams kullanan İstemci Bileşenini bir <Suspense/> sınırına sarmanızı öneririz. Bu, üzerindeki tüm İstemci Bileşenlerinin statik olarak işlenmesine ve ilk HTML'nin bir parçası olarak gönderilmesine olanak tanıyacaktır. Örnek.

Örneğin:

app/dashboard/search-bar.tsx
'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}</>
}
app/dashboard/page.tsx
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>
    </>
  )
}

Behavior

Dynamic Rendering

Bir rota dinamik olarak işleniyorsa, İstemci Bileşeninin ilk sunucu işlenmesi sırasında useSearchParams sunucuda kullanılabilir olacaktır.

Örneğin:

app/dashboard/search-bar.tsx
'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}</>
}
app/dashboard/page.tsx
import SearchBar from './search-bar'
 
export const dynamic = 'force-dynamic'
 
export default function Page() {
  return (
    <>
      <nav>
        <SearchBar />
      </nav>
      <h1>Dashboard</h1>
    </>
  )
}

Bilmekte fayda var: dynamic route segment config seçeneğini force-dynamic olarak ayarlamak dinamik oluşturmayı zorlamak için kullanılabilir.

Server Components

Pages

Sayfalardaki (Sunucu Bileşenleri) arama parametrelerine erişmek için searchParams prop.

Layouts

Sayfaların aksine, Düzenler (Sunucu Bileşenleri) searchParams prop'unu almaz. Bunun nedeni, paylaşılan bir düzenin gezinme sırasında yeniden işlenmemesidir, bu da gezinmeler arasında searchParams adresinin bayatlamasına neden olabilir. Ayrıntılı açıklamayı görüntüleyin.

Bunun yerine, Sayfa searchParams pervane veya useSearchParams istemcide en son searchParams ile yeniden oluşturulan bir İstemci Bileşenindeki kanca.

Examples

Updating searchParams

Kullanabilirsiniz useRouter veya Link yeni searchParams ayarlamak için. Bir navigasyon gerçekleştirildikten sonra, mevcut page.js güncellenmiş bir searchParams prop alacaktır.

app/example-client-component.tsx
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>
    </>
  )
}

Version History

VersionChanges
v13.0.0useSearchParams introduced.