الخطاف useEffect في React: الاعتماديات والتنظيف وأمثلة

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

import { useState, useEffect } from 'react';

export default function App() {
    const [count, setCount] = useState(0);

    useEffect(() => {
        console.log('effect ran, count is', count);
    }, [count]);

    return (
        <button onClick={() => setCount(count + 1)}>
            Clicked {count} times
        </button>
    );
}

افتح وحدة التحكم أسفل المعاينة: يسجّل التأثير مرة عندما يظهر المكوّن، ثم مرة أخرى بعد كل نقرة. غيّر [count] إلى [] وانقر مرة أخرى: يبقى التأثير صامتًا بعد السجل الأول.

الصيغة

useEffect(() => {
    // setup: runs after the render is on the screen
    return () => {
        // cleanup: runs before the next setup, and on unmount
    };
}, [dependencies]);

• الوسيط الأول هو دالة الإعداد. يمكنها أن تُرجع دالة تنظيف، أو لا شيء.
• الوسيط الثاني هو مصفوفة الاعتماديات: كل قيمة من المكوّن تقرؤها دالة الإعداد (props والحالة وأي شيء محسوب منهما).
• استدعِ useEffect في المستوى الأعلى من المكوّن، مثل كل خطاف.

التأثيرات تعمل بعد العرض

العرض هو استدعاء React لدالة مكوّنك لتعرف ما يجب أن تعرضه الشاشة. تنتظر التأثيرات حتى ينتهي ذلك العمل ويتحدث DOM، فتكون الصفحة داخل التأثير تعرض القيم الجديدة بالفعل.

import { useState, useEffect } from 'react';

export default function App() {
    const [count, setCount] = useState(0);

    console.log('1. render, count =', count);

    useEffect(() => {
        const text = document.querySelector('button').textContent;
        console.log('2. effect, the button now says:', text);
    });

    return <button onClick={() => setCount(count + 1)}>Count: {count}</button>;
}

كل نقرة تسجّل العرض أولًا والتأثير ثانيًا، ويقرأ التأثير نص الزر الذي كتبته React للتو. لهذا تنتمي قراءة DOM أو بدء مؤقت أو الاتصال بخادم إلى تأثير لا إلى جسم المكوّن: يعمل الجسم أثناء العرض، قبل أن يكون أي شيء على الشاشة، وقد تستدعيه React أكثر مما تتوقع.

تعمل التأثيرات عادة بعد أن يرسم المتصفح الشاشة. وعندما يجب أن يقيس التأثير DOM قبل الرسم، استخدم useLayoutEffect بدلًا منه، الذي يعمل دائمًا قبل الرسم.

مصفوفة الاعتماديات: ثلاثة أشكال

تقرر مصفوفة الاعتماديات متى يعمل التأثير من جديد. هناك ثلاثة أشكال، وتستخدمها هذه الكتلة كلها لتراقب الفرق.

import { useState, useEffect } from 'react';

export default function App() {
    const [a, setA] = useState(0);
    const [b, setB] = useState(0);

    useEffect(() => {
        console.log('no array: after every render');
    });

    useEffect(() => {
        console.log('[]: once, after the first render');
    }, []);

    useEffect(() => {
        console.log('[a]: a is now', a);
    }, [a]);

    return (
        <div>
            <button onClick={() => setA(a + 1)}>a + 1 (a = {a})</button>{' '}
            <button onClick={() => setB(b + 1)}>b + 1 (b = {b})</button>
        </div>
    );
}

عند التحميل تسجّل التأثيرات الثلاثة. انقر a + 1 فيعمل اثنان منها: الذي بلا مصفوفة والذي يعتمد على a. وانقر b + 1 فلا يعمل إلا الذي بلا مصفوفة، لأن شيئًا في [] أو [a] لم يتغير.

تقارن React كل اعتمادية بقيمتها السابقة باستخدام Object.is. تُقارن الأرقام والنصوص والقيم المنطقية بالقيمة. أما الكائنات والمصفوفات والدوال فتُقارن بالهوية، وهذا مهم جدًا (انظر أدناه).

لا تحذف قيمة من المصفوفة لتجعل التأثير يعمل أقل. سيظل التأثير يستخدم القيمة من عرض قديم. تلتقط قاعدة الفحص react-hooks/exhaustive-deps هذا الخطأ؛ وهي جزء من إعداد ESLint الذي يتضمنه قالب React في Vite وإعداد ESLint في Next.js.

التنظيف

تبدأ تأثيرات كثيرة شيئًا يجب إيقافه: اتصالًا، أو اشتراكًا، أو مؤقتًا. أرجع دالة من التأثير فتستدعيها React في لحظتين: قبل أن يعمل التأثير من جديد باعتماديات جديدة مباشرة، وعندما يغادر المكوّن الشاشة (الإزالة).

