useDeferredValue في React: دع الأجزاء البطيئة تتأخر

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

import { memo, useDeferredValue, useState } from 'react';

function SlowItem({ text }) {
    const start = performance.now();
    while (performance.now() - start < 1) {
        // each row takes 1 ms to render
    }
    return <li>{text}</li>;
}

const SlowList = memo(function SlowList({ query }) {
    console.log('SlowList rendering for', JSON.stringify(query));
    const rows = [];
    for (let i = 0; i < 250; i++) {
        rows.push(<SlowItem key={i} text={`${query || 'result'} #${i + 1}`} />);
    }
    return <ul style={{ maxHeight: 150, overflow: 'auto' }}>{rows}</ul>;
});

export default function App() {
    const [query, setQuery] = useState('');
    const deferredQuery = useDeferredValue(query);
    const isStale = query !== deferredQuery;

    return (
        <div>
            <input
                value={query}
                onChange={(e) => setQuery(e.target.value)}
                placeholder="Type fast"
            />
            <div style={{ opacity: isStale ? 0.5 : 1 }}>
                <SlowList query={deferredQuery} />
            </div>
        </div>
    );
}

اكتب كلمة بسرعة. يواكبك الحقل وتبهت القائمة ما دامت متأخرة. تسجّل Console سطر SlowList rendering واحدًا لكل حرف، لأن SlowList يسجّل بمجرد أن تبدأ React عرضه، لكن قوائم القيم الوسيطة لا تصل إلى الشاشة أبدًا: قاطع كل حرف جديد العرض الخلفي، وبدأت React من جديد بأحدث نص. غيّر query={deferredQuery} إلى query={query} واكتب مرة أخرى: تنتظر الآن كل ضغطة مفتاح ربع ثانية للقائمة.

الصيغة

const deferredValue = useDeferredValue(value);
const deferredValue = useDeferredValue(value, initialValue); // React 19

• value أي شيء تعرضه: نص من حقل، أو رقم، أو كائن. تعمل القيم البسيطة أفضل، لأن الكائن الجديد في كل عرض يُحسب دائمًا تغييرًا.
• القيمة المُرجعة تساوي value معظم الوقت. وبعد أن تتغير value مباشرة، تظل تحمل القيمة السابقة لعرض واحد، ثم تلحق في عرض خلفي.

كيف يعمل

كل تغيير ينتج عرضين:

1. عرض عاجل بالقيمة value الجديدة وdeferredValue القديمة. يُظهر الحقل النص الجديد. والمكوّنات التي لا تستقبل إلا deferredValue تحصل على props نفسها كما من قبل.
2. عرض خلفي بالقيمة deferredValue الجديدة. هذا هو البطيء. تعرضه React على شرائح وتتخلى عنه إذا تغيرت value من جديد قبل أن ينتهي، ثم تبدأ من جديد بأحدث قيمة.

يمكنك مراقبة ذلك بتسجيل القيمتين:

import { useDeferredValue, useState } from 'react';

export default function App() {
    const [text, setText] = useState('');
    const deferredText = useDeferredValue(text);

    console.log('render: text =', JSON.stringify(text), 'deferred =', JSON.stringify(deferredText));

    return (
        <input
            value={text}
            onChange={(e) => setText(e.target.value)}
            placeholder="Type one letter"
        />
    );
}

اكتب حرفًا واحدًا، a مثلًا، فتطبع Console سطرين إضافيين: أولًا text = "a" مع deferred = ""، ثم كلاهما "a". ذلك العرض الأول هو ما يُبقي الكتابة سريعة، لكن فقط إذا استطاع الجزء البطيء تخطيه. ولهذا يكون SlowList في المثال الأول ملفوفًا بـ memo: أثناء العرض العاجل لم تتغير الـ prop المسماة query، فتتخطاه React. من دون memo سيظل العرض العاجل يشغّل القائمة البطيئة كلها، فقط بالنص القديم، ولن تكسب شيئًا.

عرض محتوى قديم

أثناء تقدم العرض الخلفي تختلف value والقيمة المؤجلة. قارن بينهما لتخبر المستخدم بأن المحتوى قديم، دون إخفائه:

const isStale = query !== deferredQuery;

<div style={{ opacity: isStale ? 0.5 : 1, transition: 'opacity 0.2s' }}>
    <SlowList query={deferredQuery} />
</div>

