التوجيه routing في Next.js

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

أنماط الوجهات

تدعم 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

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

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

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 الانتقال بين الصفحات في جانب العميل بشكل مشابهٍ للتطبيقات وحيدة الصفحة SPA اختصارًا إلى single-page application. يُستخدم مكوّن React الذي يُدعى Link في إنجاز هذا الأمر من جانب العميل:

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

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

`/` → `pages/index.js`

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

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

إن كل مكوّن </ Link> في نافذة العرض viewport (بشكلها الأساسي أو بعد تمرير محتويات الشاشة) سيُحضَر مسبقًا prefetched بشكل افتراضي (بما في ذلك البيانات المتعلقة به) للصفحات التي تعتمد التوليد الساكن 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)}`}>
            {post.title}
          </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 },
            }}
          >
            {post.title}
          </Link>
        </li>
      ))}
    </ul>
  )
}

export default Posts

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

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

الوصول إلى كائن التوجيه router

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

الوجهات الديناميكية Dynamic Routes

لا يُعد تحديد المسارات مسبقًا أمرًا كافيًا للتطبيقات المعقدة، لهذا تتيح لك 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 وسيُرسل معامل المسار على شكل معامل استعلام query parameter إلى الصفحة وسيُدمج مع بقية معاملات الاستعلام. تمتلك الوجهة 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">Go to pages/post/[pid].js</Link>
      </li>
      <li>
        <Link href="/post/abc?foo=bar">Also goes to pages/post/[pid].js</Link>
      </li>
      <li>
        <Link href="/post/abc/a-comment">
          Go to pages/post/[pid]/[comment].js
        </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` سيحصل على

محاذير

• للوجهات المحددة مسبقًا الأفضلية على الوجهات الديناميكية والتي لها الأفضلية على جميع المسارات الملتقطة. إليك بعض الأمثلة:
  • 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/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>
  )
}

التوجيه السطحي

يتيح لك التوجه السطحي 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/، لكن لن تُستبدل الصفحة بل حالة الوجهة route فقط. يمكنك أن ترى أيضًا كيف يتغير عنوان 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 })

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

إن جرى استخدام التوجيه السطحي مع برمجيات وسيطة middleware فليس هنالك ما يضمن أن تتطابق الصفحة الجديدة مع الحالية (كما رأيت في المثال ما قبل السابق)، وذلك يعود عادة إلى أن البرمجيات الوسيطة تملك صلاحيات إعادة الكتابة آليًا ولا يمكن التأكد من طرف العمل من ذلك دون عملية إحضار البيانات التي يجري تجاهلها مع استعمال shallow لذا يجب معاملة التغييرات التي تحصل مع التوجيه السطحي على أنها تغييرات سطحية دومًا.

أمثلة

• Dynamic Routing
• Catch All Routes
• Using Router
• Shallow Routing

المصادر

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