Next.js/data fetching

إحضار البيانات في Next.js

تتيح عملية إحضار البيانات في تصيير المحتوى بطرق عدة وفقًا للحالة التي تستخدم فيها التطبيق، بما في ذلك التصيير المسبق من جانب الخادم Server-side Rendering أو التوليد الساكن للشيفرة Static Generation أو تحديث المحتوى أو إنشائه أثناء تشغيل التطبيق من خلال التوليد الساكن التراكمي Incremental Static Regeneration.

التصيير من جانب الخادم في Next.js باستخدام الدالة getServerSideProps

عندما تُصدِّر دالة تُدعى getServerSideProps (التصيير من جانب الخادم SSR) من صفحتك، تُصدَّر الصفحة مسبقًا عند كل طلب باستخدام البيانات التي تعيدها الدالة getServerSideProps:

export async function getServerSideProps(context) {
  return {
    props: {}, // تمرر إلى مكوّن الصفحة على شكل خصائص
  }
}

تنفيذ الدالة getServerSideProps في Next.js

تُنفَّذ هذه الدالة من جانب الخادم ولا يمكن تنفيذها من قبل المتصفح، وما يحدث عندما تستخدمها الصفحة أنه:

• ستُنفَّذ الدالة getServerSideProps عند الطلب، وذلك عندما تطلب الصفحة مباشرة، وستصيّر مسبقًا مع الخاصيات التي تعيدها الدالة.
• سترسل Next.js طلبًا من خلال واجهة برمحية API إلى الخادم لكي ينفِّذ الدالة getServerSideProps، وذلك عندما تطلب الصفحة من جانب العميل من خلال next/link أو next/router.

تعيد الدالة getServerSideProps النتيجة على شكل بيانات JSON تُستخدم في تصيير الصفحة، وستنجز Next.js كل هذه الأعمال تلقائيًا دون أي تفعل أي شيء إضافي عندما تُعرّف هذه الدالة.

يمكنك استخدام الأداة next-code-elimination tool للتحقق من شيفرة Next.js التي تُحذف عندما تُجمّع للعمل من ناحية العميل.

تُصدَّر الدالة getServerSideProps من الصفحات فقط، ولا يمكن تصديرها من ملفات لا تُعدُّ صفحاتٍ. و ينبغي الانتباه إلى تصديرها كدالة قائمة بحد ذاتها standalone، فلن تعمل إن أضفتها كخاصية من خواص مكوّن الصفحة.

يمكنك معرفة جميع المعاملات والخاصيات التي تُستخدم مع getServerSideProps، بالاطلاع على مرجع الواجهة البرمجية API reference.

حالات استخدام الدالة getServerSideProps في Next.js

استخدم هذه الدالة إن أردت أن تصيّر صفحة من المفترض إحضار بياناتها عند طلب هذه الصفحة. وقد يكون السبب هو طبيعة البيانات أو خصائص الطلب (مثل ترويسات الاستيثاق authorization أو الموقع الجغرافي). ستُصيّر الصفحات التي تستخدم getServerSideProps من جانب الخادم أثناء الطلب ولن تُخزَّن مؤقتًا ما لم تُهيَّأ ترويسات التحكم بالتخزين المؤقت.

إن لم تشأ أن تصيير البيانات أثناء الطلب، فقد تفكّر في إحضارها من ناحية العميل أو باستخدام الدالة getStaticProps.

استخدام الدالة getServerSideProps مقابل مسارات الواجهة البرمجية API Route

قد يكون العثور على مسار API مغريًا لإحضار البيانات من الخادم بدلًا من استدعاء هذا المسار من خلال الدالة getServerSideProps. لكن هذا الأسلوب غير ضروري وغير مجدٍ، لانه سينفِّذ طلبًا إضافيًا نظرًا لتنفيذ الدالة getServerSideProps مع المسار معًا على الخادم.

لنفترض مثلًا وجود مسار API يُستخدم في إحضار بيانات من منظومة إدارة المحتوى CMS. يُستدعى هذا المسار عندها من قبل الدالة getServerSideProps مباشرة، وسينتج عن ذلك استدعاء إضافي يخفض الأداء. بدلًا من ذلك أدرج تعليمات المنطق الذي يعتمده مسار API ضمن الدالة مباشرة، وقد يكون هذا المنطق استدعاءً لمنظومة إدارة المحتوى أو قاعدة بيانات أو مسارات API أخرى.

إحضار البيانات من جانب العميل في Next.js

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

• أظهر بداية صفحتك دون بيانات، إذ يمكن تصيير بعض أجزاء الصفحة باستخدام نمط التوليد الساكن وأن تُظهِر تقدم تنزيل البيانات المفقودة.
• أحضر بعد ذلك البيانات انطلاقًا من جانب العميل ثم أعرضها عندما تجهز.

