عرض مصدر Next.js/preview mode

<noinclude>{{DISPLAYTITLE:نمط استعراض الصفحات في Next.js}}</noinclude>
<blockquote>'''تنبيه''': تُخصص صفحة التوثيق هذه للنسخة 9.3 من Next.js والنسخ الأعلى.</blockquote>تحدثنا في توثيق [[Next.js/pages|صفحات Next.js]] وتوثيق [[Next.js/data fetching|إحضار البيانات]] عن كيفية تصيير الصفحات مسبقًا أثناء بناء التطبيق (التوليد الساكن Static Generation) باستخدام <code>getStaticProps</code> و <code>getStaticPaths</code>. 

تظهر فائدة التوليد الساكن في إحضار البيانات من منظومة إدارة محتوى دون ترويسات headless CMS، لكنه ليس مثاليًا عندما تحاول استعراض مسوّدة عملك مباشرة على الصفحة. فقد ترغب في هذه الحالة في تصيير صفحتك عند الطلب بدل تصييرها أثناء بناء التطبيق، وإحضار المحتوى التجريبي بدلًا من المحتوى الذي سيُنشر. أي قد ترغب بتجاوز التوليد الساكن في هذه الحالة بالتحديد.

تمتلك Next.js ميزة تُدعى نمط الاستعراض لحل هذا الأمر. وإليك طريقة استخدامه.

== الخطوة الأولى: أنشئ مسار API للاستعراض ولج إليه ==
<blockquote>'''تلميح''': الق نظرة أولًا على توثيق [[Next.js/api routes|مسارات API]] إن لم تكن على دراية بها.</blockquote>أنشئ أولًا مسار API لاستعراض الصفحةوسمِّه ما تشاء مثل <code>pages/api/preview.js</code> أو (استخدم الامتداد <code>ts.</code> إن كنت تستخدم TypeScript). 

عليك أن تستدعي ضمن هذا المسار الدالة <code>setPreviewData</code> من خلال كائن الاستجابة <code>res</code>، وينبغي أن يكون وسيطها كائنًا قد يُستخدم لاحقًا مع الدالة <code>getStaticProps</code>. أما الآن فسنستخدم القوسين الفارغين <code>{}</code>.<syntaxhighlight lang="javascript">
 export default function handler(req, res) {
  // ...  
  res.setPreviewData({})
  // ...
}
</syntaxhighlight>تهيئ الدالة <code>res.setPreviewData</code> بعض ملفات تعريف الارتباط cookies في المتصفح والتي تفعّل نمط الاستعراض. تُعد أية طلبات تتضمن ملفات تعريف الارتباط تلك ضمن نمط الاستعراض، ويتغير سلوك التوليد الساكن للصفحات.

بإمكانك اختبار الأمر يدويًا، بإنشاء مسار API كما في المثال التالي والولوج إليه من خلال المتصفح:<syntaxhighlight lang="javascript">
// مثال بسيط للاختبار اليدوي
//موجودًا pages/api/preview.js إن كان المسار
//ضمن المتصفح api/preview افتح الصفحة 
export default function handler(req, res) {
  res.setPreviewData({})
  res.end('Preview mode enabled')
}
</syntaxhighlight>قد تلاحظ إن كنت تستخدم أدوات مطوري ويب أن ملفات تعريف ارتباط <code>prerender_bypass__</code> و <code>next_preview_data__</code> ستُهيئ عند إرسال هذا الطلب.

=== الولوج الآمن إلى الصفحة من منظومة إدارة محتوى دون ترويسة ===
قد ترغب عمليًا باستدعاء مسار API بشكل آمن من منظومة إدارة محتوى CMS، وستختلف خطوات إنجاز الأمر وفقًا للمنظومة التي تستخدمها. لهذا سنستعرض بعض الخطوات الشائعة التي يمكنك اتخاذها. تفترض هذه الخطوات أن المنظومة التي تستخدمها تدعم ضبط عناوين URL مخصصة للاستعراض، فإن لم تكن كذلك، ستبقى قادرًا على استخدام هذه الطريقة لتأمين عناوين الاستعراض، لكن عليك أن تبني وتلج إلى هذه العناوين يدويًا.

* أولًا، عليك إنشاء مفتاح استيثاق نصي سري مستخدمًا موّلد مفاتيح استيثاق token تختاره، وسيعرفه فقط تطبيق Next.js والمنظومة. وهكذا لن يتمكن الأشخاص الذين لا يُسمح لهم بدخول المنظومة من الوصول إلى عناوين URL.
* ثانيًا، إن كانت تدعم منظومة إدارة المحتوى التي لا تستخدم الترويسات ضبط عناوين استعراض مخصصة، حدد العنوان التالي كعنوان URL للاستعراض (على افتراض أن وجهة مسار API هي <code>pages/api/preview.js</code>). 
<syntaxhighlight lang="bash">
https://<your-site>/api/preview?secret=<token>&slug=<path>
</syntaxhighlight>

