المستندات المخصصة في Next.js باستخدام المكوّن `Document`

يمكن للمكوّن Document أن يُحدّث العنصرين <html> و <body> المستخدمان في تصيير الصفحة. ويُصيّر هذا الملف في جانب الخادم فقط، وبالتالي لا يمكن استخدام معالجات الأحداث مثل 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> حتى تُصيًر الصفحة بالشكل الصحيح.

التحفظات على استخدام `document`

يختلف المكوّن </ 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. ويكافئ الكائن الذي نعرضه في الشيفرة التالية الكائن الذي تتلقاه في الدالة 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 مع المستندات المخصصة في Next.js

بإمكانك استخدام النوع المدمج 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 الرسمي.

التحفظات على استخدام document

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

استخدام TypeScript مع المستندات المخصصة في Next.js

المصادر

التحفظات على استخدام `document`

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