توجيه المسارات في Next.js

تمتلك Next.js موجهًا للمسارات يعتمد على نظام ملفات مبني على مفهوم الصفحات. فعندما يُضاف ملف إلى المجلد pages سيُتاح مباشرة كوجهة (أو مسار). يمكن استخدام الملفات ضمن هذا المجلد لتعريف مختلف الأنماط.

أنماط الوجهات في Next.js

تدعم Next.js عددًا من أنماط الوجهات سنتعرف عليها تباعًا.

الوجهات الخاصة بالصفحة Index

سيحدد الموجّه تلقائيًا موقع الصفحات التي تُدعى index بالنسبة إلى الملف الجذري كما في الأمثلة التالية:

pages/index.js → /

pages/blog/index.js → /blog

الوجهات المتداخلة

يدعم الموجّه الملفات المتداخلة، فلو أنشأت هيكلية متداخلة لمجلد سيحدد الموجّه تلقائيًا موقع كل منها بنفس الطريقة السابقة:

pages/blog/first-post.js → /blog/first-post

pages/dashboard/settings/username.js → /dashboard/settings/username

الأقسام الديناميكية لوجهة

لمطابقة جزء ديناميكي من مسار بإمكانك استخدام صيغة الأقواس المربعة، وسيتيح لك ذلك مطابقة معاملات مسماة:

pages/blog/[slug].js → /blog/:slug (/blog/hello-world)

pages/[username]/settings.js → /:username/settings (/foo/settings)

