حدود الأخطاء في React: التقاط أخطاء العرض مع بديل

حدود الأخطاء (error boundary) مكوّن React يلتقط الأخطاء المرمية أثناء عرض المكوّنات بداخله ويعرض واجهة بديلة بدلًا من انهيار التطبيق كله. يجب أن تكون مكوّن صنف يعرّف static getDerivedStateFromError، لأنه لا يوجد خطاف لذلك. تكتبها مرة واحدة وتغلّف بها أي جزء من الشجرة.

اضغط "Break the profile" لتجعل الابن يرمي خطأ أثناء العرض.

// This throws on purpose: Profile throws during render after you press the button.
import { Component, useState } from 'react';

class ErrorBoundary extends Component {
    state = { error: null };

    static getDerivedStateFromError(error) {
        return { error };
    }

    componentDidCatch(error, info) {
        console.log('caught:', error.message);
    }

    reset = () => {
        this.props.onReset();
        this.setState({ error: null });
    };

    render() {
        if (this.state.error) {
            return (
                <div style={{ padding: 12, background: '#fdecea' }}>
                    <p>Something went wrong: {this.state.error.message}</p>
                    <button onClick={this.reset}>Try again</button>
                </div>
            );
        }
        return this.props.children;
    }
}

function Profile({ broken }) {
    if (broken) {
        throw new Error('Profile could not render');
    }
    return <p>Ada Lovelace, mathematician</p>;
}

export default function App() {
    const [broken, setBroken] = useState(false);

    return (
        <div>
            <button onClick={() => setBroken(true)}>Break the profile</button>
            <p>This line is outside the boundary and stays.</p>
            <ErrorBoundary onReset={() => setBroken(false)}>
                <Profile broken={broken} />
            </ErrorBoundary>
        </div>
    );
}

يُستبدل الملف الشخصي بالبديل، ويستمر باقي الصفحة في العمل. تُظهر وحدة التحكم الخطأ مرتين: تسجّل React كل خطأ ملتقط بـ console.error، ويسجّله componentDidCatch مرة أخرى. يمسح "Try again" السبب (broken) وخطأ الحدود، فيُعرض الملف الشخصي من جديد. احذف this.props.onReset(); من reset فيرمي Try again مباشرة عائدًا إلى البديل، لأن شيئًا لم يصلح السبب.

كيف يعمل الصنف

تابعان يجعلان الصنف حدود أخطاء:

• يعمل static getDerivedStateFromError(error) أثناء العرض، مباشرة بعد أن يرمي ابن خطأ. ويُرجع تحديث الحالة الذي يحوّل الحدود إلى بديلها. ويجب أن يكون نقيًا: لا تسجيل، ولا طلبات.
• يعمل componentDidCatch(error, info) بعد أن يصبح البديل على الشاشة. استخدمه للآثار الجانبية مثل إرسال الخطأ إلى خدمة تقارير. وتسرد info.componentStack المكوّن الذي رمى الخطأ والمكوّنات فوقه.

class ErrorBoundary extends Component {
    state = { error: null };

    static getDerivedStateFromError(error) {
        return { error }; // switch to the fallback
    }

    componentDidCatch(error, info) {
        reportError(error, info.componentStack); // your logging service
    }

    render() {
        if (this.state.error) return this.props.fallback;
        return this.props.children;
    }
}

لا يوجد مكافئ بالخطافات، لذا حتى التطبيق المكتوب بمكوّنات الدوال فقط يحتاج إلى هذا الصنف الواحد. تشرح صفحة مكوّنات الأصناف صيغة الأصناف إن كانت جديدة عليك.

ما تلتقطه الحدود وما لا تلتقطه

تلتقط الحدود الأخطاء التي تحدث بينما تعمل React على المكوّنات داخلها:

• العرض (جسم مكوّن الدالة، أو render الخاص بالصنف)،
• توابع دورة الحياة والمُنشئات في مكوّنات الأصناف الأبناء،
• التأثيرات (useEffect وuseLayoutEffect) ودوال المرجع،
• الوعد المرفوض الذي يُقرأ بـ use، وفي React 19 الخطأ الذي يرميه إجراء نموذج أو دالة تُمرَّر إلى startTransition المأخوذة من useTransition.