# <code><your-site></code>: اسم نطاق التطوير الخاص بك.
# <code><token></code>: يُستبدل بمفتاح الاستيثاق الذي ولّدته.
# <code><path></code>: مسار الصفحة التي تريد استعراضها. فإن أردت استعراض الصفحة <code>posts/foo/</code> مثلًا، عليك أن تستخدم <code>slug=/posts/foo&</code>. وقد تسمح لك المنظومة بأن تضع متغيرًا في عنوان الاستعراض، وبالتالي يمكن أن يُضبط المسار <code><path></code> ديناميكيًا وفقًا لبيانات المنظومة كالتالي: <code>slug=/posts/{entry.fields.slug}&</code>.

* أخيرًا، نفّذ ما يلي في مسار API الخاص بالاستعراض:
** تأكد من تطابق مفتاح الاستيثاق، وأن معاملات <code>slug</code> موجودة (ينبغي أن يخفق الطلب إن لم تكن موجودة).
** استدع الدالة <code>res.setPreviewData</code>.
** وجّه المتصفح إلى المسار المحدد في <code><path></code> (يستخدم المثال التالي التوجيه 307 (إعادة توجيه مؤقت)).
<syntaxhighlight lang="javascript">
export default async (req, res) => {
  // تأكد من تطابق مفتاح الاستيثاق والمعاملات 
  //يجب أن يُعرف فقط من قبل التطبيق ومنظومة إدارة المحتوى
  if (req.query.secret !== 'MY_SECRET_TOKEN' || !req.query.slug) {
    return res.status(401).json({ message: 'Invalid token' })
  }

  //`slug` تأكد من وجود معاملات 
  //منطق إحضارات البيانات من المنظومة getPostBySlug ستنجز الدالة 
  const post = await getPostBySlug(req.query.slug)

  //موجودة `slug` لا تمكّن نمط الاستعراض ما لم تكن 
  if (!post) {
    return res.status(401).json({ message: 'Invalid slug' })
  }

  // مكّن نمط الاستعراض من خلال ضبط ملفات تعريف الارتباط
  res.setPreviewData({})

  // أعد التوجيه إلى المسار الذي أُحضر
  //لأن ذلك قد يسبب ضعفًا req.query.slug لا نعيد التوجيه إلى 
  res.redirect(post.slug)
}
</syntaxhighlight>إن نجح الأمر، سينتقل بك المتصفح إلى الوجهة التي تريد استعراضها بعد ضبط ملفات تعريف الارتباط التي تفعّل نمط الاستعراض.

== الخطوة الثانية: حدّث قيم الخاصيات باستخدام <code>getStaticProps</code> ==
تقتضي الخطوة التالية تحديث <code>getStaticProps</code> لدعم نمط الاستعراض. فإن طلبت صفحة تحتوي <code>getStaticProps</code> وقد ضُبطت ملفات تعريف الارتباط فيها على وضع الاستعراض (من خلال <code>res.setPreviewData</code>)، عندها تُستدعى الدالة <code>getStaticProps</code> عند الطلب بدلًا من وقت البناء.

إضافة إلى ذلك، تُستدعى الدالة مع الكائن <code>context</code> إذ:

* يحمل <code>context.preview</code> القيمة <code>true</code>.
* <code>context.previewData</code> هو نفسه الوسيط المستخدم في <code>setPreviewData</code>.
<syntaxhighlight lang="javascript">
export async function getStaticProps(context) {
  // إن استدعيت الصفحة وقد ضُبطت ملفات تعريف الارتباط على نمط الاستعراض
  //
  // سيكون محققًا context.preview 
  // هو نفسه الوسيط المستخدم في context.previewData 
  // `setPreviewData`
}
</syntaxhighlight>لقد استخدمنا الدالة <code>({})res.setPreviewData</code> في مسار API الخاص بالاستعراض، لذا ستكون قيمة <code>context.previewData</code> هي <code>{}</code>. يمكن الاستفادة من ذلك في تمرير معلومات جلسة العمل من مسار API الخاص بالاستعراض إلى <code>getStaticProps</code> عند الحاجة. وسيكون <code>context.params</code> متاحًا إيضًا إن كنت تستخدم <code>getStaticPaths</code>.

