عرض مصدر Next.js/next link

<noinclude>{{DISPLAYTITLE:الواجهة البرمجية للمكوّن <code>next/link</code> في Next.js}}</noinclude>
<blockquote>ننصحك قبل قراءة المقال بالاطلاع على [[Next.js/Routing|التوجيه في Next.js]] أولًا.</blockquote>بإمكانك تفعيل التنقل بين الصفحات أو الوجهات في جانب العميل عبر المكوّن <code>Link</code> الذي تصدّره المكتبة <code>next/link</code>.

لنفترض وجود الملفات التالية في المجلد <code>pages</code>:

* <code>pages/index.js</code>
* <code>pages/about.js</code>
* <code>pages/blog/[slug].js</code>

يمكننا الحصول على رابط إلى كل صفحة من هذه الصفحات كالتالي:<syntaxhighlight lang="javascript">
import Link from 'next/link'

function Home() {
  return (
    <ul>
      <li>
        <Link href="/">Home</Link>
      </li>
      <li>
        <Link href="/about">About Us</Link>
      </li>
      <li>
        <Link href="/blog/hello-world">Blog Post</Link>
      </li>
    </ul>
  )
}

export default Home
</syntaxhighlight>

يقبل المكوّن <code>Link</code> الخاصيات التالية:

* <code>href</code>: المسار أو عنوان URL الذي سننتقل إليه. وهذه الخاصية هي الوحيدة التي نحتاجها، كما يمكن أن تكون كائنًا (كائن URL).
* <code>as</code>: منسّق اختياري للمسار الذي سيُعرض في شريط عناوين المتصفح. استُخدم هذا المعامل سابقًا للتوجه الديناميكي ما قبل الإصدار 9.5.3. '''ملاحظة''': إن اختلف المسار هذا المعطى عن المسار المعطى في href فإن سلوك <code>href</code>/<code>as</code> القديم المستخدم في ذلك الإصدار هو الذي سيُستخدم، فارجع إلى [https://nextjs.org/docs/tag/v9.5.2/api-reference/next/link#dynamic-routes التوثيق القديم].
* legacyBehavior: يغير السلوك ويعود للسلوك القديم الذي يتطلب وجود عنصر <code><a></code> ابن، ويأخذ القيمة الافتراضية <code>false</code>.
* <code>passHref</code>: يجبر المكوّن <code>Link</code> على إرسال الخاصية <code>href</code> إلى أبناءه، ويأخذ القيمة الافتراضية <code>false</code>.
* <code>prefetch</code>: يحضر الصفحة مسبقًا وراء الستار، ويأخذ القيمة الافتراضية <code>true</code>. كما سيُعاد تحميل أي مكوّن <code></ Link></code> ظاهر في نافذة العرض (في البداية أو عند التمرير). يمكن تعطيل هذه الخاصية بتمرير القيمة <code>prefetch={false}</code>. وعندما تأخذ الخاصية <code>prefetch</code> القيمة <code>false</code>، ستستمر عملية الإحضار المسبق عند مرور مؤشر الفأرة فوق العنصر hovering. ستعيد الصفحات التي تستخدم التوليد [[Next.js/data fetching#.D8.A7.D9.84.D8.AA.D9.88.D9.84.D9.8A.D8.AF%20.D8.A7.D9.84.D8.B3.D8.A7.D9.83.D9.86%20.D9.84.D9.84.D8.B5.D9.81.D8.AD.D8.A7.D8.AA%20.D9.81.D9.8A%20Next.js%20.D8.A8.D8.A7.D8.B3.D8.AA.D8.AE.D8.AF.D8.A7.D9.85%20.D8.A7.D9.84.D8.AF.D8.A7.D9.84.D8.A9%20getStaticProps|الساكن توليد]] ملفات <code>JSON</code> مع البيانات لتسريع عملية الانتقال بين الصفحات. تُفعّل الخاصية <code>prefetch</code> في مرحلة الإنتاج فقط.
* <code>replace</code>: يستبدل حالة سجل العناوين history بدلًا من إضافة عنوان url جديد إلى المكدّس، ويأخذ القيمة الافتراضية <code>false</code>.
* <code>scroll</code>: يتحكم بالتمرير إلى أعلى الصفحة بعد الانتقال، وقيمته الافتراضية <code>true</code>.
* [[Next.js/Routing|<code>shallow</code>]]: يُحدّث مسار الصفحة الحالية دون تنفيذ الدوال <code>getStaticProps</code> أو <code>getServerSideProps</code> أو <code>getInitialProps</code>، وقيمته الافتراضية <code>false</code>.
* <code>locale</code>: يُستخدم الإعداد المحلي المُفعَّل تلقائيًا. كما يمكنك استخدامها لتغيير هذا الإعداد. عندما تأخذ الخاصية القيمة <code>false</code> يجب أن تحدد الخاصية <code>href</code> الإعداد المحلي بما أن السلوك الافتراضي قد تعطل آنذاك.

== حالة وجود أجزاء ديناميكية في الوجهة ==
لا ينبغي عليك تنفيذ أي عملية محددة عندما ترتبط إلى [[Next.js/Routing#.D8.A7.D9.84.D9.88.D8.AC.D9.87.D8.A7.D8.AA%20.D8.A7.D9.84.D8.AF.D9.8A.D9.86.D8.A7.D9.85.D9.8A.D9.83.D9.8A.D8.A9%20.D9.81.D9.8A%20Next.js|الوجهات الديناميكية]] بما في ذلك [[Next.js/Routing#.D8.A7.D9.84.D9.88.D8.AC.D9.87.D8.A7.D8.AA%20.D8.A7.D9.84.D8.AF.D9.8A.D9.86.D8.A7.D9.85.D9.8A.D9.83.D9.8A.D8.A9%20.D9.81.D9.8A%20Next.js|التقاط جميع الوجهات]]، وذلك اعتبارًا من النسخة 9.5.3. لكن قد يكون مفيدًا في بعض الأحيان استخدام [[Next.js/Routing#.D8.A7.D9.84.D8.A7.D8.B1.D8.AA.D8.A8.D8.A7.D8.B7%20.D8.A8.D9.85.D8.B3.D8.A7.D8.B1.D8.A7.D8.AA%20.D8.AF.D9.8A.D9.86.D8.A7.D9.85.D9.8A.D9.83.D9.8A.D8.A9|الاستدلال]] interpolation أو كائن URL لتوليد الرابط.

ستطابق الوجهة الديناميكية <code>pages/blog/[slug].js</code> مثلًا الرابط التالي:<syntaxhighlight lang="javascript">
import Link from 'next/link'

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

export default Posts
</syntaxhighlight>

== حالة وجود مكون <code><a></code> ابن مخصص للمكون <code>link</code> ==
إليك المثال التالي الذي يمثل هذه الحالة:<syntaxhighlight lang="javascript">
import Link from 'next/link'

function Legacy() {
  return (
    <Link href="/about" legacyBehavior>
      <a>About Us</a>
    </Link>
  )
}

export default Legacy
</syntaxhighlight>

== حالة وجود مكون ابن مخصص للمكون <code>link</code> مغلف بالعنصر <code><a></code> ==
لا بد في هذه الحالة من إضافة الخاصية <code>passHref</code> إلى المكوّن <code>link</code>، وهذا ضروري إن كنت تستخدم مكتبات مثل [https://styled-components.com/ styled-components]. لن يمتلك العنصر <code><a></code> دون أن تفعل ذلك السمة <code>href</code>، الأمر الذي يسيء إلى سهولة وصول موقعك وقد يؤثر على نتيجة البحث SEO. وفي حال استخدمت المدقق [[Next.js/eslint|ESLint]]، تأكد من استخدام القاعدة <code>next/link-passhref</code> للتأكد من الاستخدام الصحيح للخاصية <code>passHref</code>:<syntaxhighlight lang="javascript">
import Link from 'next/link'
import styled from 'styled-components'

// <a> يُنشئ ذلك مكوّن مخصص يغلف العنصر 
const RedLink = styled.a`
  color: red;
`
function NavLink({ href, name }) {
  //Link إلى الرابط href لا بد من إضافة 
  return (
    <Link href={href} passHref legacyBehavior>
      <RedLink>{name}</RedLink>
    </Link>
  )
}

export default NavLink
</syntaxhighlight>

* لا بد أيضًا من استخدام الخاصية <code>passHref</code> إن كنت ستعمل مع الميزة <code>jsx jsx@</code> العائدة لمكتبة التنسيق [https://emotion.sh/ emotion] حتى لو استخدمت <code><a></code> مباشرة.
* يجب أن يدعم المكوّن الخاصية <code>onClick</code> كي يقع حدث التنقل بالطريقة الصحيحة.

== الحالة التي يكون فيها ابن المكون <code>link</code> مكون دالة ==
لا بد في هذه الحالة من تغليف المكوّن ضمن <code>[[React/react api#reactforwardref|React.forwardRef]]</code> إضافةً إلى استخدام الخاصية <code>passHref</code> والخاصية <code>legacyBehavior</code>:<syntaxhighlight lang="javascript">
import Link from 'next/link'

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

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

export default Home
</syntaxhighlight>

== حالة استقبال كائن URL ==
يستقبل المكوّن <code>Link</code> كائن URL وينسقه تلقائيًا لإنشاء عنوان URL نصي. إليك الطريقة:<syntaxhighlight lang="javascript">
import Link from 'next/link'

function Home() {
  return (
    <ul>
      <li>
        <Link
          href={{
            pathname: '/about',
            query: { name: 'test' },
          }}
        >
          About us
        </Link>
      </li>
      <li>
        <Link
          href={{
            pathname: '/blog/[slug]',
            query: { slug: 'my-post' },
          }}
        >
          Blog Post
        </Link>
      </li>
    </ul>
  )
}

export default Home

</syntaxhighlight>يحتوي المثال السابق روابط إلى:

* <code>about?name=test/</code>: وجهة محددة مسبقًا.
* <code>blog/my-post/</code>: وجهة ديناميكية.

بإمكانك استعمال أية خاصية كما عُرّفت في [[Node.js/url|توثيق Node.js لوحدة URL]].

== استبدال العنوان في سجل العناوين بدلًا من دفعه ==
يدفع <code>push</code> المكوّن <code>Link</code> افتراضيًا عنوان URL الجديد في مكدس سجل العناوين <code>history</code>. لكن بإمكانك استخدام الخاصية <code>replace</code> لمنع إضافة مُدخل جديد إلى السجل كالتالي:<syntaxhighlight lang="javascript">
<Link href="/about" replace>
  About us
</Link>
</syntaxhighlight>

== إلغاء التمرير إلى أعلى الصفحة ==
يقتضي السلوك الافتراضي للمكوّن <code>link</code> بالانتقال إلى أعلى الصفحة. لكن عند وجود إشارة العنوان الفرعي (#) سينتقل بالصفحة إلى هذا العنوان المحدد كما يفعل أي رابط نمطي <code><a></code>. لهذا إن أردت إلغاء السلوك الافتراضي بالانتقال إلى أعلى الصفحة، استخدم الصيغة التالية:<syntaxhighlight lang="javascript">
<Link href="/#hashid" scroll={false}>
  Disables scrolling to the top
</Link>
</syntaxhighlight>

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

إليك مثال، إن أردت تخديم وجهة ‎<code>/dashboard</code> تتطلب من المستخدم إجراء الاستيثاق قبل رؤيتها، فعليك إضافة شيفرة مشابهة للشيفرة التالية في ملف البرمجيات الوسيطة middleware.js لإعادة توجيه المستخدم للصفحة الصحيحة:<syntaxhighlight lang="javascript">
// middleware.js
export function middleware(req) {
  const nextUrl = req.nextUrl
  if (nextUrl.pathname === '/dashboard') {
    if (req.cookies.authToken) {
      return NextResponse.rewrite('/auth/dashboard')
    } else {
      return NextResponse.rewrite('/public/dashboard')
    }
  }
}
</syntaxhighlight>في هذه الحالة يجب أن تستخدم الرابط <Link> بالشكل التالي (داخل مجلد الصفحات /pages):<syntaxhighlight lang="javascript">
// pages/index.js
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}>
      Dashboard
    </Link>
  )
}
</syntaxhighlight>'''ملاحظة''': إن تستخدم [[Next.js/Routing#.D8.A7.D9.84.D9.88.D8.AC.D9.87.D8.A7.D8.AA .D8.A7.D9.84.D8.AF.D9.8A.D9.86.D8.A7.D9.85.D9.8A.D9.83.D9.8A.D8.A9 Dynamic Routes|الوجهات الديناميكية]]،  فستحتاج إلى إلى ضبط الخاصية <code>as</code> والخاصية <code>href</code>، مثلًا إن كان لديك الوجهة الديناميكية ‎<code>/dashboard/[user]</code> التي تريد عرضها بشكل مختلف عبر البرمجيات الوسيطة، فيجب أن يكون <code><Link></code> بالشكل التالي:<syntaxhighlight lang="javascript">
<Link href={{ pathname: '/dashboard/authed/[user]', query: { user: username } }} as="/dashboard/[user]">Profile</Link>
</syntaxhighlight>

== أمثلة ==

* [https://github.com/vercel/next.js/tree/canary/examples/hello-world Hello World]
* [https://github.com/vercel/next.js/tree/canary/examples/active-class-name Active className on Link]

== المصادر ==

* الصفحة [https://nextjs.org/docs/api-reference/next/link Next/Link] من توثيق Next.js الرسمي.
[[تصنيف:Next.js|{{SUBPAGENAME}}]]
[[تصنيف:Next.js API|{{SUBPAGENAME}}]]