وهي لا تلتقط:

• الأخطاء في معالجات الأحداث،
• الكود غير المتزامن الذي تبدؤه بنفسك: setTimeout ودوال .then() وawait في معالج حدث،
• الأخطاء في render الخاص بالحدود نفسها (تلتقطها الحدود الأعلى التالية)،
• الأخطاء أثناء العرض على الخادم.

تُستثنى معالجات الأحداث لأنها لا تكسر العرض. ما زالت الشاشة في حالة صالحة، فيكفي try/catch في المعالج. وإذا أردت فعلًا أن تظهر الحدود، فخزّن الخطأ في الحالة وارمِه في العرض التالي:

// This throws on purpose: the second button forwards an async error to the boundary.
import { Component, useState } from 'react';

class ErrorBoundary extends Component {
    state = { error: null };
    static getDerivedStateFromError(error) {
        return { error };
    }
    render() {
        if (this.state.error) return <p style={{ color: 'crimson' }}>Boundary: {this.state.error.message}</p>;
        return this.props.children;
    }
}

function loadReport() {
    // Stands in for a request that fails
    return new Promise((_, reject) => setTimeout(() => reject(new Error('Report failed to load')), 150));
}

function Report() {
    const [error, setError] = useState(null);
    if (error) throw error; // thrown during render, so the boundary sees it

    async function handleUnsafe() {
        await loadReport(); // rejects: the boundary never hears about it
    }

    async function handleForwarded() {
        try {
            await loadReport();
        } catch (e) {
            setError(e);
        }
    }

    return (
        <div>
            <button onClick={handleUnsafe}>Load (error escapes)</button>
            <button onClick={handleForwarded}>Load (error forwarded)</button>
        </div>
    );
}

export default function App() {
    return (
        <ErrorBoundary>
            <Report />
        </ErrorBoundary>
    );
}

يترك الزر الأول الأزرار على الشاشة ولا يطبع إلا خطأ غير ملتقط في وحدة التحكم. أما الثاني فيلتقط الرفض، ويخزّنه، فتتولى الحدود الأمر.

أين تضع الحدود

حدود واحدة حول التطبيق كله توقف الشاشة البيضاء، لكن أي خطأ صغير عندها يستبدل كل شيء. ضع حدودًا حول الأجزاء التي يمكن أن تفشل باستقلال: عنصر في الشريط الجانبي، أو رسم بياني، أو كل مسار. عندها يكلّف الفشل المستخدم لوحة واحدة، لا الصفحة.

// This throws on purpose: the Stocks widget fails during render.
import { Component } from 'react';

class ErrorBoundary extends Component {
    state = { error: null };
    static getDerivedStateFromError(error) {
        return { error };
    }
    render() {
        if (this.state.error) {
            return <div style={{ padding: 8, background: '#fdecea' }}>{this.props.name} is unavailable.</div>;
        }
        return this.props.children;
    }
}

function Weather() {
    return <div style={{ padding: 8, background: '#eef6ee' }}>Weather: 21 °C</div>;
}

function Stocks() {
    const prices = undefined; // imagine the data came back empty
    return <div style={{ padding: 8 }}>Stocks: {prices.length} prices</div>;
}

export default function App() {
    return (
        <div style={{ display: 'grid', gap: 8 }}>
            <ErrorBoundary name="Weather">
                <Weather />
            </ErrorBoundary>
            <ErrorBoundary name="Stocks">
                <Stocks />
            </ErrorBoundary>
        </div>
    );
}

لا تعرض البديل إلا لوحة Stocks. انقل العنصرين إلى <ErrorBoundary> واحدة فتختفي لوحة Weather العاملة معها.

ومن دون أي حدود، تزيل React الشجرة كلها من الشاشة عندما لا يُلتقط خطأ عرض. الصفحة الفارغة أكثر أمانًا من صفحة مكسورة تعرض بيانات خاطئة، لكن المستخدمين يرونها كانهيار.

مكتبة react-error-boundary

