useLayoutEffect في React: القياس قبل أن يرسم المتصفح

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

التأثيرات معلنة بترتيب: التأثير، ثم تأثير التخطيط، لكن وحدة التحكم تطبع تأثير التخطيط أولًا في كل عرض. ترتيب الإعلان لا يهم بين الخطافين؛ بل توقيتهما.

الصيغة

التوقيع مطابق لـ useEffect: دالة إعداد، ودالة تنظيف اختيارية، ومصفوفة اعتماديات.

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

كل ما تعرفه عن الاعتماديات والتنظيف من useEffect ينطبق. الفرق الوحيد هو متى تستدعيه React.

متى يعمل كل منهما

بعد العرض، تحدّث React الـ DOM ثم تفعل ثلاثة أشياء بترتيب ثابت:

1. تشغّل كل دوال تنظيف تأثيرات التخطيط وتأثيرات التخطيط، بشكل متزامن.
2. تترك المتصفح يرسم. وإذا ضبط تأثير تخطيط حالة، تعيد React العرض أولًا، وما زال ذلك قبل الرسم.
3. تشغّل التأثيرات العادية، عادة بعد الرسم.

عبر الشجرة، يعمل كل تأثير تخطيط قبل أي تأثير عادي، ويعمل الأبناء قبل آبائهم، لأن الأب لا يمكنه الانتهاء إلا بعد أن يكون أبناؤه في مكانهم:

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

تُظهر وحدة التحكم تأثيري التخطيط أولًا، Child ثم Parent، ثم التأثيرين العاديين بالترتيب نفسه. يجعل key={n} كل نقرة تركّب Parent جديدًا، فتحصل على الأسطر الأربعة نفسها في كل مرة. أضف إلى كل تأثير دالة تنظيف تسجّل، وراقب القديمة تعمل قبل الجديدة.

مشكلة الوميض

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

1. اعرض التلميح في مكان ما، ليمكن قياسه.
2. قِسه، واحسب الموضع الحقيقي، واضبط الحالة، وأعد العرض.

مع 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 ومرّر المؤشر مرة أخرى: قد يومض التلميح الآن في أعلى الصندوق لإطار واحد قبل أن يتحرك. على جهاز سريع يكون ذلك غالبًا أسرع من أن يُلاحظ، وهذا بالضبط سبب أن هذا الخطأ يُنشر ثم يُبلَّغ عنه من هواتف أبطأ.

كل من offsetHeight وoffsetTop وgetBoundingClientRect() يجبر المتصفح على حساب التخطيط، فقراءتها في تأثير التخطيط تعطيك القيم الحقيقية للـ DOM الذي كتبته React للتو.

قياس عنصر

يعمل النمط نفسه لأي حجم يعتمد عليه العرض: اقرأه بمرجع في تأثير تخطيط، وخزّنه في الحالة، واعرض به.

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

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

• يقرأ التأثير التخطيط (الحجم، أو الموضع، أو التمرير).
• يغيّر ما يُعرض بناءً على تلك القراءة.
• ستكون الحالة الوسيطة مرئية وتبدو خاطئة.

كل ما عدا ذلك (الجلب، والاشتراكات، والمؤقتات، والتسجيل، والتحليلات) ينتمي إلى useEffect. قاعدة سريعة: ابدأ بـ useEffect، ولا تنتقل إلا إذا رأيت وميضًا.

يعمل useEffect عادة بعد الرسم، لكن ليس دائمًا. عندما يأتي التحديث من فعل مستخدم منفصل مثل نقرة أو ضغطة مفتاح، قد تشغّل React التأثيرات قبل أن يرسم المتصفح. وهذا أحد أسباب ظهور الوميض في موقف دون آخر.

العرض على الخادم

لا تعمل التأثيرات أبدًا أثناء العرض على الخادم، ولا useLayoutEffect كذلك. يرسل الخادم HTML العرض الأول، ولا يعمل تأثير التخطيط إلا بعد الإماهة (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

هناك خطاف تأثير ثالث، useInsertionEffect، يعمل قبل أي تأثير تخطيط. وهو موجود لمكتبات CSS-in-JS التي تولّد وسوم <style> وقت التشغيل: إدراج الأنماط هناك يعني أن تأثير التخطيط الذي يقيس عنصرًا يراه منسقًا بالفعل. لا يستطيع تحديث الحالة ولم تُربط المراجع بعد، لذا لا فائدة منه في كود التطبيقات. إن لم تكن تكتب مكتبة تنسيق، فلن تحتاج إليه.