pages/post/[...all].js → /post/* (/post/2020/id/title)

سنتعرف أكثر على الوجهات الديناميكة تاليًا في صفحة التوثيق هذه.

الربط ما بين الصفحات في Next.js

يتح لك موجّه Next.js الانتقال بين الصفحات في جانب العميل بشكل مشابهٍ للتطبيقات وحيدة الصفحة. يُستخدم مكوّن React الذي يُدعى Link في إنجاز هذا الأمر من جانب العميل:

import Link from 'next/link'

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

export default Home

يستخدم المثال السابق روابط عدة يتعلق كل منها بمسار (href) إلى صفحة معروفة:

`/` → `pages/index.js`

`/about` → `pages/about.js`

`/blog/hello-world` → `pages/blog/[slug].js`

إن كل مكوّن </ Link> في نافذة العرض (بشكلها الأساسي أو بعد تمرير محتويات الشاشة) سيُحضَر مسبقًا بشكل افتراضي (بما في ذلك البيانات المتعلقة به) للصفحات باستخدام التوليد الساكن Static Generation. ولن تُحضر البيانات الناتجة عن تصيير الوجهات من جانب الخادم server-rendered مسبقَا.

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

يمكن استخدام الاستدلال لإنشاء مسار، وتظهر الفائدة من ذلك عندما يتضمن عنوان المسار أجزاءً ديناميكة. فلو أردت أن تعرض على سبيل المثال مجموعة من المنشورات التي مُرِّرت إلى المكوّن على شكل خاصية:

import Link from 'next/link'

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

export default Posts

ملاحظة: استُخدم الكائن encodeURIComponent في المثال السابق للمحافظة على توافق المسار مع utf-8.

import Link from 'next/link'

function Posts({ posts }) {
  return (
    <ul>
      {posts.map((post) => (
        <li key={post.id}>
          <Link
            href={{
              pathname: '/blog/[slug]',
              query: { slug: post.slug },
            }}
          >
            <a>{post.title}</a>
          </Link>
        </li>
      ))}
    </ul>
  )
}

export default Posts

بدلًا من استخدام طريقة الاستدلال لإنشاء المسار، استخدمنا في الحالة الثانية كائن URL كقيمة للخاصية href:

• pathname: هو اسم الصفحة الموجودة في المجلد pages، وهيblog/[slug]/ في مثالنا.
• query: هو كائن يحتوي على جزء ديناميكي، وهو slug في حالتنا.

الدفع بالموجّه

للوصول إلى الكائن في مكوّن React، يمكنك استخدام useRouter أو withRouter علمًا أنه من الأفضل استخدام useRouter عمومًا.

الوجهات الديناميكية في Next.js

لا يُعد تحديد المسارات مسبقًا أمرًا كافيًا للتطبيقات المعقدة، لهذا تتيح لك Next.js إمكانية إضافة أقواس مربعة حول صفحة ([param]) لإنشاء وجهة ديناميكة.

لنتأمل الصفحة التالية pages/post/[pid].js:

import { useRouter } from 'next/router'

const Post = () => {
  const router = useRouter()
  const { pid } = router.query

  return <p>Post: {pid}</p>
}

export default Post

تجري مطابقة أي وجهة مثل post/1/ أوpost/abc/ وغيرها مع المسار pages/post/[pid].js وسيُرسل معامل المسار على شكل استعلام إلى الصفحة وسيُدمج مع بقية معاملات الاستعلام. تمتلك الوجهة post/abc/ مثلًا كائن الاستعلام query التالي:

{ "pid": "abc" }

كما تمتلك الوجهة post/abc?foo=bar/ أيضًا كائن الاستعلام query التالي:

{ "foo": "bar", "pid": "abc" }

لكن معاملات الوجهة ستلغي معاملات الاستعلام التي تتفق معها بالاسم. إذ تمتلك الوجهة post/abc?pid=123/ مثلًا كائن الاستعلام query التالي:

{ "pid": "abc" }

تعمل الوجهات التي تضم عدة أجزاء ديناميكية بنفس الطريقة، إذ تطابق الصفحة pages/post/[pid]/[comment].js الوجهة post/abc/a-comment/ وسيكون كائن الاستعلام query الخاص بها هو:

{ "pid": "abc", "comment": "a-comment" }

تُعالح المسارات الديناميكية للتنقل بين الصفحات في جانب العميل بواسطة المكوِّن next/link. فإن أردنا الحصول على روابط إلى الوجهات التي ذكرناها سابقًا، ستبدو كالتالي:

import Link from 'next/link'

function Home() {
  return (
    <ul>
      <li>
        <Link href="/post/abc">
          <a>Go to pages/post/[pid].js</a>
        </Link>
      </li>
      <li>
        <Link href="/post/abc?foo=bar">
          <a>Also goes to pages/post/[pid].js</a>
        </Link>
      </li>
      <li>
        <Link href="/post/abc/a-comment">
          <a>Go to pages/post/[pid]/[comment].js</a>
        </Link>
      </li>
    </ul>
  )
}

export default Home

التقاط جميع الوجهات

بالإمكان توسعة الوجهات الديناميكية لمطابقة كل المسارات وذلك بإضافة ثلاث نقاط (...) داخل القوسين المربعين. إليك مثالًا:

• تطابق الوجهة pages/post/[...slug].js المسار post/a/ كما تطابق post/a/b/ و post/a/b/c/ وهكذا. بإمكانك طبعًا اختيار أي اسم بدلًا من slug مثل [param...].

تُرسل معاملات البحث كمعاملات استعلام ( slug مثال على ذلك) إلى الصفحة، وتشكل المعاملات دائمًا مصفوفة. وبالتالي سيكون كائن الاستعلام عن المسار post/a/ مثلًا هو:

{ "slug": ["a"] }

في حالة post/a/b/ وأية مسارات مطابقة أخرى، ستُضاف البارمترات الجديدة إلى المصفوفة كالتالي:

{ "slug": ["a", "b"] }

التقاط جميع الوجهات اختياريًا

يمكن التقاط جميع الوجهات اختياريًا بإضافة المعامل بين قوسين مربعين مزدوجين مثل ([[...slug]]). إذ ستطابق الوجهة pages/post/[[...slug]].js مثلًا المسارات post/ و post/a/ و post/a/b/ وهكذا.

إن الاختلاف الرئيسي بين التقاط جميع الوجهات والتقاط جميع الوجهات اختياريًا هو أن الالتقاط الاختياري سيطابق أيضًا المسارات التي لا تضم معامل البحث (المسار post/ مثالًا).

سيكون كائن الاستعلام query التالي:

{ } //`/post` سيحصل على المسار 
{ "slug": ["a"] } //(مصفوفة وحيد العنصر) `/post/a` سيحصل على المسار 
{ "slug": ["a", "b"] } //(مصفوفة متعددة العناصر) `/post/a/b` سيحصل على

تحفظات على المسارات الديناميكية في Next.js

• للوجهات المحددة مسبقًا الأفضلية على الوجهات الديناميكية والتي لها الأفضلية على جميع المسارات الملتقطة. إليك بعض الأمثلة:
  • pages/post/create.js يتطابق مع post/create/.
  • pages/post/[pid].js يتطابق مع post/1/ و post/abc/ وليس مع post/create/.
  • pages/post/[...slug].js يتطابق مع post/1/2/ و post/a/b/c/ وليس مع post/create/ و post/abc/.
• ستُرطَّب الصفحات التي تُحسّن بشكل ساكن من خلال المحسّن الساكن الآلي Automatic Static Optimization دون تزويدها بمعاملات وجهاتها، أي سيكون كائن الاستعلام query مصفوفة فارغة ({}). وبعد الترطيب ستدفع Next.js نحو تحديث التطبيق لتزويد مصفوفة الاستعلام بقيم المعاملات.

الوجهات القسرية في Next.js

يغطي الكائن next/link كل احتياجاتك في التوجه إلى الموارد والصفحات، لكن بإمكانك أيضًا التنقل بين الصفحات في جانب العميل دون الحاجة إليه (الق نظرة على توثيق الواجهة البرمجية المتعلق بالوجهات).

يظهر المثال التالي كيفية التنقل بين الصفحات باستخدام useRouter:

import { useRouter } from 'next/router'

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

  return (
    <button onClick={() => router.push('/about')}>
      Click here to read more
    </button>
  )
}

التوجه السطحي في Next.js

يتيح لك التوجه السطحي Shallow routing تغيير عنوان URL دون تنفيذ طرق إحضار البيانات مرة أخرى بما فيها getServerSideProps و getStaticProps و getInitialProps. ستحصل على المسار الحديث ومصفوفة الاستعلام الحديثة من خلال الكائن router (الذي يضيفه useRouter أو withRouter) دون أن يفقد المكوّن حالته.

لتمكين التوجه السطحي، اضبط قيمة الخيار shallow على true. إليك مثالًا:

import { useEffect } from 'react'
import { useRouter } from 'next/router'

// الحالي URL هو عنوان '/'
function Page() {
  const router = useRouter()

  useEffect(() => {
    // تنقَّل دائمًا بعد التصيير الأول
    router.push('/?counter=10', undefined, { shallow: true })
  }, [])

  useEffect(() => {
    // !تغيّر العداد
  }, [router.query.counter])
}

export default Page

سيُحدَّث عنوان URL إلى ?counter=10/، لكن لن تُستبدل الصفحة بل حالة الوجهة فقط. يمكنك أن ترى أيضًا كيف يتغير عنوان URL بواسطة المكوّن componentDidUpdate كالتالي:

componentDidUpdate(prevProps) {
  const { pathname, query } = this.props.router
  // تأكد من تغير الخاصية لتفادي الحلقات المفرغة
  if (query.counter !== prevProps.router.query.counter) {
    // أحضر البيانات وفق الاستعلام الجديد
  }
}

التحفظات على التوجه السطحي

يعمل هذا التوجه مع عناوين URL التي تتغير في الصفحة الحالية. لنفترض مثلًا وجود صفحة أخرى تُدعى pages/about.js ومن ثم نفَّذت الأمر التالي:

router.push('/?counter=10', '/about?counter=10', { shallow: true })

طالما أنها صفحة جديدة، فلن تُحمّل الصفحة الحالية بل تُحمّل الجديدة وتُنتظر البيانات حتى تأتي حتى لو أردنا وجهة سطحية.

المصادر

• صفحات Router من توثيق Next.js الرسمي.