import { useState, useEffect } from 'react';

function connect(room) {
    console.log('connect to', room);
    return { disconnect: () => console.log('disconnect from', room) };
}

function ChatRoom({ room }) {
    useEffect(() => {
        const connection = connect(room);
        return () => connection.disconnect();
    }, [room]);

    return <p>Welcome to #{room}</p>;
}

export default function App() {
    const [room, setRoom] = useState('general');
    const [show, setShow] = useState(true);

    return (
        <div>
            <select value={room} onChange={(e) => setRoom(e.target.value)}>
                <option>general</option>
                <option>music</option>
                <option>travel</option>
            </select>{' '}
            <button onClick={() => setShow(!show)}>{show ? 'Hide' : 'Show'} chat</button>
            {show && <ChatRoom room={room} />}
        </div>
    );
}

اختر غرفة أخرى: تُظهر وحدة التحكم disconnect from general ثم connect to music. يُغلق الاتصال القديم دائمًا قبل أن يُفتح الجديد. انقر Hide فتعمل دالة التنظيف مرة أخيرة، لأن ChatRoom أُزيل.

الدالة connect هنا بديل عن عميل محادثة أو WebSocket حقيقي. والشكل نفسه لأي منها: أنشئه في الإعداد، وأغلقه في التنظيف.

مسح مؤقت

المؤقت الذي يبدأ في تأثير يظل يعمل بعد زوال المكوّن ما لم توقفه دالة التنظيف.

import { useState, useEffect } from 'react';

function Ticker() {
    const [seconds, setSeconds] = useState(0);

    useEffect(() => {
        console.log('start timer');
        const id = setInterval(() => {
            console.log('tick');
            setSeconds((s) => s + 1);
        }, 1000);
        return () => {
            console.log('cleanup: clear timer');
            clearInterval(id);
        };
    }, []);

    return <p>{seconds} seconds</p>;
}

export default function App() {
    const [show, setShow] = useState(true);
    return (
        <div>
            <button onClick={() => setShow(!show)}>{show ? 'Hide' : 'Show'} timer</button>
            {show && <Ticker />}
        </div>
    );
}

احذف السطر clearInterval(id);، ثم أخفِ المؤقت: يظل tick يصل إلى وحدة التحكم من مكوّن لم يعد موجودًا. وكل Show يبدأ مؤقتًا آخر.

لاحظ setSeconds((s) => s + 1). يعمل التأثير مرة واحدة، فستقرأ setSeconds(seconds + 1) العادية القيمة seconds من العرض الأول إلى الأبد وتتوقف عند 1. أما دالة التحديث فتحصل دائمًا على أحدث قيمة.

إزالة مستمع أحداث

يتبع مستمعو الأحداث على window أو document النمط نفسه. مرّر إلى removeEventListener الدالة نفسها التي مررتها إلى addEventListener:

useEffect(() => {
    function handleKeyDown(e) {
        if (e.key === 'Escape') onClose();
    }
    window.addEventListener('keydown', handleKeyDown);
    return () => window.removeEventListener('keydown', handleKeyDown);
}, [onClose]);

الحلقة اللانهائية

التأثير الذي يضبط قيمة حالة يعتمد عليها أيضًا يبدأ حلقة: تتغير الحالة، فتعرض React، وقد تغيّرت الاعتمادية، فيعمل التأثير ويضبط الحالة من جديد.

// Never stops: every render runs the effect, every effect causes a render
useEffect(() => {
    setCount(count + 1);
});

// Same loop: count changes, so the effect runs again
useEffect(() => {
    setCount(count + 1);
}, [count]);

يُعرض المكوّن بلا نهاية ويبقى التبويب مشغولًا. لا توقف React هذه الحلقة: في التطوير تسجّل خطأ "Maximum update depth exceeded" في وحدة التحكم، وفي الإنتاج لا تسجّل شيئًا. تشغّل هذه الكتلة النسخة الثانية بشرط توقف، لتراقب الحلقة دون تجميد الصفحة:

import { useState, useEffect } from 'react';

export default function App() {
    const [count, setCount] = useState(0);

    console.log('render', count);

    useEffect(() => {
        if (count < 5) {
            setCount(count + 1);
        }
    }, [count]);

    return <p>count = {count}</p>;
}

تسجّل وحدة التحكم من render 0 إلى render 5: ستة عروض لتركيب واحد، كل منها بدأه التأثير. والإصلاح يعتمد على ما قصدته:

• أردته مرة واحدة. استخدم [] وصيغة دالة التحديث، setCount((c) => c + 1)، حتى لا تكون count اعتمادية.
• تحسب قيمة من حالة أخرى. لا تخزّنها أصلًا؛ احسبها أثناء العرض، كما يظهر في القسم الأخير من هذه الصفحة.
• تستجيب لإجراء من المستخدم. ضع الكود في معالج الحدث.

الكائنات والدوال كاعتماديات

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

import { useState, useEffect } from 'react';

export default function App() {
    const [query, setQuery] = useState('react');
    const [dark, setDark] = useState(false);

    const options = { query, limit: 10 };

    useEffect(() => {
        console.log('search for', options.query);
    }, [options]);

    return (
        <div style={{ background: dark ? '#222' : '#fff', color: dark ? '#fff' : '#222', padding: 12 }}>
            <input value={query} onChange={(e) => setQuery(e.target.value)} />{' '}
            <button onClick={() => setDark(!dark)}>Toggle dark</button>
        </div>
    );
}

لا علاقة لتبديل الألوان بالبحث، ومع ذلك يسجّل كل تبديل search for react من جديد. انقل السطر options إلى داخل التأثير وغيّر المصفوفة إلى [query]: تصمت عمليات التبديل ولا يشغّل البحث إلا الكتابة في الحقل.

هذا هو الإصلاح العام. أنشئ الكائنات والدوال داخل التأثير الذي يستخدمها، واعتمد على القيم البسيطة التي تُبنى منها. وعندما يجب أن تعيش دالة خارج التأثير، يُبقي useCallback هويتها ثابتة بين مرات العرض.

لماذا تعمل التأثيرات مرتين في التطوير

مع تفعيل <StrictMode> (يغلّف تطبيق Vite الجديد الجذر به، ويفعّله App Router في Next.js افتراضيًا)، تجري React اختبارًا في التطوير: تركّب كل مكوّن، وتشغّل تأثيراته، وتشغّل دوال تنظيفها، ثم تشغّل التأثيرات مرة أخرى. بالنسبة لغرفة المحادثة أعلاه، تُظهر وحدة تحكم التطوير:

connect to general
disconnect from general
connect to general

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

قد لا تحتاج إلى تأثير

التأثيرات للمزامنة مع أنظمة خارج React. واستخدامان شائعان أفضل من دونها.

القيم المحسوبة من props أو الحالة. احسبها أثناء العرض. تخزينها في الحالة ومزامنتها بتأثير يكلّف عرضًا إضافيًا، وأول هذين العرضين يضع قيمة قديمة في DOM:

import { useState, useEffect } from 'react';

function WithEffect({ first, last }) {
    const [fullName, setFullName] = useState('');
    useEffect(() => {
        setFullName(first + ' ' + last);
    }, [first, last]);
    console.log('WithEffect renders:', JSON.stringify(fullName));
    return <p>{fullName}</p>;
}

function Computed({ first, last }) {
    const fullName = first + ' ' + last;
    console.log('Computed renders:', JSON.stringify(fullName));
    return <p>{fullName}</p>;
}

export default function App() {
    const [first, setFirst] = useState('Ada');
    return (
        <div>
            <button onClick={() => setFirst(first === 'Ada' ? 'Grace' : 'Ada')}>
                Switch name
            </button>
            <WithEffect first={first} last="Lovelace" />
            <Computed first={first} last="Lovelace" />
        </div>
    );
}

كل نقرة تعرض WithEffect مرتين، وعرضه الأول ما زال يُظهر الاسم القديم. أما Computed فيُعرض مرة واحدة بالقيمة الصحيحة.

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

useEffectEvent

أحيانًا يحتاج التأثير إلى أحدث قيمة لـ prop دون أن يعمل من جديد عندما تتغير. في غرفة المحادثة، ينبغي أن يستخدم الإشعار theme الحالية، لكن تبديل السمة ينبغي ألا يعيد الاتصال. تضيف React 19.2 الخطاف useEffectEvent لهذا:

import { useEffect, useEffectEvent } from 'react';

function ChatRoom({ roomId, theme }) {
    const onConnected = useEffectEvent(() => {
        showNotification('Connected!', theme); // always the latest theme
    });

    useEffect(() => {
        const connection = createConnection(roomId);
        connection.on('connected', () => onConnected());
        connection.connect();
        return () => connection.disconnect();
    }, [roomId]); // theme is not a dependency
}

الدالة المأخوذة من useEffectEvent مخصصة للاستدعاء داخل التأثيرات فقط. لا تمررها إلى مكوّنات أخرى ولا تدرجها في مصفوفة الاعتماديات.