error.js

يحدد ملف error حدود واجهة المستخدم (UI boundary) لمعالجة الأخطاء في مقطع المسار.

وهو مفيد لالتقاط الأخطاء غير المتوقعة التي تحدث في مكونات الخادم (Server Components) ومكونات العميل (Client Components) وعرض واجهة مستخدم بديلة.

'use client' // مكونات الأخطاء يجب أن تكون من نوع مكونات العميل

import { useEffect } from 'react'

export default function Error({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  useEffect(() => {
    // تسجيل الخطأ في خدمة تقارير الأخطاء
    console.error(error)
  }, [error])

  return (
    <div>
      <h2>حدث خطأ ما!</h2>
      <button
        onClick={
          // محاولة الاسترداد عن طريق إعادة عرض المقطع
          () => reset()
        }
      >
        حاول مرة أخرى
      </button>
    </div>
  )
}

'use client' // مكونات الأخطاء يجب أن تكون من نوع مكونات العميل

import { useEffect } from 'react'

export default function Error({ error, reset }) {
  useEffect(() => {
    // تسجيل الخطأ في خدمة تقارير الأخطاء
    console.error(error)
  }, [error])

  return (
    <div>
      <h2>حدث خطأ ما!</h2>
      <button
        onClick={
          // محاولة الاسترداد عن طريق إعادة عرض المقطع
          () => reset()
        }
      >
        حاول مرة أخرى
      </button>
    </div>
  )
}

الخصائص (Props)

`error`

نسخة من كائن Error يتم تمريرها إلى مكون العميل error.js.

`error.message`

رسالة الخطأ.

بالنسبة للأخطاء الممررة من مكونات العميل، ستكون هذه الرسالة الأصلية للخطأ.
بالنسبة للأخطاء الممررة من مكونات الخادم، ستكون رسالة خطأ عامة لتجنب تسريب تفاصيل حساسة. يمكن استخدام errors.digest لمطابقة الخطأ المقابل في سجلات الخادم.

`error.digest`

تجزئة (hash) يتم إنشاؤها تلقائيًا للخطأ الذي تم طرحه في مكون الخادم. يمكن استخدامها لمطابقة الخطأ المقابل في سجلات الخادم.

`reset`

وظيفة لإعادة تعيين حدود الخطأ. عند تنفيذها، تحاول الوظيفة إعادة عرض محتويات حدود الخطأ. إذا نجحت، يتم استبدال مكون الخطأ الاحتياطي بنتيجة إعادة العرض.

يمكن استخدامها لدفع المستخدم لمحاولة الاسترداد من الخطأ.

معلومة مفيدة:

حدود error.js يجب أن تكون مكونات عميل.

في إصدارات الإنتاج، يتم إزالة التفاصيل المحددة للأخطاء الممررة من مكونات الخادم لتجنب تسريب معلومات حساسة.

حدود error.js لن تتعامل مع الأخطاء المطروحة في مكون layout.js في نفس المقطع لأن حدود الخطأ متداخلة داخل مكون التخطيط ذلك.

للتعامل مع الأخطاء لتخطيط معين، ضع ملف error.js في المقطع الأب للتخطيط.

للتعامل مع الأخطاء داخل التخطيط الجذر أو القالب، استخدم متغيرًا من error.js يسمى app/global-error.js.

`global-error.js`

للتعامل مع الأخطاء في layout.js الجذر بشكل خاص، استخدم متغيرًا من error.js يسمى app/global-error.js موجود في دليل الجذر app.

'use client'

export default function GlobalError({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  return (
    <html>
      <body>
        <h2>حدث خطأ ما!</h2>
        <button onClick={() => reset()}>حاول مرة أخرى</button>
      </body>
    </html>
  )
}

'use client'

export default function GlobalError({ error, reset }) {
  return (
    <html>
      <body>
        <h2>حدث خطأ ما!</h2>
        <button onClick={() => reset()}>حاول مرة أخرى</button>
      </body>
    </html>
  )
}

معلومة مفيدة:

global-error.js يحل محل layout.js الجذر عند التنشيط ولذلك يجب أن يحدد علامات <html> و <body> الخاصة به.

أثناء تصميم واجهة مستخدم للأخطاء، قد تجد أنه من المفيد استخدام أدوات مطوري React لتبديل حدود الأخطاء يدويًا.

not-found.js

يستخدم ملف not-found لعرض واجهة المستخدم عند استدعاء دالة notFound() داخل مقطع مسار.

سجل الإصدارات

الإصدار	التغييرات
`v13.1.0`	تم تقديم `global-error`.
`v13.0.0`	تم تقديم `error`.

On this page