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 على جانب العميل.

هذا يسمح بتصيير جزء من الصفحة بشكل ثابت بينما الجزء الديناميكي الذي يستخدم searchParams يتم تصييره على جانب العميل.

يمكنك تقليل الجزء من المسار الذي يتم تصييره على جانب العميل عن طريق تغليف المكون الذي يستخدم useSearchParams في حد Suspense. على سبيل المثال:

'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 سيكون متاحًا على الخادم أثناء التصيير الأولي لمكون العميل.

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

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

'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>
    </>
  )
}

مكونات الخادم (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)
      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.