الخطاف useOptimistic في React: واجهة فورية مع التراجع

useOptimistic خطاف في React 19 يتيح للشاشة عرض نتيجة إجراء قبل أن ينتهي. تضبط قيمة متفائلة داخل إجراء؛ فتعرضها React ما دام الإجراء معلقًا، ثم تعود إلى الحالة الحقيقية. وإذا فشل الطلب، فالحالة الحقيقية لم تتغير أبدًا، فتتراجع الشاشة من تلقاء نفسها.

الواجهة البرمجية الوهمية في هذا المثال بديل عن طلب حقيقي وتفشل في كل استدعاء ثالث، لترى النتيجتين.

import { startTransition, useOptimistic, useState } from 'react';

let calls = 0;
function saveLike(liked) {
    // Stands in for a real request. Every third call fails.
    calls += 1;
    const fails = calls % 3 === 0;
    return new Promise((resolve, reject) =>
        setTimeout(() => (fails ? reject(new Error('Network error')) : resolve(liked)), 1000),
    );
}

export default function App() {
    const [liked, setLiked] = useState(false);
    const [optimisticLiked, setOptimisticLiked] = useOptimistic(liked);
    const [error, setError] = useState('');

    function toggle() {
        const next = !optimisticLiked;
        setError('');
        startTransition(async () => {
            setOptimisticLiked(next);
            try {
                await saveLike(next);
                startTransition(() => setLiked(next));
            } catch (e) {
                setError(`${e.message}, so the change was undone.`);
            }
        });
    }

    return (
        <div>
            <button onClick={toggle}>{optimisticLiked ? 'Liked' : 'Like'}</button>
            <p style={{ color: '#666' }}>Saved on the server: {liked ? 'liked' : 'not liked'}</p>
            {error && <p style={{ color: 'crimson' }}>{error}</p>}
        </div>
    );
}

انقر الزر ثلاث مرات، مع انتظار ثانية بين النقرات. تتبدل الأوليان فورًا ويلحق سطر الحفظ بعد ثانية. والثالثة تتبدل فورًا أيضًا، ثم تنقلب عائدة عندما يفشل الطلب. غيّر calls % 3 إلى calls % 2 فتفشل كل نقرة ثانية.

الصيغة

const [optimisticState, setOptimistic] = useOptimistic(state, updateFn?);

• state هي القيمة الحقيقية، عادة من useState أو props أو useActionState. وعندما لا يكون أي إجراء معلقًا، تكون optimisticState هذه القيمة بالضبط.
• تضبط setOptimistic(value) القيمة المتفائلة ما دام الإجراء الحالي يعمل.
• updateFn اختيارية: (currentState, optimisticValue) => nextState. معها تستقبل setOptimistic تغييرًا بدلًا من قيمة جديدة كاملة. انظر شكل المختزل أدناه.

دورة حياة النقرة الواحدة هي نفسها دائمًا:

1. داخل إجراء، تستدعي setOptimistic. تتحدث الشاشة فورًا.
2. ينتظر الإجراء الطلب.
3. عند النجاح تحدّث الحالة الحقيقية (داخل startTransition عندما يأتي ذلك بعد await).
4. ينتهي الإجراء. تتبع optimisticState الحالة state من جديد: القيمة المحفوظة عند النجاح، والقيمة القديمة عند الفشل.

الخطوة 4 هي سبب عدم وجود كود تراجع في المثال. لا تضبط كتلة catch إلا رسالة خطأ.

يجب أن يعمل داخل إجراء

لا توجد القيمة المتفائلة إلا ما دام انتقال معلقًا، لذا يجب استدعاء setOptimistic داخل واحد. وكل هذه تُحسب:

• الدالة التي تمررها إلى startTransition (أو startTransition المأخوذة من useTransition)،
• دالة تُمرَّر إلى <form action={...}> أو <button formAction={...}>،
• الإجراء الذي تعطيه لـ useActionState.

إذا استُدعيت من onClick عادي، فليس للقيمة المتفائلة إجراء تعيش فيه. تعيدها React فورًا، وفي التطوير تسجّل React "An optimistic state update occurred outside a transition or action".

ينبغي تغليف تحديثات الحالة الحقيقية التي تحدث بعد await في startTransition خاصة بها، كما هو حال startTransition(() => setLiked(next)) أعلاه. لا تستطيع React أن تعرف، بعد await، أنك ما زلت داخل الانتقال السابق.

قائمة رسائل بشكل المختزل

عندما تكون الحالة المتفائلة قائمة، مرّر دالة تحديث كوسيط ثانٍ. عندها تستقبل دالة الضبط العنصر الجديد، وتُلحقه React بما تكون عليه القائمة الحقيقية في تلك اللحظة.

import { startTransition, useOptimistic, useState } from 'react';

let calls = 0;
function deliver(text) {
    // Stands in for a real request. Every third message fails.
    calls += 1;
    const id = calls;
    const fails = id % 3 === 0;
    return new Promise((resolve, reject) =>
        setTimeout(() => (fails ? reject(new Error('failed')) : resolve({ id, text })), 1200),
    );
}

export default function App() {
    const [messages, setMessages] = useState([{ id: 0, text: 'Hi there' }]);
    const [failed, setFailed] = useState([]);
    const [optimisticMessages, addOptimistic] = useOptimistic(messages, (current, text) => [
        ...current,
        { id: `pending-${text}`, text, sending: true },
    ]);

    async function send(formData) {
        const text = formData.get('text');
        addOptimistic(text);
        try {
            const saved = await deliver(text);
            startTransition(() => setMessages((list) => [...list, saved]));
        } catch {
            setFailed((list) => [...list, text]);
        }
    }

    return (
        <div>
            {optimisticMessages.map((m) => (
                <p key={m.id} style={{ margin: '4px 0', opacity: m.sending ? 0.5 : 1 }}>
                    {m.text} {m.sending && <small>(sending...)</small>}
                </p>
            ))}
            {failed.map((text, i) => (
                <p key={i} style={{ color: 'crimson', margin: '4px 0' }}>Not sent: {text}</p>
            ))}
            <form action={send}>
                <input name="text" defaultValue="Hello" />
                <button type="submit">Send</button>
            </form>
        </div>
    );
}