تغلّف الحزمة react-error-boundary الصنف نيابة عنك وتضيف أدوات مساعدة لإعادة الضبط. وهي غير متاحة في هذا المحرر، فإليك بها في كتلة ثابتة:

import { ErrorBoundary, useErrorBoundary } from 'react-error-boundary';

function Fallback({ error, resetErrorBoundary }) {
    return (
        <div role="alert">
            <p>Something went wrong: {error.message}</p>
            <button onClick={resetErrorBoundary}>Try again</button>
        </div>
    );
}

<ErrorBoundary FallbackComponent={Fallback} onReset={() => refetch()} resetKeys={[userId]}>
    <Profile userId={userId} />
</ErrorBoundary>;

// Inside a child: hand an async error to the boundary
const { showBoundary } = useErrorBoundary();
fetchData().catch(showBoundary);

تعيد resetKeys ضبط الحدود عندما تتغير أي قيمة مسرودة، وتؤدي showBoundary حيلة «خزّن وارمِ» من المثال السابق.

الإبلاغ عن الأخطاء في React 19

تبلّغ React 19 عن الأخطاء بطريقة جديدة. الأخطاء التي تلتقطها الحدود تُسجَّل مرة واحدة بـ console.error، والأخطاء غير الملتقطة تذهب إلى window.reportError. ولإرسالها إلى خدمتك الخاصة، مرّر خيارات إلى createRoot. كل خيار يستبدل التسجيل الافتراضي المقابل:

import { createRoot } from 'react-dom/client';

const root = createRoot(document.getElementById('root'), {
    onCaughtError(error, errorInfo) {
        // an error boundary caught it
        logToService('caught', error, errorInfo.componentStack);
    },
    onUncaughtError(error, errorInfo) {
        // no boundary caught it, and React removed the tree
        logToService('uncaught', error, errorInfo.componentStack);
    },
    onRecoverableError(error, errorInfo) {
        // React recovered by itself, for example after a hydration mismatch
        logToService('recovered', error, errorInfo.componentStack);
    },
});
root.render(<App />);

onRecoverableError للأخطاء التي أصلحتها React دون مساعدتك، مثل عدم تطابق في الإماهة أو خطأ عرض زال عندما أعادت React المحاولة. ويأخذ hydrateRoot الخيارات الثلاثة نفسها.

أخطاء شائعة

وضع الحدود داخل المكوّن الذي يرمي الخطأ. لا تلتقط الحدود إلا الأخطاء من أبنائها. إذا عرض Profile المكوّن <ErrorBoundary> حول JSX الخاصة به ثم رمى خطأ في جسمه، يتجاوزها الخطأ إلى الحدود الأعلى التالية. غلّف المكوّن من أبيه.

آثار جانبية في getDerivedStateFromError. يعمل أثناء العرض وقد يعمل أكثر من مرة، فاقصره على إرجاع الحالة. مكان التسجيل هو componentDidCatch أو onCaughtError على الجذر.

إعادة ضبط لا تصلح شيئًا. مسح خطأ الحدود يعرض الأبناء أنفسهم بـ props نفسها. إذا رموا خطأ من جديد، يعود المستخدم إلى البديل. غيّر ما سبب الخطأ أولًا (أعد الجلب، أو امسح المدخل السيئ، أو غيّر key)، ثم امسح الخطأ، كما يفعل المثال الأول بـ onReset.

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

بدائل تخفي الخطأ عنك. الرسالة الودية مناسبة للمستخدمين، لكن تأكد أن الخطأ ما زال يصل إلى سجلاتك. تسجّل React 19 الأخطاء الملتقطة في وحدة التحكم افتراضيًا؛ وفي الإنتاج تلك الوحدة هي وحدة مستخدمك، فأرسل الأخطاء إلى خدمة من componentDidCatch أو onCaughtError.

تقترن حدود الأخطاء بشكل طبيعي مع <Suspense>: يتولى Suspense «ليس جاهزًا بعد»، وتتولى الحدود «فشل». ضع الحدود خارج Suspense، كما في أمثلة use، ليغطي مكوّن واحد التحميل والنجاح والفشل.