=== إحضار بيانات الاستعراض ===
يمكنك تحديث <code>getStaticProps</code> لإحضار البيانات المختلفة وفقًا للخاصية <code>context.preview</code> أو/و <code>context.previewData</code>. فقد تمتلك منظومة إدارة المحتوى لديك على سبيل المثال وصلات API مختلفة لمسودات المنشورات، وبالتالي ستتمكن حينها من استخدام <code>context.preview</code> لتعديل عنوان URL لوصلة API كما يلي:<syntaxhighlight lang="javascript">
export async function getStaticProps(context) {
  // API إلى وصلة "/preview" محققًا اربط context.preview إن كان 
  //  سيختلف طلب البيانات التجريبية (المسودة)
  // عن بيانات النشر وفقًا لمنظومة إدارة المحتوى التي لا تحمل ترويسات
  const res = await fetch(`https://.../${context.preview ? 'preview' : ''}`)
  // ...
}
</syntaxhighlight>فإن ولجت الآن إلى مسار API باستخدام <code>secret</code> و <code>slug</code> من خلال منظومة إدارة محتوى دون ترويسات أو يدويًا، من المفترض أن ترى المحتوى الذي تنوي استعراضه. وإن حدَّثت مسودتك دون أن تنشرها، من المفترض أن تكون قادرًا على استعراضها أيضًا:<syntaxhighlight lang="bash">
# للاستعراض URL يضبط ما يلي عنوان
# من خلال منظومة إدارة محتوى أو يدويًا وستكون قادرًا على استعراض المحتوى
https://<your-site>/api/preview?secret=<token>&slug=<path>
</syntaxhighlight>

== تفاصيل أكثر عن نمط الاستعراض في Next.js ==
إليك بعض التفاصيل الهامة التي تتعلق بنمط الاستعراض.

=== حذف ملفات تعريف ارتباط نمط الاستعراض ===
لا توجد مدة إنتهاء صلاحية محددة افتراضيًا لملفات تعريف الارتباط، وبالتالي ستنتهي جلسة الاستعراض مع إغلاق المتصفح.

لإزالة ملفات تعريف الارتباط لنمط الاستعراض يدويًا، أنشئ مسار API يستدعي الدالة <code>()clearPreviewData</code>:<syntaxhighlight lang="javascript">
// pages/api/clear-preview-mode-cookies.js

export default function handler(req, res) {
  res.clearPreviewData()
}
</syntaxhighlight>أرسل بعد ذلك طلبًا إلى <code>api/clear-preview-mode-cookies/</code> لتفعيل مسار API. وإن كنت تستدعي هذا المسار مستخدمًا المكوّن <code>next/link</code>، فلا بد من تمرير <code>prefetch={false}</code> لمنع استدعاء <code>clearPreviewData</code> خلال الإحضار المسبق للرابط.

=== تحديد المدة الزمنية لنمط الاستعراض ===
تأخذ الدالة <code>setPreviewData</code> معاملًا اختياريًا ثانيًا يُفترض أن يكون كائن خيارات. يقبل هذا الكائن المفاتيح التالية:

* <code>maxAge</code>: يحدد عدد الثواني التي ينبغي أن تدومها جلسة العمل.
<syntaxhighlight lang="javascript">
setPreviewData(data, {
  maxAge: 60 * 60, //تبقى ملفات تعريف الارتباط الخاصة بالاستعراض ساعة
})
</syntaxhighlight>

=== حدود حجم بيانات الاستعراض <code>previewData</code> ===
بإمكانك تمرير كائن إلى الدالة <code>setPreviewData</code> ومن ثم جعله متاحًا للاستخدام من قبل الدالة <code>getStaticProps</code>. لكن ونظرًا لتخزين البيانات في ملفات تعريف الارتباط، فهنالك محدودية في حجم الكائن، وتحدد حاليًا بحوالي 2 كيلوبايت.

=== العمل مع الدالة <code>getServerSideProps</code> ===
يعمل نمط الاستعراض مع الدالة <code>getServerSideProps</code> أيضًا، وسيكون متاحًا مع الكائن الذي يضم <code>preview</code> و <code>previewData</code>.

=== العمل مع مسارات API ===
يمكن لمسارات API الوصول إلى قيم <code>preview</code> و <code>previewData</code> ضمن الكائن الذي يُطلب. إليك مثالًا:<syntaxhighlight lang="javascript">
export default function myApiRoute(req, res) {
  const isPreview = req.preview
  const previewData = req.previewData
  // ...
}
</syntaxhighlight>

=== مفاتيح وملفات ارتباط خاصة لكل عملية بناء <code>next build</code> ===
تتغير قيم ملفات تعريف الارتباط التي تفرض حالة الاستعراض ومفتاح الاستيثاق لتشفير بيانات <code>previewData</code> مع اكتمال كل عملية بناء <code>next build</code>. يضمن ذلك عدم القدرة على تخمين قيم ملفات تعريف الارتباط.<blockquote>'''ملاحظة''': عليك أن تسمح باستخدام ملفات تعريف ارتباط مصدرها طرف آخر وإذنًا بالوصول إلى التخزين المحلي، لاختبار نمط الاستعراض محليًا ضمن متصفحك عبر طلبات HTTP.</blockquote>

== اقرأ أيضًا ==

* [[Next.js/data fetching|إحضار البيانات في Next.js]].
* [[Next.js/api routes|مسارات API في Next.js]].
* [[Next.js/environment variables|متغيرات البيئة في Next.js]].
* [[Next.js/dynamic import|الإدراج الديناميكي للوحدات البرمجية في Next.js]]. 

== المصادر ==

* الصفحة [https://nextjs.org/docs/advanced-features/preview-mode Preview Mode] من توثيق Next.js الرسمي.