ההוק useOptimistic ב-React: ממשק מיידי עם rollback

useOptimistic הוא הוק של React 19 שמאפשר למסך להציג את התוצאה של action לפני שה-action מסתיים. קובעים ערך אופטימי בתוך action; React מציגה אותו בזמן שה-action ממתין, ואז חוזרת ל-state האמיתי. אם הבקשה נכשלה, ה-state האמיתי אף פעם לא השתנה, ולכן המסך חוזר לאחור בעצמו.

ה-API המזויף בדוגמה הזו מחליף בקשה אמיתית ונכשל בכל קריאה שלישית, כדי שתוכלו לראות את שתי התוצאות.

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

לחצו על הכפתור שלוש פעמים, וחכו שנייה בין לחיצה ללחיצה. שתי הראשונות מתחלפות מיד ושורת ה-saved משיגה אותן שנייה אחר כך. גם השלישית מתחלפת מיד, ואז מתהפכת בחזרה כשהבקשה נכשלת. שנו את calls % 3 ל-calls % 2 וכל לחיצה שנייה נכשלת.

התחביר

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

• state הוא הערך האמיתי, בדרך כלל מ-useState, מ-props או מ-useActionState. כשאף action לא ממתין, optimisticState הוא בדיוק הערך הזה.
• setOptimistic(value) קובע את הערך האופטימי לכל הזמן שה-action הנוכחי רץ.
• updateFn אופציונלי: (currentState, optimisticValue) => nextState. איתו, setOptimistic מקבל שינוי ולא ערך חדש שלם. ראו את צורת ה-reducer בהמשך.

מחזור החיים של לחיצה אחת תמיד זהה:

1. בתוך action, קוראים ל-setOptimistic. המסך מתעדכן מיד.
2. ה-action מחכה לבקשה.
3. בהצלחה מעדכנים את ה-state האמיתי (בתוך startTransition כשזה בא אחרי await).
4. ה-action מסתיים. optimisticState עוקב שוב אחרי state: הערך שנשמר בהצלחה, הערך הישן בכישלון.

שלב 4 הוא הסיבה שאין קוד rollback בדוגמה. בלוק ה-catch רק קובע הודעת שגיאה.

הוא חייב לרוץ בתוך action

הערך האופטימי קיים רק בזמן ש-transition ממתין, ולכן צריך לקרוא ל-setOptimistic בתוך אחד כזה. כל אלה נחשבים:

• הפונקציה שמעבירים ל-startTransition (או ל-startTransition מ-useTransition),
• פונקציה שמועברת ל-<form action={...}> או ל-<button formAction={...}>,
• ה-action שנותנים ל-useActionState.

כשקוראים לו מ-onClick רגיל, לערך האופטימי אין action לחיות בו. React מחזירה אותו מיד, ובפיתוח React רושמת "An optimistic state update occurred outside a transition or action".

עדכונים ל-state האמיתי שקורים אחרי await צריכים להיעטף ב-startTransition משלהם, כמו startTransition(() => setLiked(next)) למעלה. React לא יכולה לדעת, אחרי await, שאתם עדיין בתוך ה-transition הקודם.

רשימת הודעות עם צורת ה-reducer

כשה-state האופטימי הוא רשימה, העבירו פונקציית עדכון כארגומנט השני. ה-setter מקבל אז את הפריט החדש, ו-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 שומרת ערכים אופטימיים עד שכל action ממתין הסתיים. ה-form action הוא כבר transition, ולכן addOptimistic לא צריך כאן startTransition משלו.

תנו לכל פריט אופטימי key שלא יתנגש עם פריטים אמיתיים. הדוגמה משתמשת ב-pending- ועוד הטקסט, כך ששליחת אותו טקסט פעמיים בזמן ששניהם ממתינים הייתה מתנגשת; אפליקציה אמיתית הייתה יוצרת id בצד הלקוח.

כמה עדכונים בבת אחת

מכיוון שפונקציית העדכון מקבלת את ה-state הנוכחי, עדכונים אופטימיים נערמים זה על זה. לחצו מהר וכל לחיצה ממתינה מוחלת מעל הקודמת.

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 שומרת את הערכים האופטימיים עד שכל action ממתין הסתיים, ואז מציגה את הספירה האמיתית.

מתי להשתמש בו, ומתי לא

עדכונים אופטימיים מתאימים ל-actions שכמעט תמיד מצליחים וקל לבטל: לייקים, כוכבים, toggles, שינוי שם, הוספת הודעה. המשתמש לא רואה ספינר במקרה הנפוץ.

הימנעו מהם במקומות שבהם "בוצע" שקרי היה מטעה: תשלומים, מחיקת חשבון, כל דבר שהמשתמש עשוי לפעול לפיו לפני שהתוצאה ידועה. בשבילם, הציגו מצב pending עם isPending מ-useActionState או מ-useTransition וחכו לתשובה האמיתית.

תמיד ספרו למשתמש כש-rollback קורה. ערך שחוזר בשקט נראה כמו באג. שתי הדוגמאות שלמעלה מחזיקות הודעת שגיאה ב-state רגיל כדי שהיא תשרוד אחרי ה-action.

עם useActionState

useOptimistic ו-useActionState משתלבים יחד. ה-action מ-useActionState הוא כבר transition, כך שאפשר לקבוע את הערך האופטימי בתחילתו, וה-state שמוחזר הוא הערך האמיתי שהאופטימי חוזר אליו.

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 זורק שגיאה, השגיאה של ה-action הולכת ל-error boundary הקרוב; כדי להציג במקום את הכותרת הישנה עם הודעה, תפסו את השגיאה בתוך ה-action והחזירו את ה-state הקודם ועוד שגיאה.

טעויות נפוצות

קריאה ל-setter מחוץ ל-action. הערך האופטימי לא נשאר על המסך, ו-React מזהירה בפיתוח. עטפו אותו ב-startTransition או העבירו אותו ל-form action.

לשכוח לעדכן את ה-state האמיתי. בהצלחה, ה-action חייב לשנות את ה-state ש-useOptimistic משקף (setLiked, setMessages). אחרת הערך האופטימי נעלם כשה-action מסתיים, ובקשה מוצלחת נראית כמו rollback.

עדכון ה-state האמיתי אחרי await בלי transition. העדכון עדיין נכנס, אבל React עשויה להציג אותו ברגע אחר מסוף ה-action. עטפו אותו ב-startTransition, כמו שכל שלוש הדוגמאות עושות.

שימוש בערך האופטימי כמקור האמת. שלחו בקשות וחשבו סכומים מה-state האמיתי. הערך האופטימי נועד רק לתצוגה ויכול להיזרק בכל רגע.