Zasady hooków w React: dlaczego kolejność ma znaczenie

Zasady hooków są dwie: wywołuj hooki tylko na najwyższym poziomie komponentu, nigdy w warunku, pętli, zagnieżdżonej funkcji ani po wczesnym return; i wywołuj je tylko z komponentów funkcyjnych albo z własnych hooków. Istnieją, bo React odróżnia hooki po kolejności, w jakiej je wywołujesz, więc ta kolejność musi być taka sama przy każdym renderowaniu.

React przechowuje wartości hooków komponentu na liście przypisanej do tego komponentu. Przy każdym renderowaniu przechodzi po tej liście: pierwsze wywołanie hooka dostaje pierwsze miejsce, drugie wywołanie drugie miejsce i tak dalej. Nie ma nazw, są tylko pozycje. Przykład poniżej to zabawkowa wersja tego pomysłu w kilku liniach zwykłego JavaScriptu, a nie własny kod Reacta, więc możesz go bezpiecznie psuć.

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>
    );
}

Pierwsze renderowanie wypełnia trzy miejsca: Ada, Countess, 36. Kliknij "Render without nickname": wywołanie warunkowe zostaje pominięte, więc wywołanie age zajmuje miejsce 1 i odczytuje Countess. Prawdziwy React w niektórych przypadkach zauważa niezgodność i rzuca błąd, a w innych oddaje złą wartość złemu hookowi, co jest gorsze. Przenieś wywołanie toyUseState('Countess') nad if, a oba przyciski pokażą właściwy wiek.

Dwie zasady w kodzie

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
    }
}

Wywołanie hooka, do którego zawsze dochodzi, w tej samej kolejności, jest w porządku bez względu na to, gdzie stoi w ciele komponentu, pod warunkiem że jest przed każdym wczesnym return.

Naprawa hooka wywołanego warunkowo

Linter zgłasza to jako React Hook "useEffect" is called conditionally. React Hooks must be called in the exact same order in every component render. Rozwiązanie jest zawsze takie samo: wywołuj hook za każdym razem, a warunek umieść w jego środku.

// 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>
    );
}

Efekt jest deklarowany przy każdym renderowaniu, a if w jego środku decyduje, czy cokolwiek zrobić. Zaloguj się i wyloguj kilka razy, a konsola pokaże subskrypcję przy każdym logowaniu i rezygnację z subskrypcji przy każdym wylogowaniu.

Hooki po wczesnym return

Wczesny return to też warunek. Ten kod daje "Rendered more hooks than during the previous render" za pierwszym razem, gdy loading zmieni się na false, bo to renderowanie dochodzi do hooka, którego poprzednie nigdy nie wywołało. Gdy renderowanie wywołuje mniej hooków niż poprzednie, komunikat brzmi "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>
    );
}

Każdy hook stoi nad return, więc obie gałęzie wywołują te same hooki. Kliknij "Toggle loading", rozwiń listę, a potem dwa razy przełącz ładowanie: lista pamięta, że była rozwinięta, bo stan nigdy nie został pominięty.

Hooki w pętli

Nie możesz wywołać useState raz na każdy element w pętli, bo liczba elementów się zmienia. Daj każdemu elementowi własny komponent i tam wywołaj hook; każda instancja ma własne miejsca.

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"

Komunikat zaczyna się od "Invalid hook call. Hooks can only be called inside of the body of a function component." Ma trzy typowe przyczyny:

1. Hook wykonuje się, gdy React nie renderuje komponentu funkcyjnego. W handlerze zdarzenia, wewnątrz callbacku efektu, w komponencie klasowym albo na poziomie modułu. Przenieś go do ciała komponentu albo własnego hooka i wywołaj własny hook z komponentu.
2. Wersje react i react-dom się nie zgadzają. Zainstaluj tę samą wersję obu.
3. Są dwie kopie Reacta. Podlinkowany lokalny pakiet albo biblioteka, która dołącza własnego Reacta, wnosi drugą kopię, a hooki z jednej kopii nie działają z rendererem drugiej. Uruchom npm ls react i upewnij się, że pojawia się tylko jedna wersja.

npm ls react

Podgląd tutaj działa jak build produkcyjny, który nie wypisuje tych komunikatów: hook wywołany z handlera zdarzenia kończy się zwykłym TypeError, na przykład "Cannot read properties of null", a własne błędy Reacta przychodzą jako krótkie kody "Minified React error". Uruchom aplikację w trybie deweloperskim, żeby przeczytać pełny tekst.

Niech pilnuje tego linter

eslint-plugin-react-hooks sprawdza obie zasady w trakcie pisania, a do tego tablice zależności efektów. Zawierają go szablon React w Vite i konfiguracja ESLint w Next.js. W płaskiej konfiguracji ESLint włącz jego zalecany zestaw:

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

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

Dwie podstawowe reguły to react-hooks/rules-of-hooks (błąd) i react-hooks/exhaustive-deps (ostrzeżenie). Od wersji 7 zestaw włącza też reguły pochodzące z React Compiler, takie jak react-hooks/purity i react-hooks/refs, które zgłaszają nieczyste renderowanie i odczyt refów podczas renderowania. Żeby wybierać reguły pojedynczo, zarejestruj wtyczkę jako plugins: { 'react-hooks': reactHooks } i wymień reguły, których chcesz.

Wtyczka rozpoznaje hooki po nazwie: każda funkcja, której nazwa zaczyna się od use, a po nim wielkiej litery, jest traktowana jako hook i mogą ją wywoływać tylko komponenty (nazwy z wielkiej litery) i inne funkcje use. Dlatego własne hooki muszą używać tego przedrostka.

Wyjątek: use

use, dodany w React 19, odczytuje obietnicę albo kontekst i w odróżnieniu od każdego innego hooka może być wywołany w warunku albo pętli. Nadal musi być wywoływany podczas renderowania, wewnątrz komponentu albo hooka.

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>
    );
}

Gdy zmieniasz motyw, kolor zmienia tylko nagłówek z motywem. Spróbuj tego samego z useContext wewnątrz if, a linter to zgłosi. Strona o hooku use omawia odczytywanie nim obietnic.