useRouter

يسمح لك خطاف useRouter بتغيير المسارات برمجيًا داخل مكونات العميل (Client Components).

توصية: استخدم مكون <Link> للتنقل إلا إذا كان لديك متطلب محدد لاستخدام useRouter.

'use client'

import { useRouter } from 'next/navigation'

export default function Page() {
  const router = useRouter()

  return (
    <button type="button" onClick={() => router.push('/dashboard')}>
      Dashboard
    </button>
  )
}

'use client'

import { useRouter } from 'next/navigation'

export default function Page() {
  const router = useRouter()

  return (
    <button type="button" onClick={() => router.push('/dashboard')}>
      Dashboard
    </button>
  )
}

`useRouter()`

router.push(href: string, { scroll: boolean }): تنفيذ تنقل من جانب العميل إلى المسار المحدد. يضيف إدخالًا جديدًا إلى سجل المتصفح (browser’s history).
router.replace(href: string, { scroll: boolean }): تنفيذ تنقل من جانب العميل إلى المسار المحدد دون إضافة إدخال جديد إلى سجل المتصفح (browser’s history stack).
router.refresh(): تحديث المسار الحالي. يتم إجراء طلب جديد إلى الخادم، وإعادة جلب طلبات البيانات، وإعادة عرض مكونات الخادم. سيقوم العميل بدمج حمولة مكون خادم React المحدثة دون فقدان حالة React من جانب العميل (مثل useState) أو حالة المتصفح (مثل موضع التمرير).
router.prefetch(href: string): الجلب المسبق (Prefetch) للمسار المحدد لتحقيق انتقالات أسرع من جانب العميل.
router.back(): التنقل للخلف إلى المسار السابق في سجل المتصفح.
router.forward(): التنقل للأمام إلى الصفحة التالية في سجل المتصفح.

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

يقوم مكون <Link> تلقائيًا بجلب المسارات مسبقًا عندما تصبح مرئية في نافذة العرض.

يمكن أن يعيد refresh() نفس النتيجة إذا كانت طلبات الجلب مخزنة مؤقتًا. قد تغير الوظائف الديناميكية الأخرى مثل cookies و headers أيضًا الاستجابة.

الانتقال من `next/router`

يجب استيراد خطاف useRouter من next/navigation وليس من next/router عند استخدام موجه التطبيق (App Router)
تمت إزالة سلسلة pathname واستبدالها بـ usePathname()
تمت إزالة كائن query واستبداله بـ useSearchParams()
تم استبدال router.events. انظر أدناه.

عرض دليل الانتقال الكامل.

أمثلة

أحداث الموجه (Router events)

يمكنك الاستماع لتغييرات الصفحة عن طريق تكوين خطافات أخرى لمكون العميل مثل usePathname و useSearchParams.

app/components/navigation-events.js

'use client'

import { useEffect } from 'react'
import { usePathname, useSearchParams } from 'next/navigation'

export function NavigationEvents() {
  const pathname = usePathname()
  const searchParams = useSearchParams()

  useEffect(() => {
    const url = `${pathname}?${searchParams}`
    console.log(url)
    // يمكنك الآن استخدام URL الحالي
    // ...
  }, [pathname, searchParams])

  return null
}

والتي يمكن استيرادها في تخطيط (layout).

app/layout.js

import { Suspense } from 'react'
import { NavigationEvents } from './components/navigation-events'

export default function Layout({ children }) {
  return (
    <html lang="en">
      <body>
        {children}

        <Suspense fallback={null}>
          <NavigationEvents />
        </Suspense>
      </body>
    </html>
  )
}

معلومة مفيدة: تم تغليف <NavigationEvents> في حدود Suspense لأن useSearchParams() يتسبب في العرض من جانب العميل حتى حدود Suspense الأقرب أثناء العرض الثابت (static rendering). معرفة المزيد.

تعطيل استعادة التمرير

بشكل افتراضي، سيقوم Next.js بالتمرير إلى أعلى الصفحة عند التنقل إلى مسار جديد. يمكنك تعطيل هذا السلوك عن طريق تمرير scroll: false إلى router.push() أو router.replace().

'use client'

import { useRouter } from 'next/navigation'

export default function Page() {
  const router = useRouter()

  return (
    <button
      type="button"
      onClick={() => router.push('/dashboard', { scroll: false })}
    >
      Dashboard
    </button>
  )
}

'use client'

import { useRouter } from 'next/navigation'

export default function Page() {
  const router = useRouter()

  return (
    <button
      type="button"
      onClick={() => router.push('/dashboard', { scroll: false })}
    >
      Dashboard
    </button>
  )
}

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

الإصدار	التغييرات
`v13.0.0`	تم تقديم `useRouter` من `next/navigation`.

useRouter()