تعمل هذه المقاربة جيدًا مع الصفحات التي تمثل لوحة تحكم أو إعدادات لانها صفحات خاصة بالمستخدم لا حاجة لتطبيق قواعد تحسين محركات البحث عليها، ولا حاجة لتصييرها مسبقًا. تُحدَّث هذه البيانات باستمرار ويتطلب ذلك إحضار هذه البيانات عند الطلب فقط.

استخدام الدالة getServerSideProps لإحضار البيانات عند الطلب في Next.js

يعرض المثال التالي كيفية إحضار البيانات عند الطلب ثم تصيير البيانات مسبقًا قبل عرضها:

function Page({ data }) {
  // تصيير البيانات
}

// تُستدعى هذه الشيفرة عند كل طلب
export async function getServerSideProps() {
  // أحضر البيانات من وصلة برمحية خارجية
  const res = await fetch(`https://.../data`)
  const data = await res.json()

  // تمرير البيانات إلى الصفحة عن طريق الخاصيات
  return { props: { data } }
}

export default Page

التخزين المؤقت أثناء التصيير من جانب الخادم (SSR)

بإمكانك استخدام ترويسات التخزين المؤقت (Cache-Control) ضمن الدالة getServerSideProps لتخزين الاستجابات الديناميكية مؤقتًا. استخدم القيمة stale-while-revalidate مثلًا:

// (s-maxage=10)تُعد هذه القيمة جديدة مدة عشر ثوان.
// إن أعيد الطلب ضمن هذه الثواني العشرة ستبقى هذه القيمة حديثة
// بينما إن أعيد الطلب قبل 59 ثانية ستُصيّر القيمة على الرغم من كونها قديمة
//(stale-while-revalidate=59).
//سيجري طلب خلف الستار لتحديث  هذه القيمة في الذاكرة المؤقتة 
//سترى هذه القيمة الجديدة إن حدّثت الصفحة 
export async function getServerSideProps({ req, res }) {
  res.setHeader(
    'Cache-Control',
    'public, s-maxage=10, stale-while-revalidate=59'
  )

  return {
    props: {},
  }
}

تصيير الأخطاء عند استخدام الدالة getServerSideProps في Next.js

إن ظهر خطأ داخل الدالة getServerSideProps فستعرض الملف pages/500.js. راجع توثيق الصفحة 500 لتتعلم طريقة إنشائها. لن يُستخدم هذا الملف في مرحلة التطوير وستُعرض صفحة الخاصة بهذه المرحلة بدلًا منه.

التوليد الساكن للمسارات باستخدام الدالة getStaticProps

عندما تمتلك الصفحة مسارات ديناميكية وتستخدم في الوقت نفسه الدالة getStaticProps، لا بد حينها من تعريف قائمة بالمسارات التي ينبغي توليدها بشكل ساكن. مع تصدير الدالة التي تُدعى getStaticPaths من

export async function getStaticPaths() {
  return {
    paths: [
      { params: { ... } }
    ],
    fallback: true // false or 'blocking'
  };
}

ينبغي استخدام الدالة getStaticPaths مع الدالة getStaticProps، ولا يمكنك استخدامها مع getServerSideProps.

يمكنك معرفة جميع المعاملات والخاصيات التي تُستخدم مع getStaticPaths، بالاطلاع على مرجع الواجهة البرمجية API reference.

حالات استخدام الدالة getStaticPaths في Next.js

ينبغي استخدام هذه الدالة إن كنت ستصّر مسبقًا صفحات تحتوي على مسارات ديناميكية وكان:

• مصدر البيانات هو منظومة إدارة محتوى دون ترويسات.
• مصدر البيانات هو قاعدة بيانات.
• مصدر البيانات هو نظام إدارة ملفات.
• بالإمكان التخزين المؤقت للبيانات للعموم (غير مخصصة لمستخدم محدد).
• لا بد من تصيير الصفحة مسبقًا (لأغراض تحسين محركات البحث "سيو") وأن يجري ذلك بسرعة. توّلد getStaticProps ملفات HTML و JSON التي يمكن تخزينها مؤقتًا من قبل منظومة توصيل محتوى CDN لرفع الأداء.

تنفيذ الدالة getStaticPaths في Next.js

تُنفَّذ هذه الدالة عند بناء التطبيق في وضع الإنتاج فقط. يمكنك التحقق من أن الشيفرة المكتوبة داخل الدالة getStaticPaths ستُزال من الشيفرة المجمّعة من ناحية العميل باستخدام الأداة next-code-elimination tool.

