مكون <Link>

<Link> هو مكون React يمتد عنصر HTML <a> لتوفير الجلب المسبق (Prefetching) والتنقل من جانب العميل بين المسارات. وهو الطريقة الأساسية للتنقل بين المسارات في Next.js.

على سبيل المثال، ضع في الاعتبار دليل pages مع الملفات التالية:

• pages/index.js
• pages/about.js
• pages/blog/[slug].js

يمكننا إنشاء رابط لكل من هذه الصفحات كما يلي:

import Link from 'next/link'

function Home() {
  return (
    <ul>
      <li>
        <Link href="/">الرئيسية</Link>
      </li>
      <li>
        <Link href="/about">من نحن</Link>
      </li>
      <li>
        <Link href="/blog/hello-world">مقال المدونة</Link>
      </li>
    </ul>
  )
}

export default Home

الخصائص (Props)

فيما يلي ملخص للخصائص المتاحة لمكون Link:

معلومة مفيدة: يمكن إضافة سمات وسم <a> مثل className أو target="_blank" إلى <Link> كخصائص وسيتم تمريرها إلى العنصر الأساسي <a>.

href (مطلوب)

المسار أو URL للانتقال إليه.

<Link href="/dashboard">لوحة التحكم</Link>

يمكن أن يقبل href كائنًا أيضًا، على سبيل المثال:

// الانتقال إلى /about?name=test
<Link
  href={{
    pathname: '/about',
    query: { name: 'test' },
  }}
>
  حول
</Link>

replace

القيمة الافتراضية false. عندما تكون true، سيستبدل next/link حالة التاريخ الحالية بدلاً من إضافة URL جديد إلى مكدس تاريخ المتصفح.

import Link from 'next/link'

export default function Page() {
  return (
    <Link href="/dashboard" replace>
      لوحة التحكم
    </Link>
  )
}

import Link from 'next/link'

export default function Page() {
  return (
    <Link href="/dashboard" replace>
      لوحة التحكم
    </Link>
  )
}

scroll

القيمة الافتراضية true. السلوك الافتراضي لـ <Link> هو التمرير إلى أعلى المسار الجديد أو الحفاظ على موضع التمرير للتنقل للخلف وللأمام. عندما تكون false، لن يقوم next/link بالتمرير إلى أعلى الصفحة بعد التنقل.

import Link from 'next/link'

export default function Page() {
  return (
    <Link href="/dashboard" scroll={false}>
      لوحة التحكم
    </Link>
  )
}

import Link from 'next/link'

export default function Page() {
  return (
    <Link href="/dashboard" scroll={false}>
      لوحة التحكم
    </Link>
  )
}

prefetch

القيمة الافتراضية true. عندما تكون true، سيقوم next/link بجلب الصفحة (المشار إليها بـ href) مسبقًا في الخلفية. هذا مفيد لتحسين أداء التنقل من جانب العميل. سيتم تحميل أي <Link /> في نطاق الرؤية (مبدئيًا أو عن طريق التمرير) مسبقًا.

يمكن تعطيل الجلب المسبق عن طريق تمرير prefetch={false}. يتم تمكين الجلب المسبق فقط في بيئة الإنتاج.

import Link from 'next/link'

export default function Page() {
  return (
    <Link href="/dashboard" prefetch={false}>
      لوحة التحكم
    </Link>
  )
}

import Link from 'next/link'

export default function Page() {
  return (
    <Link href="/dashboard" prefetch={false}>
      لوحة التحكم
    </Link>
  )
}

خصائص أخرى

legacyBehavior

لم يعد عنصر <a> مطلوبًا كعنصر فرعي لـ <Link>. أضف خاصية legacyBehavior لاستخدام السلوك القديم أو قم بإزالة <a> للترقية. يتوفر أداة تحويل أكواد (codemod) لترقية الكود الخاص بك تلقائيًا.

معلومة مفيدة: عندما لا يتم تعيين legacyBehavior إلى true، يمكن تمرير جميع خصائص وسم anchor إلى next/link أيضًا مثل className، onClick، إلخ.

passHref

يجبر Link على إرسال خاصية href إلى العنصر الفرعي. القيمة الافتراضية false.

scroll

التمرير إلى أعلى الصفحة بعد التنقل. القيمة الافتراضية true.

shallow

تحديث مسار الصفحة الحالية دون إعادة تشغيل getStaticProps، getServerSideProps أو getInitialProps. القيمة الافتراضية false.

locale

يتم إضافة اللغة النشطة تلقائيًا. تسمح locale بتوفير لغة مختلفة. عندما تكون false، يجب أن يتضمن href اللغة حيث يتم تعطيل السلوك الافتراضي.

أمثلة

الربط مع المسارات الديناميكية

بالنسبة للمسارات الديناميكية، يمكن أن يكون استخدام القوالب النصية (template literals) مفيدًا لإنشاء مسار الرابط.

على سبيل المثال، يمكنك إنشاء قائمة من الروابط للمسار الديناميكي pages/blog/[slug].js

import Link from 'next/link'

function Posts({ posts }) {
  return (
    <ul>
      {posts.map((post) => (
        <li key={post.id}>
          <Link href={`/blog/${post.slug}`}>{post.title}</Link>
        </li>
      ))}
    </ul>
  )
}

export default Posts

إذا كان العنصر الفرعي مكونًا مخصصًا يلف وسم <a>