هذا عادة أجمل من مؤشر دوار: تبقى النتائج القديمة قابلة للقراءة وتتغير في مكانها عندما تجهز الجديدة. وتعمل الفكرة نفسها مع Suspense: إذا جعلت القيمة المؤجلة مكوّنًا يُعلَّق أثناء تحميل البيانات، تظل React تعرض المحتوى القديم بدلًا من البديل حتى يجهز المحتوى الجديد (راجع Suspense وlazy).

القيمة الابتدائية (React 19)

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

import { memo, useDeferredValue } from 'react';

const Preview = memo(function Preview({ text }) {
    console.log('Preview render:', JSON.stringify(text));
    if (!text) return <p>Loading preview...</p>;
    return <p>{text}</p>;
});

export default function App() {
    const article = 'React renders the cheap version first, then this one.';
    const deferred = useDeferredValue(article, '');
    return <Preview text={deferred} />;
}

تُظهر Console عرضين: الأول بـ ""، ثم بالنص الكامل. احذف الوسيط الثاني فلا يُسجَّل إلا عرض واحد، بالنص الكامل مباشرة.

useDeferredValue مقابل useTransition

كلاهما يعلّم العمل كغير عاجل ويستخدم آلية العرض نفسها. الفرق هو أين تضعهما:

• useTransition يغلّف التحديث. تستدعي startTransition(() => setQuery(text))، فتحتاج إلى دالة الضبط. وتحصل على isPending مجانًا.
• useDeferredValue يغلّف القيمة. تستدعيه حيث تُستخدم القيمة، فيعمل عندما تصل القيمة كـ prop أو تأتي من خطاف لا تتحكم فيه. وتحسب «الانتظار» بنفسك بـ value !== deferredValue.

// You own the state: either works, a transition is direct
startTransition(() => setQuery(nextQuery));

// You only receive the value
function SearchResults({ query }) {
    const deferredQuery = useDeferredValue(query);
    return <SlowList query={deferredQuery} />;
}

useDeferredValue مقابل التأخير والتقييد

التأخير (debounce) ينتظر مدة ثابتة بعد آخر تغيير؛ والتقييد (throttle) يحدّث مرة واحدة على الأكثر في كل فترة. كلاهما يختار مهلة مسبقًا، فيجعلان الصفحة على حاسوب محمول سريع أبطأ مما يلزم، وقد تكون المهلة على هاتف بطيء ما زالت قصيرة جدًا.

ليس لـ useDeferredValue أي مهلة. يبدأ العرض الخلفي فورًا، فتتحدث القائمة على جهاز سريع على الفور تقريبًا، وعلى جهاز بطيء تُبقي React الحقل سريع الاستجابة وتعرض القائمة بقدر ما تستطيع. والعمل الخلفي قابل للمقاطعة أيضًا، وهو ما لا يكونه العرض المؤخَّر: بمجرد أن يبدأ عرض مؤخَّر، يحجب حتى ينتهي.

وما لا يفعله هو تقليل طلبات الشبكة. إذا بدأت كل قيمة جديدة طلبًا، فما زالت القيمة المؤجلة تتغير مع كل عرض يكتمل، لذا أخّر الطلب نفسه عندما يهم عدد الطلبات.

أخطاء شائعة

• نسيان memo. كما يظهر أعلاه، يجب أن يتمكن المكوّن البطيء من تخطي العرض العاجل. إذا لم يكن ملفوفًا بـ memo، أو كانت إحدى props الأخرى كائنًا جديدًا في كل عرض، فإنه يُعرض مرتين لكل ضغطة مفتاح بدلًا من مرة.
• تمرير كائن جديد. ينشئ useDeferredValue({ query }) كائنًا جديدًا في كل عرض، فتبدو القيمة المؤجلة متغيرة دائمًا وتبدأ React عرضًا خلفيًا إضافيًا في كل مرة. أجّل القيمة البسيطة (useDeferredValue(query)) وابنِ الكائنات منها.
• توقع طلبات أقل. المكوّن الذي يجلب البيانات بناءً على القيمة المؤجلة ما زال يجلب لكل قيمة ينتهي عرضها.

متى تلجأ إليه

استخدم useDeferredValue عندما يقود حقل واحد جزءًا من الصفحة بطيئًا في العرض، ويمكن حفظ الجزء البطيء، ولا مانع لديك من عرض نتائج أقدم قليلًا للحظة: نتائج البحث، أو رسم بياني يُعاد رسمه من مرشح، أو معاينة لنص منسق. وإذا كان الجزء البطيء بطيئًا لسبب يمكنك إصلاحه، مثل عرض 5,000 صف بينما يظهر 50، فأصلح ذلك أولًا. ولنسخة هذا النمط التي تملك فيها دالة الضبط، راجع useTransition.