• تُنفَّذ الدالة getStaticProps عند تنفيذ الأمر next build لكل مسار paths يُعاد أثناء البناء.
• تُنفَّذ الدالة getStaticProps في الخلفية عند استخدام التوجيه fallback: true.
• تُستدعى الدالة getStaticProps قبل التصيير الأولي عند استخدام التوجيه fallback: blocking.

ملاحظة: تُستدعى الدالة عند كل استدعاء خلال مرحلة التطوير (next dev).

التوليد الساكن للصفحات في Next.js باستخدام الدالة getStaticProps

عندما تُصدِّر دالة تُدعى getStaticProps (توليد ساكن للموقع) من صفحة، تُصيِّر Next.js هذه الصفحة أثناء بناء التطبيق باستخدام الخاصيات props التي تُعيدها هذه الدالة.

export async function getStaticProps(context) {
  return {
    props: {}, // تُمرر إلى مكوِّن الصفحة على شكل خاصيات
  }
}

حالات استخدام الدالة getStaticProps في Next.js

عليك استخدام هذه الدالة في الحالات التالية:

• البيانات التي ستستخدمها لتصيير الصفحة أثناء بناء التطبيق متوفرة مسبقًا قبل أن يطلبها المستخدم.
• مصدر البيانات هو نظام إدارة محتوى دون ترويسات headless CMS.
• لا بد من تصيير الصفحة مسبقًا (لأغراض تحسين محركات البحث "سيو") وأن يجري ذلك بسرعة. توّلد getStaticProps ملفات HTML و JSON التي يمكن تخزينها مؤقتًا من قبل منظومة توصيل محتوى CDN لرفع الأداء.
• عند إمكانية التخزين المؤقت للبيانات للعموم (غير مخصصة لمستخدم محدد). يمكن تجاوز هذا الشرط في بعض الحالات الخاصة من خلال استخدام برمجيات وسطية Middleware لإعادة كتابة المسار.

تنفيذ الدالة getStaticProps في Next.js

تُنفَّذ هذه الدالة دائمًا من جانب الخادم وليس من جانب العميل:

• تُنفَّذ getStaticProps دائمًا اثناء تنفيذ الأمر
• تُنفّذ getStaticProps في الخلفية عند استخدام التوجيه revalidate.
• تُنفّذ getStaticProps في الخلفية عند الطلب عند استخدام التوجيه unstable_revalidate.

عندما تُستخدم الدالة getStaticProps مع نمط التجديد الساكن التدريجي للصفحات Incremental Static Regeneration، ستُنفَّذ في الخلفية أثناء إعادة تقييم الصفحة القديمة ومن ثم تُقدّم الصفحة المحدّثة إلى المتصفح.

لا يمكن للدالة getStaticProps أن تلج إلى الطلبات الواردة (كمعاملات الاستعلام أو ترويسات HTTP) لأنها تولّد ملف HTML ساكن. لكن إن أردت الوصول إلى هذه الطلبات فكِّر باستخدام برمجيات وسطية إضافة إلى هذه الدالة.

استخدام الدالة لإحضار البيانات من منظومة إدارة محتوى CMS

تعرض الشيفرة التالية طريقة إحضار قائمة بالمنشورات من منظومة إدارة محتوى:

// getStaticProps() تُعرض المنشورات أثناء بناء التطبيق باستخدام 
function Blog({ posts }) {
  return (
    <ul>
      {posts.map((post) => (
        <li>{post.title}</li>
      ))}
    </ul>
  )
}
// تُستدعى هذه الدالة أثناء بناء التطبيق من جانب الخادم
// لن تُستدعى من جانب العميل لذلك بالإمكان الاستعلام من قاعدة بيانات مباشرة

export async function getStaticProps() {
  //خارجية API تستدعى وصلة 
  // يمكن استدعاء أية مكتبة لإحضار البيانات
  const res = await fetch('https://.../posts')
  const posts = await res.json()

  // المنشورات كخاصيات أثناء بناء التطبيقBlog يتلقى المكوّن 
  // { props: { posts } } بإعادة
  return {
    props: {
      posts,
    },
  }
}

export default Blog

يمكنك معرفة جميع المعاملات والخاصيات التي تُستخدم مع getStaticProps، بالاطلاع على مرجع الواجهة البرمجية API reference.

كتابة شيفرة تعمل من جانب الخادم مباشرة في Next.js

لن تُنفَّذ الدالة getStaticProps إلا من ناحية الخادم فقط ولا يمكن تنفيذها من ناحية العميل وبالتالي لن تجدها ضمن شيفرة جافا سكربت الخاصة بالمتصفح وستتمكن من كتابة استعلامات مباشرة من قاعدة البيانات دون إرسالها إلى المتصفحات. وهكذا يمكنك كتابة شيفرة تُنفَّذ من جانب الخادم مباشرة ضمن الدالة getStaticProps بدلًا من إحضار مسار API منها (كونها تحضر البيانات بنفسها من مصدر خارجي).

