الخطاف use في React: قراءة الوعود والسياق أثناء العرض

use واجهة في React 19 تقرأ قيمة من وعد أو من سياق أثناء عرض المكوّن. يوقف use(promise) المكوّن حتى يُحل الوعد، ويعرض بديل أقرب <Suspense> في الأثناء؛ ويعمل use(context) مثل useContext لكن يمكن أن يكون داخل if أو حلقة.

الدالة fetchUser أدناه بديل عن طلب حقيقي.

import { Suspense, use, useState } from 'react';

function fetchUser(id) {
    console.log('fetching user', id);
    return new Promise((resolve) =>
        setTimeout(() => resolve({ id, name: id === 1 ? 'Ada' : 'Linus' }), 1000),
    );
}

function Profile({ userPromise }) {
    const user = use(userPromise);
    return <p>User #{user.id}: {user.name}</p>;
}

export default function App() {
    const [userPromise, setUserPromise] = useState(() => fetchUser(1));

    return (
        <div>
            <button onClick={() => setUserPromise(fetchUser(1))}>User 1</button>
            <button onClick={() => setUserPromise(fetchUser(2))}>User 2</button>
            <Suspense fallback={<p>Loading...</p>}>
                <Profile userPromise={userPromise} />
            </Suspense>
        </div>
    );
}

يعرض العرض الأول "Loading..." لثانية واحدة، ثم الملف الشخصي. انقر User 2: يعود البديل ما دام الوعد الجديد معلقًا. ليس لـ Profile حالة تحميل خاصة به؛ فهو مكتوب كأن البيانات موجودة أصلًا.

كيف يعمل use(promise)

عندما يستدعي Profile الخطاف use(userPromise):

• إذا كان الوعد قد حُل، يُرجع use قيمته ويستمر العرض.
• وإذا كان ما زال معلقًا، توقف React عرض Profile وتعرض بديل أقرب <Suspense> فوقه. وعندما يستقر الوعد، تعرض React المكوّن Profile من جديد، وهذه المرة يُرجع use القيمة.
• وإذا رُفض، تعرض React أقرب حدود أخطاء بدلًا من ذلك.

تتذكر React النتيجة على كائن الوعد نفسه. ولهذا يجب أن يكون الوعد هو الكائن نفسه في العرض التالي.

ولإبقاء الملف الشخصي القديم على الشاشة أثناء تحميل التالي، اضبط الوعد داخل انتقال. عندها تنتظر React بدلًا من عرض البديل من جديد:

<button onClick={() => startTransition(() => setUserPromise(fetchUser(2)))}>User 2</button>

أين تنشئ الوعد

هذا هو الجزء الذي يوقع الناس في الخطأ. كتابة استدعاء الجلب داخل المكوّن الذي يقرؤه تبدو طبيعية لكنها لا تعمل:

// Do not do this
function Profile({ id }) {
    const user = use(fetchUser(id)); // a new promise on every render
    return <p>{user.name}</p>;
}

كل عرض يستدعي fetchUser ويحصل على وعد جديد معلق. يُعلَّق Profile. وعندما يُحل ذلك الوعد، تعرض React Profile من جديد، فينشئ وعدًا معلقًا آخر، فيُعلَّق من جديد. لا يعرض المكوّن البيانات أبدًا، ويمتلئ تبويب الشبكة بالطلبات.

أنشئ الوعد في مكان لا يُعاد تشغيله مع كل عرض للقارئ:

• في أب، محفوظًا في الحالة (كما في المثال الأول) أو منشأً في معالج حدث.
• على مستوى الوحدة، عندما لا تعتمد البيانات على props: const configPromise = fetchConfig(); فوق المكوّن.
• في ذاكرة مؤقتة مفتاحها الوسائط، فيُرجع المعرّف نفسه الوعد نفسه.
• في إطار عمل: يستطيع مكوّن خادم تمرير وعد إلى مكوّن عميل كـ prop، وتفعل محمّلات المسارات الشيء نفسه. وهذه هي الحالة التي صُمم use لأجلها.

إليك نسخة الذاكرة المؤقتة، ليتمكن مكوّن من طلب البيانات بالمعرّف مع الحصول على وعد ثابت:

import { Suspense, use, useState } from 'react';

const cache = new Map();
function getWeather(city) {
    if (!cache.has(city)) {
        console.log('request for', city);
        // Stands in for a real request
        cache.set(city, new Promise((resolve) => setTimeout(() => resolve(`${city.length * 3} °C`), 800)));
    }
    return cache.get(city);
}

function Weather({ city }) {
    const temperature = use(getWeather(city));
    return <p>{city}: {temperature}</p>;
}

export default function App() {
    const [city, setCity] = useState('Lisbon');

    return (
        <div>
            {['Lisbon', 'Oslo', 'Cairo'].map((c) => (
                <button key={c} onClick={() => setCity(c)}>{c}</button>
            ))}
            <Suspense fallback={<p>Loading weather...</p>}>
                <Weather city={city} />
            </Suspense>
        </div>
    );
}

تنقّل بين المدن الثلاث، ثم عد إلى مدينة فتحتها من قبل. تسجّل وحدة التحكم طلبًا واحدًا لكل مدينة، والمدينة التي رأيتها من قبل تظهر دون البديل، لأن وعدها قد حُل أصلًا. احذف الفحص if (!cache.has(city)) فيعود المكوّن إلى التعليق إلى الأبد.

