React useLayoutEffect 教程：在浏览器绘制前测量

useLayoutEffect 是 useEffect 的一个版本，只是运行得更早：在 React 更新 DOM 之后、浏览器绘制新的一帧之前立即运行。其中的代码可以测量元素并修改布局，而用户只会看到最终结果。它运行时会阻塞绘制，所以只在确实需要这个时机时才用它。

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

两个 Effect 的声明顺序是先 effect 后 layout effect，但每次渲染时控制台都先输出 layout effect。这两个 Hook 之间，声明顺序无关紧要，起决定作用的是它们的时机。

语法

它的签名与 useEffect 完全相同：一个 setup 函数，一个可选的清理函数，以及一个依赖数组。

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

你在 useEffect 中学到的关于依赖和清理函数的一切，在这里都适用。唯一的区别是 React 调用它的时机。

两者各自何时运行

一次渲染之后，React 更新 DOM，然后按固定顺序做三件事：

1. 同步运行所有 layout effect 的清理函数和 layout effect。
2. 让浏览器绘制。如果某个 layout effect 设置了 state，React 会先重新渲染，这仍然发生在绘制之前。
3. 运行普通 Effect，通常在绘制之后。

在整棵树中，所有 layout effect 都在任何普通 Effect 之前运行，而且子组件先于父组件运行，因为父组件只有在子组件就位后才算完成：

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

控制台先显示两个 layout effect，先 Child 后 Parent，然后按同样的顺序显示两个普通 Effect。key={n} 让每次点击都挂载一个全新的 Parent，所以你每次都会看到同样的四行。给每个 Effect 加一个输出日志的清理函数，观察旧的清理函数在新的 Effect 之前运行。

闪烁问题

设想一个提示框，它应该显示在按钮上方，除非上方没有空间，那时就放到下方。在提示框进入 DOM、你能测量它的高度之前，你无法知道上方有没有空间。所以渲染要分两遍进行：

1. 先把提示框渲染在某个地方，以便测量。
2. 测量它，算出真正的位置，设置 state，再渲染一次。

用 useEffect 时，浏览器可能在这两遍之间进行绘制，用户会看到提示框从第一个位置跳到第二个位置。用 useLayoutEffect 时，第二遍发生在绘制之前，所以第一个位置永远不会被显示出来。

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

把鼠标悬停在上面的按钮上：它上方没有空间，所以提示框出现在下方。悬停在下面那个按钮上，提示框就出现在上方。控制台会告诉你测量结果选择了哪一侧。把 useLayoutEffect 改成 useEffect 再悬停一次：提示框现在可能会在盒子顶部闪现一帧，然后才移动过去。在速度快的电脑上，这往往快到察觉不到，而这正是这类 bug 被发布上线、然后从速度较慢的手机上被用户报告回来的原因。

offsetHeight、offsetTop 和 getBoundingClientRect() 都会强制浏览器计算布局，所以在 layout effect 中读取它们，得到的是 React 刚刚写入的 DOM 的真实值。

测量元素

同样的写法适用于渲染依赖的任何尺寸：在 layout effect 中通过 ref 读取它，存进 state，再用它来渲染。

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

点击按钮，宽度那一行与文字在同一帧更新。页面永远不会出现新文字配旧宽度的情况，因为第二次渲染发生在绘制之前。把 [text] 从依赖数组中去掉，测量就会在每次渲染后运行，包括由它自己的 setWidth 引起的那次；它之所以会停下来，只是因为宽度不再变化了。

优先使用 useEffect

layout effect 会推迟绘制，直到它返回；如果它设置了 state，还要等额外的那次渲染完成。一个慢的 layout effect 会让页面上的每次更新都显得卡顿。只有在以下条件全部满足时，才使用 useLayoutEffect：

• Effect 会读取布局信息（尺寸、位置、滚动）。
• 它根据读取结果改变渲染内容。
• 中间状态会被看到，而且看起来是错的。

其他所有情况（数据请求、订阅、定时器、日志、统计分析）都应该放在 useEffect 中。一个简单的原则：先用 useEffect，只有当你看到闪烁时才换掉它。

useEffect 通常在绘制之后运行，但并不总是如此。当更新来自点击或按键这类离散的用户操作时，React 可能会在浏览器绘制之前运行 Effect。这也是闪烁有时出现、有时不出现的原因之一。

服务端渲染

服务端渲染期间 Effect 从不运行，useLayoutEffect 也一样。服务器发送第一次渲染的 HTML，layout effect 只在浏览器中 hydration 完成之后才运行。React 18 及更早版本在服务器上渲染这种组件时，会警告 "useLayoutEffect does nothing on the server"；React 19 去掉了这条警告。

如果没有测量结果，服务端渲染出的第一帧看起来就会不对，常见的修复方法有两种：先渲染一个中性的占位内容（例如在测量完成之前隐藏提示框），或者只在客户端渲染这个组件：

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

useInsertionEffect

还有第三个 Effect Hook，useInsertionEffect，它在所有 layout effect 之前运行。它是为在运行时生成 <style> 标签的 CSS-in-JS 库准备的：在这里插入样式，意味着测量元素的 layout effect 看到的已经是加好样式的元素。它不能更新 state，ref 此时也还没有绑定，所以在应用代码中没有用处。如果你不是在写样式库，就不会用到它。