لنلق نظرة على المثال التالي: يُستخدم مسار API لإحضار بيانات من منظومة إدارة محتوى، لهذا سيُستدعى مباشرة من خلال الدالة getStaticProps، وستكون النتيجة استدعاء إضافي وانخفاضًا في الأداء. وبدلًا عن ذلك، يمكن مشاركة منطق إحضار البيانات من منظومة إدارة المحتوى باستخدام المجلد lib/ ومن ثم مشاركته مع الدالة getStaticProps.

// lib/fetch-posts.js
// تُشارك الدالة التالية
// API routes و getStaticProps مع 
// `lib/` من المجلد
export async function loadPosts() {
  //لخارجية للحصول على المنشوراتAPI تستدعى وصلة 
  const res = await fetch('https://.../posts/')
  const data = await res.json()

  return data
}

// pages/blog.js
import { loadPosts } from '../lib/load-posts'

// تُنفَّذ الدالة من جانب الخادم فقط
export async function getStaticProps() {
  //بالإمكان استدعاء نفس الدالة مباشرة `/api`  بدلًا من إحضار المسار 
  const posts = await loadPosts()

   // تُمرر إلى مكوِّن الصفحة على شكل خاصيات
  return { props: { posts } }
}

إن لم تستخدم مسارات API لإحضار البيانات بإمكانك استخدام الدالة ()fetch ضمن الدالة getStaticProps.

التوليد التلقائي لشيفرة HTML و JSON

عندما تُصيَّر صفحة تحتوي على الدالة getStaticProps أثناء بناء التطبيق، ستوّلد Next.js ملف JSON بالإضافة إلى ملف HTML وذلك لاحتواء نتيجة تنفيذ تلك الدالة.

يُستخدم ملف JSON للتوجيه من جانب العميل عبر next/link أو next/router. فعندما ننتقل إلى الصفحة التي صُيِّرت مسبقًا باستخدام الدالة getStaticProps، ستحضر Next.js ملف JSON (الذي بني مُسبقًا أثناء بناء التطبيق) ثم تسنده إلى خصائص مكوِّن الصفحة. وبالتالي لن تستدعي عمليات التنقل بين صفحات التطبيق من ناحية العميل استدعاء الدالة getStaticProps لأن ما سيُستخدم فعلًا هو ملف JSON المُصدَّر.

عند استخدام التوليد الساكن التدريجي أو التراكمي، سيجر تنفيذ الدالة getStaticProps في الخلفية لتوليد ملف JSON المطلوب للتنقل بين الصفحات من جانب العميل. قد ترى ذلك على شكل طلبات متعدددة لنفس الصفحة، وهذا أمر مقصود ولن يؤثر على أداء الصفحة بالنسبة للمستخدم النهائي.

أماكن استخدام الدالة getStaticProps في Next.js

يمكن تصدير الدالة getStaticProps من صفحة Next.js (مكوّن صفحة) فقط ولا يمكن تصديرها من ملفات لا تمثل صفحات. ومن أهم الأسباب الكامنة وراء هذا التقييد هو أن رياكت تحتاج إلى جميع البيانات قبل تصيير الصفحة.

لا بد أن تُصدّر أيضًا الدالة getStaticProps لتكون ذاتية الدعم فلن تعمل إن أضفتها كخاصية إلى مكوِّن الصفحة.

ملاحظة: تُستدعى الدالة عند كل استدعاء خلال مرحلة التطوير (next dev).

نمط الاستعراض

بإمكانك أن تتجاوز التوليد التلقائي مؤقتًا وتصيِّر الصفحة عند الطلب بدلًا من تصييرها أثناء بناء التطبيق باستخدام نمط الاستعراض Preview Mode. فقد تستخدم مثلًا منظومة إدارة محتوي بلا ترويسات، وتريد أن تستعرض مسودة العمل قبل أن نشره.

التجديد التدريجي الساكن في Next.js

تتيح لك أن تنشئ أو تُحدِّث الصفحات الساكنة بعد ان تنهي بناء الموقع من خلال التجديد التدريجي الساكن Incremental Static Regeneration (واختصارًا ISR) الذي يمكِّنك من استخدام التجديد الساكن للصفحات منفردةً دون الحاجة إلى إعادة بناء الموقع بأكمله. وهكذا ستحتفظ بميزات الصفحات الساكنة مع إتوسيع إمكانات ملايين الصفحات.

لاستخدام ISR أضف الخاصية revalidate إلى الدالة getStaticProps: