قواعد الخطافات في React: لماذا يهم الترتيب وكيف تصلح الأخطاء

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

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

import { useState } from 'react';

const slots = [];
let index = 0;

function toyUseState(initial) {
    const i = index++;
    if (!(i in slots)) slots[i] = initial;
    return [slots[i]];
}

function renderForm(showNickname) {
    index = 0;
    const [name] = toyUseState('Ada');
    let nickname = '(no hook called)';
    if (showNickname) {
        [nickname] = toyUseState('Countess');
    }
    const [age] = toyUseState(36);
    return { name, nickname, age };
}

export default function App() {
    const [result, setResult] = useState(() => renderForm(true));
    return (
        <div>
            <button onClick={() => setResult(renderForm(true))}>Render with nickname</button>{' '}
            <button onClick={() => setResult(renderForm(false))}>Render without nickname</button>
            <p>
                name: {String(result.name)}, nickname: {String(result.nickname)}, age:{' '}
                {String(result.age)}
            </p>
            <p style={{ color: '#666' }}>slots: {JSON.stringify(slots)}</p>
        </div>
    );
}

يملأ العرض الأول ثلاث خانات: Ada وCountess و36. انقر "Render without nickname": يُتخطى الاستدعاء الشرطي، فيأخذ استدعاء age الخانة 1 ويقرأ Countess. تلاحظ React الحقيقية عدم التطابق في بعض الحالات وترمي خطأ، وفي حالات أخرى تسلّم القيمة الخاطئة إلى الخطاف الخاطئ، وهذا أسوأ. انقل استدعاء toyUseState('Countess') إلى ما قبل if فيعطي الزران العمر الصحيح.

القاعدتان في الكود

function Profile({ user }) {
    // Good: always called, always in this order
    const [tab, setTab] = useState('posts');
    const theme = useContext(ThemeContext);
    useEffect(() => {
        document.title = user.name;
    }, [user.name]);

    // Bad: inside a condition, a loop or a nested function
    if (user.isAdmin) {
        const [log, setLog] = useState([]); // breaks the order
    }
}

استدعاء الخطاف الذي يُبلغ دائمًا، وبالترتيب نفسه، لا بأس به أينما كان في الجسم، ما دام يأتي قبل أي return مبكر.

إصلاح خطاف يُستدعى بشرط

تبلّغ أداة الفحص عن هذا بالرسالة React Hook "useEffect" is called conditionally. React Hooks must be called in the exact same order in every component render. والإصلاح هو نفسه دائمًا: استدعِ الخطاف في كل مرة، وضع الشرط داخله.

// Broken: the effect exists on some renders and not others
function Notifications({ user }) {
    if (user) {
        useEffect(() => {
            console.log('subscribe for', user.name);
        }, [user]);
    }
    return null;
}

import { useState, useEffect } from 'react';

function Notifications({ user }) {
    useEffect(() => {
        if (!user) return;
        console.log('subscribe for', user.name);
        return () => console.log('unsubscribe for', user.name);
    }, [user]);

    return <p>{user ? `Notifications for ${user.name}` : 'Log in to see notifications'}</p>;
}

export default function App() {
    const [user, setUser] = useState(null);
    return (
        <div>
            <button onClick={() => setUser(user ? null : { name: 'Ada' })}>
                {user ? 'Log out' : 'Log in'}
            </button>
            <Notifications user={user} />
        </div>
    );
}

يُعلن التأثير في كل عرض، والشرط if بداخله يقرر ما إذا كان سيفعل شيئًا. سجّل الدخول والخروج بضع مرات فتُظهر Console اشتراكًا مع كل دخول وإلغاء اشتراك مع كل خروج.

الخطافات بعد إرجاع مبكر

الإرجاع المبكر return شرط أيضًا. ينتج هذا الرسالة "Rendered more hooks than during the previous render" في أول مرة تصبح فيها loading قيمتها false، لأن ذلك العرض يبلغ خطافًا لم يستدعه العرض السابق أبدًا. وعندما يستدعي عرضٌ خطافات أقل من السابق، تكون الرسالة "Rendered fewer hooks than expected".

// Broken: useState is skipped while loading
function Comments({ loading, comments }) {
    if (loading) return <p>Loading...</p>;
    const [expanded, setExpanded] = useState(false);
    return <List items={comments} expanded={expanded} />;
}

import { useState } from 'react';

function Comments({ loading, comments }) {
    const [expanded, setExpanded] = useState(false);

    if (loading) return <p>Loading...</p>;

    const shown = expanded ? comments : comments.slice(0, 2);
    return (
        <div>
            <ul>
                {shown.map((c) => (
                    <li key={c}>{c}</li>
                ))}
            </ul>
            <button onClick={() => setExpanded(!expanded)}>
                {expanded ? 'Show less' : `Show all ${comments.length}`}
            </button>
        </div>
    );
}

export default function App() {
    const [loading, setLoading] = useState(true);
    return (
        <div>
            <button onClick={() => setLoading(!loading)}>Toggle loading</button>
            <Comments loading={loading} comments={['Nice!', 'Agreed.', 'First.', 'Thanks']} />
        </div>
    );
}