تحتاج الذاكرة المؤقتة الحقيقية أيضًا إلى طريقة لإنهاء صلاحية المدخلات. تتولى مكتبات البيانات وأطر العمل ذلك، ولهذا تحصل معظم التطبيقات على وعودها من إحداها.

use(context)، حتى داخل if

يُرجع use(SomeContext) القيمة نفسها التي يُرجعها useContext(SomeContext). والفرق هو أين يمكنك استدعاؤه. يجب أن يعمل كل خطاف آخر في المستوى الأعلى، وبالترتيب نفسه في كل عرض (قواعد الخطافات). أما use فيمكن استدعاؤه بعد إرجاع مبكر، أو داخل شرط، أو في حلقة.

import { createContext, use, useState } from 'react';

const UserContext = createContext(null);

function Greeting({ showName }) {
    if (!showName) {
        return <p>Hello!</p>;
    }
    const user = use(UserContext);
    return <p>Hello, {user.name}!</p>;
}

export default function App() {
    const [showName, setShowName] = useState(false);

    return (
        <UserContext value={{ name: 'Grace' }}>
            <button onClick={() => setShowName(!showName)}>
                {showName ? 'Hide' : 'Show'} the name
            </button>
            <Greeting showName={showName} />
        </UserContext>
    );
}

انقر الزر للتبديل بين الفرعين. استبدل use(UserContext) بـ useContext(UserContext) فيخرق الكود قواعد الخطافات، لأن الخطاف سيعمل في بعض مرات العرض دون غيرها.

ما زالت لـ use حدود: لا تستدعِه إلا أثناء عرض مكوّن أو داخل خطاف مخصص. وفي معالج حدث أو تأثير، اقرأ السياق بقيمة حصلت عليها أصلًا أثناء العرض.

الأخطاء: حدود الأخطاء لا try/catch

عندما يُرفض الوعد، يذهب الخطأ إلى أقرب حدود أخطاء، بالطريقة نفسها التي يذهب بها خطأ العرض.

// This throws on purpose: the second request rejects and the boundary shows it.
import { Component, Suspense, use, useState } from 'react';

function fetchPost(id) {
    // Stands in for a real request. Post 2 does not exist.
    return new Promise((resolve, reject) =>
        setTimeout(() => (id === 2 ? reject(new Error('Post 2 not found')) : resolve(`Post ${id} body`)), 600),
    );
}

class ErrorBoundary extends Component {
    state = { error: null };
    static getDerivedStateFromError(error) {
        return { error };
    }
    render() {
        if (this.state.error) return <p style={{ color: 'crimson' }}>{this.state.error.message}</p>;
        return this.props.children;
    }
}

function Post({ postPromise }) {
    return <p>{use(postPromise)}</p>;
}

export default function App() {
    const [id, setId] = useState(1);
    const [postPromise, setPostPromise] = useState(() => fetchPost(1));

    function open(next) {
        setId(next);
        setPostPromise(fetchPost(next));
    }

    return (
        <div>
            <button onClick={() => open(1)}>Post 1</button>
            <button onClick={() => open(2)}>Post 2</button>
            <ErrorBoundary key={id}>
                <Suspense fallback={<p>Loading...</p>}>
                    <Post postPromise={postPromise} />
                </Suspense>
            </ErrorBoundary>
        </div>
    );
}

افتح Post 2 فتعرض الحدود رسالة الخطأ. افتح Post 1 مرة أخرى فيعمل: يعطي key={id} الحدود حالة جديدة لكل منشور، فلا تظل تعرض الخطأ القديم.

لا يمكنك التقاط use معلق أو مرفوض بـ try/catch. ما دام الوعد معلقًا، يقاطع use العرض برمي قيمة خاصة، وكتلة catch حوله ستبتلعها. القيمة الملتقطة خطأ تبدأ رسالته بـ "Suspense Exception: This is not a real error!"، وفي التطوير تسجّل React أيضًا "use was called from inside a try/catch block". ولعرض قيمة احتياطية بدلًا من شاشة خطأ، تعامل مع الرفض على الوعد قبل تمريره إلى الأسفل:

const postPromise = fetchPost(id).catch(() => 'This post could not be loaded.');

use مقارنة بالجلب في useEffect

النمط الكلاسيكي في العميل يجلب في تأثير ويحتفظ بثلاث قطع من الحالة:

function Profile({ id }) {
    const [user, setUser] = useState(null);
    const [error, setError] = useState(null);

    useEffect(() => {
        let ignore = false;
        fetchUser(id).then(
            (u) => !ignore && setUser(u),
            (e) => !ignore && setError(e),
        );
        return () => {
            ignore = true;
        };
    }, [id]);

    if (error) return <p>Error</p>;
    if (!user) return <p>Loading...</p>;
    return <p>{user.name}</p>;
}

نسخة التأثير مكتفية بذاتها، ولهذا ما زالت النهج الأشيع في التطبيقات التي بلا إطار عمل؛ وتتناولها صفحة جلب البيانات بالكامل. أما use فيتألق عندما يبدأ شيء فوق المكوّن الطلب مبكرًا ويسلّم الوعد إلى الأسفل.