React useLayoutEffect: pomiar przed odmalowaniem ekranu

useLayoutEffect to wersja useEffect, która uruchamia się wcześniej: zaraz po tym, jak React zaktualizował DOM, ale zanim przeglądarka odmaluje nową klatkę. Kod w nim może mierzyć elementy i zmieniać układ, a użytkownik widzi tylko końcowy wynik. Na czas działania blokuje odmalowanie, więc używaj go tylko wtedy, gdy potrzebujesz takiego momentu uruchomienia.

import { useState, useEffect, useLayoutEffect } from 'react';

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

    console.log('1. render');

    useEffect(() => {
        console.log('3. effect (usually after paint)');
    });

    useLayoutEffect(() => {
        console.log('2. layout effect (before paint)');
    });

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

Efekty są zadeklarowane w kolejności: efekt, efekt układu, ale konsola przy każdym renderowaniu wypisuje najpierw efekt układu. Kolejność deklaracji nie ma znaczenia między tymi dwoma hookami; liczy się ich moment uruchomienia.

Składnia

Sygnatura jest identyczna jak w useEffect: funkcja setup, opcjonalna funkcja czyszcząca i tablica zależności.

useLayoutEffect(() => {
    // runs after the DOM update, before paint
    return () => {
        // cleanup, before the next run and on unmount
    };
}, [dependencies]);

Wszystko, co wiesz o zależnościach i czyszczeniu z useEffect, obowiązuje tutaj. Jedyna różnica to moment, w którym React go wywołuje.

Kiedy uruchamia się każdy z nich

Po renderowaniu React aktualizuje DOM, a potem robi trzy rzeczy w stałej kolejności:

1. Synchronicznie uruchamia wszystkie funkcje czyszczące efektów układu i same efekty układu.
2. Pozwala przeglądarce odmalować ekran. Jeśli efekt układu ustawił stan, React najpierw renderuje ponownie, wciąż przed odmalowaniem.
3. Uruchamia zwykłe efekty, zwykle po odmalowaniu.

W całym drzewie każdy efekt układu uruchamia się przed jakimkolwiek zwykłym efektem, a dzieci przed rodzicami, bo rodzic może skończyć dopiero wtedy, gdy jego dzieci są na miejscu:

import { useEffect, useLayoutEffect, useState } from 'react';

function Child() {
    useLayoutEffect(() => {
        console.log('Child layout effect');
    });
    useEffect(() => {
        console.log('Child effect');
    });
    return <p>Child</p>;
}

function Parent() {
    useLayoutEffect(() => {
        console.log('Parent layout effect');
    });
    useEffect(() => {
        console.log('Parent effect');
    });
    return <Child />;
}

export default function App() {
    const [n, setN] = useState(0);
    return (
        <div>
            <button onClick={() => setN(n + 1)}>Render again ({n})</button>
            <Parent key={n} />
        </div>
    );
}

Konsola pokazuje najpierw oba efekty układu, Child, potem Parent, a potem oba zwykłe efekty w tej samej kolejności. key={n} sprawia, że każde kliknięcie montuje świeży Parent, więc za każdym razem dostajesz te same cztery linie. Dodaj do każdego efektu funkcję czyszczącą, która wypisuje log, i zobacz, jak stare uruchamiają się przed nowymi.

Problem migotania

Wyobraź sobie tooltip, który powinien pojawić się nad przyciskiem, chyba że nad nim nie ma miejsca, a wtedy idzie pod spód. Nie wiesz, czy jest miejsce, dopóki tooltip nie znajdzie się w DOM i nie zmierzysz jego wysokości. Renderowanie odbywa się więc w dwóch przebiegach:

1. Wyrenderuj tooltip gdziekolwiek, żeby dało się go zmierzyć.
2. Zmierz go, wylicz prawdziwą pozycję, ustaw stan, wyrenderuj ponownie.

Z useEffect przeglądarka może odmalować ekran między tymi przebiegami, a użytkownik zobaczy, jak tooltip przeskakuje z pierwszej pozycji do drugiej. Z useLayoutEffect drugi przebieg następuje przed odmalowaniem, więc pierwsza pozycja nigdy nie jest pokazana.

import { useLayoutEffect, useRef, useState } from 'react';

function Tooltip({ anchor, text }) {
    const ref = useRef(null);
    const [top, setTop] = useState(0);

    useLayoutEffect(() => {
        const height = ref.current.offsetHeight;
        const above = anchor.offsetTop - height - 6;
        const fits = above >= 0;
        console.log(fits ? 'room above: placing above' : 'no room above: placing below');
        setTop(fits ? above : anchor.offsetTop + anchor.offsetHeight + 6);
    }, [anchor]);

    const style = {
        position: 'absolute', top, left: anchor.offsetLeft,
        background: '#222', color: '#fff', padding: '4px 8px', borderRadius: 4, fontSize: 13,
    };
    return <div ref={ref} style={style}>{text}</div>;
}

export default function App() {
    const [anchor, setAnchor] = useState(null);
    const show = (e) => setAnchor(e.currentTarget);
    const hide = () => setAnchor(null);

    return (
        <div style={{ position: 'relative', height: 160 }}>
            <button onMouseEnter={show} onMouseLeave={hide} style={{ position: 'absolute', top: 0 }}>
                Hover me (top)
            </button>
            <button onMouseEnter={show} onMouseLeave={hide} style={{ position: 'absolute', top: 110 }}>
                Hover me (lower)
            </button>
            {anchor && <Tooltip anchor={anchor} text="A tooltip that picks its side" />}
        </div>
    );
}

Najedź na górny przycisk: nad nim nie ma miejsca, więc tooltip pojawia się pod spodem. Najedź na dolny, a pojawi się nad nim. Konsola mówi, którą stronę wybrał pomiar. Zmień useLayoutEffect na useEffect i najedź ponownie: tooltip może teraz mignąć na górze ramki przez jedną klatkę, zanim się przesunie. Na szybkim komputerze często dzieje się to zbyt szybko, żeby to zauważyć, i właśnie dlatego ten błąd trafia na produkcję, a potem jest zgłaszany z wolniejszych telefonów.

offsetHeight, offsetTop i getBoundingClientRect() zmuszają przeglądarkę do przeliczenia układu, więc odczyt w efekcie układu daje prawdziwe wartości DOM, który React właśnie zapisał.

Mierzenie elementu

Ten sam wzorzec działa dla każdego rozmiaru, od którego zależy renderowanie: odczytaj go przez ref w efekcie układu, zapisz w stanie, renderuj z nim.

import { useLayoutEffect, useRef, useState } from 'react';

export default function App() {
    const [text, setText] = useState('Short');
    const [width, setWidth] = useState(null);
    const boxRef = useRef(null);

    useLayoutEffect(() => {
        const w = Math.round(boxRef.current.getBoundingClientRect().width);
        console.log('measured width for', JSON.stringify(text));
        setWidth(w);
    }, [text]);

    return (
        <div>
            <button onClick={() => setText(text + ' and longer')}>Make it longer</button>
            <p>
                <span ref={boxRef} style={{ background: '#ffeaa7', padding: '2px 6px' }}>
                    {text}
                </span>
            </p>
            <p>The highlighted text is {width} px wide.</p>
        </div>
    );
}

Kliknij przycisk, a linia z szerokością zaktualizuje się w tej samej klatce co tekst. Strona nigdy nie pokazuje nowego tekstu obok starej szerokości, bo drugie renderowanie następuje przed odmalowaniem. Usuń [text] z tablicy zależności, a pomiar będzie się wykonywał po każdym renderowaniu, także po tym, które wywołuje jego własne setWidth; zatrzymuje się tylko dlatego, że szerokość przestaje się zmieniać.

Wybieraj useEffect

Efekt układu wstrzymuje odmalowanie, dopóki nie wróci, a jeśli ustawia stan, także dopóki nie skończy się dodatkowe renderowanie. Wolny efekt sprawia, że każda aktualizacja na stronie wydaje się wolna. Używaj useLayoutEffect tylko wtedy, gdy wszystkie te warunki są spełnione:

• Efekt odczytuje układ (rozmiar, pozycję, przewinięcie).
• Na podstawie tego odczytu zmienia to, co jest renderowane.
• Stan pośredni byłby widoczny i wyglądałby źle.

Wszystko inne (pobieranie danych, subskrypcje, timery, logowanie, analityka) należy do useEffect. Prosta zasada: zacznij od useEffect i zmień go tylko wtedy, gdy widzisz migotanie.

useEffect zwykle uruchamia się po odmalowaniu, ale nie zawsze. Gdy aktualizacja pochodzi z dyskretnej akcji użytkownika, takiej jak kliknięcie albo naciśnięcie klawisza, React może uruchomić efekty, zanim przeglądarka odmaluje ekran. To jeden z powodów, dla których migotanie może pojawić się w jednej sytuacji, a w innej nie.

Renderowanie na serwerze

Efekty nigdy nie uruchamiają się podczas renderowania na serwerze, useLayoutEffect też nie. Serwer wysyła HTML pierwszego renderowania, a efekt układu uruchamia się dopiero po hydracji w przeglądarce. React 18 i wcześniejsze ostrzegały "useLayoutEffect does nothing on the server", gdy taki komponent był renderowany na serwerze; React 19 usunął to ostrzeżenie.

Jeśli pierwsza klatka wyrenderowana na serwerze bez pomiaru wyglądałaby źle, są dwa popularne rozwiązania: wyrenderuj neutralny widok zastępczy (na przykład ukryj tooltip, dopóki nie zostanie zmierzony) albo renderuj komponent tylko po stronie klienta:

function ClientOnly({ children }) {
    const [mounted, setMounted] = useState(false);
    useEffect(() => setMounted(true), []);
    return mounted ? children : null;
}

useInsertionEffect

Jest też trzeci hook efektu, useInsertionEffect, który uruchamia się przed każdym efektem układu. Istnieje dla bibliotek CSS-in-JS, które generują tagi <style> w czasie działania: wstawienie stylów w tym momencie sprawia, że efekt układu, który mierzy element, widzi go już ostylowanego. Nie może aktualizować stanu, a refy nie są jeszcze podłączone, więc w kodzie aplikacji jest bezużyteczny. Jeśli nie piszesz biblioteki do stylowania, nie będziesz go potrzebować.