أرسل ثلاث رسائل بنصوص مختلفة، واحدة تلو الأخرى. تظهر كل منها باهتة مع "(sending...)" وتصبح واضحة بعد التسليم؛ وتختفي الثالثة من المحادثة وتظهر على أنها "Not sent". أرسلها بسرعة بدلًا من ذلك فتبقى الثلاث باهتة حتى ينتهي آخر طلب، لأن React تحتفظ بالقيم المتفائلة حتى تنتهي كل الإجراءات المعلقة. وإجراء النموذج انتقال أصلًا، فلا تحتاج addOptimistic هنا إلى startTransition خاصة بها.

أعطِ كل عنصر متفائل مفتاحًا لن يتعارض مع العناصر الحقيقية. يستخدم المثال pending- مع النص، فإرسال النص نفسه مرتين وكلاهما معلق سيتعارض؛ وتطبيق حقيقي سينشئ معرّفًا على العميل.

عدة تحديثات معًا

لأن دالة التحديث تستقبل الحالة الحالية، تتراكم التحديثات المتفائلة. انقر بسرعة فتُطبَّق كل نقرة معلقة فوق السابقة.

import { startTransition, useOptimistic, useState } from 'react';

let calls = 0;
function addToCart() {
    // Stands in for a real request. Every third call fails.
    calls += 1;
    const fails = calls % 3 === 0;
    return new Promise((resolve, reject) => setTimeout(() => (fails ? reject(new Error()) : resolve()), 1500));
}

export default function App() {
    const [count, setCount] = useState(0);
    const [optimisticCount, addOptimistic] = useOptimistic(count, (current, delta) => current + delta);

    function handleClick() {
        startTransition(async () => {
            addOptimistic(1);
            try {
                await addToCart();
                startTransition(() => setCount((c) => c + 1));
            } catch {
                console.log('one request failed');
            }
        });
    }

    return (
        <div>
            <button onClick={handleClick}>Add to cart</button>
            <p>In cart: {optimisticCount}</p>
            <p style={{ color: '#666' }}>Confirmed: {count}</p>
        </div>
    );
}

انقر أربع مرات بسرعة. تُظهر السلة 4 فورًا. وعندما تنتهي الطلبات، يستقر العدد على 3، لأن الطلب الثالث فشل ووحدة التحكم تقول ذلك. تحتفظ React بالقيم المتفائلة حتى تنتهي كل الإجراءات المعلقة، ثم تعرض العدد الحقيقي.

متى تستخدمه، ومتى لا

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

تجنّبها حيث تكون عبارة «تم» الزائفة مضللة: المدفوعات، وحذف حساب، وأي شيء قد يتصرف المستخدم بناءً عليه قبل معرفة النتيجة. لهذه، اعرض حالة انتظار بـ isPending من useActionState أو useTransition وانتظر الجواب الحقيقي.

أخبر المستخدم دائمًا عندما يحدث تراجع. القيمة التي تعود بصمت تبدو كخطأ برمجي. يحتفظ المثالان أعلاه برسالة خطأ في حالة عادية لتعيش بعد الإجراء.

مع useActionState

يتلاءم useOptimistic وuseActionState معًا. الإجراء المأخوذ من useActionState انتقال أصلًا، فيمكنك ضبط القيمة المتفائلة في بدايته، والحالة المُرجعة هي القيمة الحقيقية التي تعود إليها المتفائلة.

const [state, formAction] = useActionState(async (previous, formData) => {
    const title = formData.get('title');
    setOptimisticTitle(title);
    const saved = await saveTitle(title);
    return { title: saved.title };
}, { title: 'Untitled' });

const [optimisticTitle, setOptimisticTitle] = useOptimistic(state.title);

أثناء عمل الحفظ تعرض الصفحة العنوان الجديد. وعندما يُحل، تحمل state.title القيمة المحفوظة. وإذا رمت saveTitle خطأ، يذهب خطأ الإجراء إلى أقرب حدود أخطاء؛ ولعرض العنوان القديم مع رسالة بدلًا من ذلك، التقط الخطأ داخل الإجراء وأرجع الحالة السابقة مع خطأ.

أخطاء شائعة

استدعاء دالة الضبط خارج إجراء. لا تبقى القيمة المتفائلة على الشاشة، وتحذّر React في التطوير. غلّفها في startTransition أو انقلها إلى إجراء نموذج.

نسيان تحديث الحالة الحقيقية. عند النجاح، يجب أن يغيّر الإجراء الحالة التي يعكسها useOptimistic (setLiked وsetMessages). وإلا اختفت القيمة المتفائلة عندما ينتهي الإجراء، وبدا الطلب الناجح كتراجع.

تحديث الحالة الحقيقية بعد await دون انتقال. ما زال التحديث يصل، لكن React قد تعرضه في لحظة مختلفة عن نهاية الإجراء. غلّفه في startTransition، كما تفعل الأمثلة الثلاثة.

استخدام القيمة المتفائلة كمصدر للحقيقة. أرسل الطلبات واحسب المجاميع من الحالة الحقيقية. القيمة المتفائلة للعرض فقط ويمكن رميها في أي وقت.