إذا كان العنصر الفرعي لـ Link هو مكون مخصص يلف وسم <a>، فيجب عليك إضافة passHref إلى Link. هذا ضروري إذا كنت تستخدم مكتبات مثل styled-components. بدون هذا، لن يحتوي وسم <a> على سمة href، مما يؤثر على إمكانية الوصول إلى موقعك وقد يؤثر على SEO. إذا كنت تستخدم ESLint، فهناك قاعدة مدمجة next/link-passhref لضمان الاستخدام الصحيح لـ passHref.

import Link from 'next/link'
import styled from 'styled-components'

// هذا ينشئ مكونًا مخصصًا يلف وسم <a>
const RedLink = styled.a`
  color: red;
`

function NavLink({ href, name }) {
  return (
    <Link href={href} passHref legacyBehavior>
      <RedLink>{name}</RedLink>
    </Link>
  )
}

export default NavLink

• إذا كنت تستخدم ميزة JSX pragma الخاصة بـ emotion (@jsx jsx)، فيجب عليك استخدام passHref حتى إذا كنت تستخدم وسم <a> مباشرة.
• يجب أن يدعم المكون خاصية onClick لتنشيط التنقل بشكل صحيح

إذا كان العنصر الفرعي مكونًا وظيفيًا

إذا كان العنصر الفرعي لـ Link هو مكون وظيفي، بالإضافة إلى استخدام passHref و legacyBehavior، يجب عليك تغليف المكون في React.forwardRef:

import Link from 'next/link'

// `onClick`, `href`, و `ref` يجب تمريرها إلى عنصر DOM
// للمعالجة الصحيحة
const MyButton = React.forwardRef(({ onClick, href }, ref) => {
  return (
    <a href={href} onClick={onClick} ref={ref}>
      انقر هنا
    </a>
  )
})

function Home() {
  return (
    <Link href="/about" passHref legacyBehavior>
      <MyButton />
    </Link>
  )
}

export default Home

مع كائن URL

يمكن أن يتلقى Link أيضًا كائن URL وسيقوم تلقائيًا بتنسيقه لإنشاء سلسلة URL. إليك كيفية القيام بذلك:

import Link from 'next/link'

function Home() {
  return (
    <ul>
      <li>
        <Link
          href={{
            pathname: '/about',
            query: { name: 'test' },
          }}
        >
          من نحن
        </Link>
      </li>
      <li>
        <Link
          href={{
            pathname: '/blog/[slug]',
            query: { slug: 'my-post' },
          }}
        >
          مقال المدونة
        </Link>
      </li>
    </ul>
  )
}

export default Home

يحتوي المثال أعلاه على رابط إلى:

• مسار محدد مسبقًا: /about?name=test
• مسار ديناميكي: /blog/my-post

يمكنك استخدام كل خاصية كما هو موضح في توثيق وحدة Node.js URL.

استبدال URL بدلاً من الإضافة

السلوك الافتراضي لمكون Link هو push عنوان URL جديد إلى مكدس history. يمكنك استخدام خاصية replace لمنع إضافة إدخال جديد، كما في المثال التالي:

<Link href="/about" replace>
  من نحن
</Link>

تعطيل التمرير إلى أعلى الصفحة

السلوك الافتراضي لـ Link هو التمرير إلى أعلى الصفحة. عندما يكون هناك hash محدد، سيقوم بالتمرير إلى id معين، مثل وسم <a> العادي. لمنع التمرير إلى الأعلى / hash، يمكن إضافة scroll={false} إلى Link:

<Link href="/#hashid" scroll={false}>
  تعطيل التمرير إلى الأعلى
</Link>

Middleware

من الشائع استخدام Middleware للمصادقة أو أغراض أخرى تتضمن إعادة توجيه المستخدم إلى صفحة مختلفة. لكي يعمل مكون <Link /> بشكل صحيح في جلب الروابط مع إعادة الكتابة عبر Middleware، تحتاج إلى إخبار Next.js بكل من URL المعروض وURL المطلوب جلبها مسبقًا. هذا مطلوب لتجنب طلبات الجلب غير الضرورية إلى middleware لمعرفة المسار الصحيح للجلب المسبق.

على سبيل المثال، إذا كنت تريد تقديم مسار /dashboard الذي يحتوي على واجهات للمستخدمين المصادق عليهم والزوار، يمكنك إضافة شيء مشابه لما يلي في Middleware الخاص بك لإعادة توجيه المستخدم إلى الصفحة الصحيحة:

export function middleware(req) {
  const nextUrl = req.nextUrl
  if (nextUrl.pathname === '/dashboard') {
    if (req.cookies.authToken) {
      return NextResponse.rewrite(new URL('/auth/dashboard', req.url))
    } else {
      return NextResponse.rewrite(new URL('/public/dashboard', req.url))
    }
  }
}

في هذه الحالة، سترغب في استخدام الكود التالي في مكون <Link /> الخاص بك:

import Link from 'next/link'
import useIsAuthed from './hooks/useIsAuthed'

export default function Page() {
  const isAuthed = useIsAuthed()
  const path = isAuthed ? '/auth/dashboard' : '/dashboard'
  return (
    <Link as="/dashboard" href={path}>
      لوحة التحكم
    </Link>
  )
}

معلومة مفيدة: إذا كنت تستخدم المسارات الديناميكية، فستحتاج إلى تكييف خصائص as و href. على سبيل المثال، إذا كان لديك مسار ديناميكي مثل /dashboard/[user] تريد عرضه بشكل مختلف عبر middleware، ستكتب: <Link href={{ pathname: '/dashboard/authed/[user]', query: { user: username } }} as="/dashboard/[user]">الملف الشخصي</Link>.

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