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 من جانب العميل (مثل useState) أو حالة المتصفح (مثل موضع التمرير).
router.prefetch(href: string): جلب مسبق (Prefetch) للمسار المحدد لتحقيق انتقالات أسرع من جانب العميل.
router.back(): التنقل للخلف إلى المسار السابق في سجل المتصفح.
router.forward(): التنقل للأمام إلى الصفحة التالية في سجل المتصفح.

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

يجب ألا ترسل عناوين URL غير موثوقة أو غير معالجة إلى router.push أو router.replace، لأن هذا قد يعرض موقعك لثغرات البرمجة النصية عبر المواقع (XSS). على سبيل المثال، سيتم تنفيذ عناوين URL مثل javascript: المرسلة إلى router.push أو router.replace في سياق صفحتك.

يقوم مكون <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 '...'
}

والتي يمكن استيرادها في تخطيط (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()