كل خطاف يقع قبل return، فيستدعي الفرعان الخطافات نفسها. انقر "Toggle loading"، ووسّع القائمة، ثم بدّل التحميل مرتين: تتذكر القائمة أنها كانت موسّعة، لأن الحالة لم تُتخطَّ أبدًا.

الخطافات في حلقة

لا يمكنك استدعاء useState مرة لكل عنصر في حلقة، لأن عدد العناصر يتغير. أعطِ كل عنصر مكوّنه الخاص واستدعِ الخطاف هناك؛ ولكل نسخة خاناتها الخاصة.

import { useState } from 'react';

function Item({ name }) {
    const [qty, setQty] = useState(0);
    return (
        <li>
            {name}: {qty} <button onClick={() => setQty(qty + 1)}>+</button>
        </li>
    );
}

export default function App() {
    const [items, setItems] = useState(['Tea', 'Milk']);
    return (
        <div>
            <ul>
                {items.map((name) => (
                    <Item key={name} name={name} />
                ))}
            </ul>
            <button onClick={() => setItems([...items, `Item ${items.length + 1}`])}>
                Add item
            </button>
        </div>
    );
}

الرسالة "Invalid hook call"

تبدأ الرسالة بـ "Invalid hook call. Hooks can only be called inside of the body of a function component." ولها ثلاثة أسباب معتادة:

1. يعمل الخطاف بينما لا تعرض React مكوّن دالة. في معالج حدث، أو داخل دالة تأثير، أو في مكوّن صنف، أو على مستوى الوحدة. انقله إلى جسم المكوّن أو إلى خطاف مخصص، واستدعِ الخطاف المخصص من المكوّن.
2. إصدارا react وreact-dom غير متطابقين. ثبّت الإصدار نفسه من الاثنين.
3. توجد نسختان من React. حزمة محلية مربوطة أو مكتبة تجمع React الخاصة بها تجلب نسخة ثانية، والخطافات من نسخة لا تعمل مع مُصيِّر النسخة الأخرى. شغّل npm ls react وتأكد أن إصدارًا واحدًا فقط يظهر.

npm ls react

تعمل المعاينة هنا مثل بناء الإنتاج الذي لا يطبع هذه الرسائل: الخطاف المستدعى من معالج حدث يفشل بخطأ TypeError عادي مثل "Cannot read properties of null"، وتصل أخطاء React نفسها كرموز قصيرة "Minified React error". شغّل تطبيقك في وضع التطوير لتقرأ النص الكامل.

دع أداة الفحص تفرضها

تفحص eslint-plugin-react-hooks القاعدتين أثناء الكتابة، وتفحص أيضًا مصفوفات اعتماديات التأثيرات. يتضمنها قالب React في Vite وإعداد ESLint في Next.js. وفي إعداد ESLint المسطح، فعّل إعدادها الموصى به:

// eslint.config.js
import reactHooks from 'eslint-plugin-react-hooks';
import { defineConfig } from 'eslint/config';

export default defineConfig([reactHooks.configs.flat.recommended]);

القاعدتان الأساسيتان هما react-hooks/rules-of-hooks (خطأ) وreact-hooks/exhaustive-deps (تحذير). ومنذ الإصدار 7 يفعّل الإعداد أيضًا قواعد آتية من React Compiler، مثل react-hooks/purity وreact-hooks/refs، اللتين تنبهان إلى العرض غير النقي وقراءة المراجع أثناء العرض. ولاختيار القواعد واحدة واحدة، سجّل الإضافة على شكل plugins: { 'react-hooks': reactHooks } واسرد القواعد التي تريدها.

تجد الإضافة الخطافات بأسمائها: أي دالة يبدأ اسمها بـ use يليها حرف كبير تُعامل كخطاف، ولا يجوز أن تستدعيها إلا المكوّنات (أسماء بحرف كبير) ودوال use الأخرى. ولهذا يجب أن تستخدم الخطافات المخصصة البادئة.

الاستثناء: use

الخطاف use، الذي أُضيف في React 19، يقرأ وعدًا أو سياقًا، وخلافًا لكل خطاف آخر يجوز استدعاؤه داخل شرط أو حلقة. لكن ما زال يجب استدعاؤه أثناء العرض، داخل مكوّن أو خطاف.

import { createContext, use, useState } from 'react';

const ThemeContext = createContext('light');

function Heading({ children, themed }) {
    let color = '#000';
    if (themed) {
        const theme = use(ThemeContext);
        color = theme === 'dark' ? '#7aa7ff' : '#c0392b';
    }
    return <h3 style={{ color }}>{children}</h3>;
}

export default function App() {
    const [theme, setTheme] = useState('light');
    return (
        <ThemeContext value={theme}>
            <button onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}>
                Theme: {theme}
            </button>
            <Heading>Plain heading</Heading>
            <Heading themed>Themed heading</Heading>
        </ThemeContext>
    );
}

لا يتغير لون إلا العنوان ذي السمة عندما تبدّل السمة. جرّب الشيء نفسه مع useContext داخل if فتنبّه إليه أداة الفحص. تتناول صفحة الخطاف use قراءة الوعود به.