استخدام مستند مخصص Document في Next.js

ملاحظة: بدأت Next.js في الإصدار 13 دعم استخدام المجلد /app كنسخة تجريبية، ويمكن باستعمال المجلد ذاك دعم التخطيطات layouts والوجهات المتداخلة nested routes واستعمال مكونات خادم Server افتراضيًا، كما يمكنك جلب بيانات تُستعمل في كل تطبيقك.

يمكن للمكوّن Document أن يُحدّث العنصرين <html> و <body> المستخدمان في تصيير صفحة Page. ويُصيّر هذا الملف في جانب الخادم فقط، وبالتالي لا يمكن استخدام معالجات الأحداث مثل onClick ضمن document_. ولكي تخصص المكوّن Document الافتراضي، أنشئ الملف pages/_document.js كما يلي:

import { Html, Head, Main, NextScript } from 'next/document'

export default function Document() {
  return (
    <Html>
      <Head />
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  )
}

تمثل الشيفرة السابقة المكوّن Document الافتراضي الذي تضيفه Next.js، ويُسمح بالسمات المخصصة على شكل خاصيات. فقد ترغب مثلًا في إضافة lang="en" إلى العنصر <html>:

<Html lang="en">

أو أن تضيف السمة className إلى العنصر body:

<body className="bg-white">

ولا بد من استخدام المكوّنات <Html> و </ Head> و </ Main> و < /NextScript> حتى تُصيًر الصفحة بالشكل الصحيح.

محاذير

يختلف المكوّن </ Head> الذي يُستخدم في document_ عن مكوّن الترويسة next/head، إذ ينبغي أن يُستخدم هنا للترويسات <head> المشتركة بين عدة صفحات فقط. أما في بقية الحالات مثل حالة استخدام العنصر <title>، فننصح باستخدام next/head في صفحتك أو مكوّناتك.
لا تُهيأ مكوّنات React الموجودة خارج </ Main> من قبل المتصفح، فلا تضع فيها ما يخص منطق التطبيق أو تنسيقات CSS مخصصة (مثل styled-jsx ). وإن أردت مكوّنات تتشاركها جميع صفحاتك (كالقوائم أو شريط الأدوات) استخدم المكوّن layout.
لا يدعم المكوّن Document حاليًا طرق إحضار البيانات في Next.js مثل getStaticProps أو getServerSideProps.

تخصيص التابع `renderPage`

تنويه: هذا الموضوع متقدم ويُستخدم فقط لتدعم المكتبات مثل CSS-in-JS للتصيير من جانب الخادم. لن تحتاج إلى ذلك عند استخدام الدعم المدمج لتنسيقات styled-jsx.

ننصحك أن تتحاشى استخدام نسخ مخصصة من الدالة getInitialProps والتابع renderPage قدر الإمكان وذلك استعدادًا لمتطلبات React 18. ويكافئ الكائن ctx الذي نعرضه في الشيفرة التالية الكائن الذي تتلقاه في الدالة getInitialProps بالإضافة إلى التابع renderPage:

import Document, { Html, Head, Main, NextScript } from 'next/document'

class MyDocument extends Document {
  static async getInitialProps(ctx) {
    const originalRenderPage = ctx.renderPage

    //بشكل متزامن React شغّل منطق تصيير 
    ctx.renderPage = () =>
      originalRenderPage({
        // React يفيد في تغليف كامل شجرة 
        enhanceApp: (App) => App,
        // يفيد في التغليف على أساس الصفحة
        enhanceComponent: (Component) => Component,
      })
    //`renderPage` إذ تضم الآن التابع المخصص getInitialProps شغّل الدالة الأب 

    const initialProps = await Document.getInitialProps(ctx)

    return initialProps
  }

  render() {
    return (
      <Html>
        <Head />
        <body>
          <Main />
          <NextScript />
        </body>
      </Html>
    )
  }
}

export default MyDocument

ملاحظة: لا تُستدعى الدالة getInitialProps ضمن المستند المخصص document_ أثناء التنقلات من جانب العميل.

استخدام TypeScript

بإمكانك استخدام النوع المدمج DocumentContext وتغيّر اسم الملف إلى pages/_document.tsx/. كالتالي:

import Document, { DocumentContext } from 'next/document'

class MyDocument extends Document {
  static async getInitialProps(ctx: DocumentContext) {
    const initialProps = await Document.getInitialProps(ctx)

    return initialProps
  }
}

export default MyDocument

المصادر

الصفحة Custom Document من توثيق Next.js الرسمي.

محاذير

تخصيص التابع renderPage

استخدام TypeScript

المصادر

تخصيص التابع `renderPage`