logoNext.js العربية
التوثيقالمدونةالتعلم
مقدمة/مرجع API/الدوال (Functions)/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().

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

التصيير الثابت (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)

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

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

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

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

أمثلة

تحديث searchParams

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

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>
    </>
  )
}
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 لخطاف `useSelectedLayoutSegment`.