logoNext.js العربية
التوثيقالمدونةالتعلم
مقدمة/مرجع API/الدوال/useSearchParams

useSearchParams

useSearchParams هو خطاف لمكون العميل (Client Component) يتيح لك قراءة سلسلة الاستعلام (query string) لـ 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}</>
}
'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(): تُرجع القيمة الأولى المرتبطة بمعامل البحث. على سبيل المثال:

    URLsearchParams.get("a")
    /dashboard?a=1'1'
    /dashboard?a=''
    /dashboard?b=3null
    /dashboard?a=1&a=2'1' - استخدم getAll() للحصول على جميع القيم

  • URLSearchParams.has(): تُرجع قيمة منطقية تشير إلى وجود المعامل المحدد. على سبيل المثال:

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

  • تعرف على المزيد حول طرق القراءة فقط الأخرى لـ URLSearchParams، بما في ذلك getAll()، keys()، values()، entries()، forEach()، و toString().

معلومة مفيدة:

  • useSearchParams هو خطاف لمكون العميل (Client Component) وغير مدعوم في مكونات الخادم (Server Components) لمنع قيم قديمة أثناء التصيير الجزئي.
  • إذا كان التطبيق يتضمن دليل /pages، فسيُرجع useSearchParams ReadonlyURLSearchParams | null. القيمة null هي لأغراض التوافق أثناء الترحيل حيث لا يمكن معرفة معلمات البحث أثناء التصيير المسبق لصفحة لا تستخدم getServerSideProps.

السلوك

التصيير الثابت (Static Rendering)

إذا كان المسار مصيرًا بشكل ثابت، فإن استدعاء 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')

  // لن يتم تسجيل هذا على الخادم عند استخدام التصيير الثابت
  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')

  // لن يتم تسجيل هذا على الخادم عند استخدام التصيير الثابت
  console.log(search)

  return <>Search: {search}</>
}
import { Suspense } from 'react'
import SearchBar from './search-bar'

// هذا المكون الممرر كاحتياطي لحدود Suspense
// سيتم تصييره بدلاً من شريط البحث في HTML الأولي.
// عندما تصبح القيمة متاحة أثناء تهيئة React، سيتم استبدال
// الاحتياطي بمكون `<SearchBar>`.
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'

// هذا المكون الممرر كاحتياطي لحدود Suspense
// سيتم تصييره بدلاً من شريط البحث في HTML الأولي.
// عندما تصبح القيمة متاحة أثناء تهيئة React، سيتم استبدال
// الاحتياطي بمكون `<SearchBar>`.
function SearchBarFallback() {
  return <>placeholder</>
}

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

التصيير الديناميكي (Dynamic Rendering)

إذا كان المسار مصيرًا بشكل ديناميكي، فسيكون useSearchParams متاحًا على الخادم أثناء التصيير الأولي لمكون العميل.

على سبيل المثال:

'use client'

import { useSearchParams } from 'next/navigation'

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

  const search = searchParams.get('search')

  // سيتم تسجيل هذا على الخادم أثناء التصيير الأولي
  // وعلى العميل أثناء عمليات التنقل اللاحقة.
  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')

  // سيتم تسجيل هذا على الخادم أثناء التصيير الأولي
  // وعلى العميل أثناء عمليات التنقل اللاحقة.
  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>
    </>
  )
}

معلومة مفيدة: يمكن استخدام خيار dynamic لقطاع المسار بقيمة force-dynamic لإجبار التصيير الديناميكي.

مكونات الخادم (Server Components)

الصفحات (Pages)

للوصول إلى معلمات البحث في الصفحات (مكونات الخادم)، استخدم خاصية searchParams.

التخطيطات (Layouts)

على عكس الصفحات، لا تتلقى التخطيطات (مكونات الخادم) خاصية searchParams. هذا لأن التخطيط المشترك لا يتم إعادة تصييره أثناء التنقل مما قد يؤدي إلى searchParams قديمة بين عمليات التنقل. عرض التفسير التفصيلي.

بدلاً من ذلك، استخدم خاصية الصفحة searchParams أو خطاف useSearchParams في مكون عميل، والذي يتم إعادة تصييره على العميل بأحدث searchParams.

أمثلة

تحديث searchParams

يمكنك استخدام useRouter أو Link لتعيين searchParams جديدة. بعد تنفيذ التنقل، ستتلقى الصفحة الحالية page.js خاصية searchParams محدثة.

'use client'

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

  // الحصول على سلسلة searchParams جديدة عن طريق دمج
  // searchParams الحالية مع زوج مفتاح/قيمة معطى
  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>

      {/* باستخدام useRouter */}
      <button
        onClick={() => {
          // <pathname>?sort=asc
          router.push(pathname + '?' + createQueryString('sort', 'asc'))
        }}
      >
        ASC
      </button>

      {/* باستخدام <Link> */}
      <Link
        href={
          // <pathname>?sort=desc
          pathname + '?' + createQueryString('sort', 'desc')
        }
      >
        DESC
      </Link>
    </>
  )
}
'use client'

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

  // الحصول على سلسلة searchParams جديدة عن طريق دمج
  // searchParams الحالية مع زوج مفتاح/قيمة معطى
  const createQueryString = useCallback(
    (name, value) => {
      const params = new URLSearchParams(searchParams)
      params.set(name, value)

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

  return (
    <>
      <p>Sort By</p>

      {/* باستخدام useRouter */}
      <button
        onClick={() => {
          // <pathname>?sort=asc
          router.push(pathname + '?' + createQueryString('sort', 'asc'))
        }}
      >
        ASC
      </button>

      {/* باستخدام <Link> */}
      <Link
        href={
          // <pathname>?sort=desc
          pathname + '?' + createQueryString('sort', 'desc')
        }
      >
        DESC
      </Link>
    </>
  )
}

سجل الإصدارات

الإصدارالتغييرات
v13.0.0تم تقديم useSearchParams.

useRouter

مرجع API لخطاف useRouter.

useSelectedLayoutSegment

مرجع API لـ hook استخدام useSelectedLayoutSegment.