useSyncExternalStore في React: الاشتراك في بيانات خارجية

يشترك useSyncExternalStore بمكوّن في بيانات تعيش خارج React ويعيد عرضه كلما تغيرت تلك البيانات. تعطيه دالتين: subscribe، التي تخبر React كيف تستمع إلى التغييرات، وgetSnapshot، التي تُرجع القيمة الحالية.

import { useSyncExternalStore } from 'react';

// A tiny store that lives outside React
let count = 0;
const listeners = new Set();

const counterStore = {
    increment() {
        count += 1;
        listeners.forEach((listener) => listener());
    },
    subscribe(listener) {
        listeners.add(listener);
        return () => listeners.delete(listener);
    },
    getSnapshot() {
        return count;
    },
};

function Display({ name }) {
    const value = useSyncExternalStore(counterStore.subscribe, counterStore.getSnapshot);
    console.log(name, 'rendered with', value);
    return <p>{name} sees {value}</p>;
}

export default function App() {
    return (
        <div>
            <Display name="Header" />
            <Display name="Footer" />
            <button onClick={counterStore.increment}>Increment the store</button>
        </div>
    );
}

لا يتشارك مكوّنا Display أي props ولا سياق، ومع ذلك يتحدثان معًا، لأن كليهما مشترك في المخزن نفسه. يستدعي الزر دالة عادية، لا دالة ضبط من React. أضف <Display name="Sidebar" /> ثالثًا فينضم دون أي تغيير آخر.

الصيغة

const value = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot?);

• تبدأ subscribe(callback) الاستماع، وتستدعي callback كلما احتمل أن تكون البيانات قد تغيرت، وتُرجع دالة لإلغاء الاشتراك. تستدعيها React بعد تركيب المكوّن وتستدعي الدالة المُرجعة عند إزالته.
• تُرجع getSnapshot() القيمة الحالية. تستدعيها React أثناء كل عرض وبعد كل إشعار، ثم تقارن النتيجة بالأخيرة باستخدام Object.is. قيمة نفسها، لا عرض.
• تُرجع getServerSnapshot() (اختيارية) القيمة التي تُستخدم على الخادم وأثناء الإماهة.

عرّف subscribe خارج المكوّن، أو أبقِها ثابتة بـ useCallback. إذا مررت دالة subscribe جديدة في كل عرض، تلغي React الاشتراك وتشترك من جديد في كل مرة.

واجهات المتصفح كمخازن

كل ما له قيمة حالية ويطلق حدثًا عندما تتغير القيمة يناسب هذا الشكل. وnavigator.onLine مع الحدثين online وoffline هو الحالة الكلاسيكية.

import { useSyncExternalStore } from 'react';

function subscribe(callback) {
    window.addEventListener('online', callback);
    window.addEventListener('offline', callback);
    console.log('subscribed to online/offline');
    return () => {
        window.removeEventListener('online', callback);
        window.removeEventListener('offline', callback);
    };
}

function useOnlineStatus() {
    return useSyncExternalStore(
        subscribe,
        () => navigator.onLine,
        () => true
    );
}

export default function App() {
    const online = useOnlineStatus();
    return (
        <p style={{ color: online ? '#1a7f37' : '#c0392b' }}>
            {online ? 'You are online' : 'You are offline: changes will sync later'}
        </p>
    );
}

أطفئ شبكتك (أو بدّل إلى Offline في أدوات المطور في متصفحك) فيتغير النص دون إعادة تحميل. يقول الوسيط الثالث «افترض الاتصال» عند العرض على الخادم، حيث لا يوجد navigator. وتغليف استدعاء الخطاف في useOnlineStatus يجعله خطافًا مخصصًا يستطيع أي مكوّن استخدامه.

ويعمل عرض النافذة بالطريقة نفسها:

import { useSyncExternalStore, useState } from 'react';

function subscribe(callback) {
    window.addEventListener('resize', callback);
    return () => window.removeEventListener('resize', callback);
}

function useWindowWidth() {
    return useSyncExternalStore(subscribe, () => window.innerWidth, () => 1024);
}

function Layout() {
    const width = useWindowWidth();
    return <p>{width}px: {width < 600 ? 'one column' : 'two columns'}</p>;
}

export default function App() {
    const [copies, setCopies] = useState(1);
    return (
        <div>
            <button onClick={() => setCopies(copies + 1)}>Add a copy</button>
            {Array.from({ length: copies }, (_, i) => (
                <Layout key={i} />
            ))}
        </div>
    );
}

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

يجب أن تُرجع getSnapshot قيمة مخزنة مؤقتًا

تستدعي React الدالة getSnapshot كثيرًا وتقارن النتائج بالمرجع. الدالة التي تبني كائنًا أو مصفوفة جديدة في كل استدعاء تبدو دائمًا كتغيير:

// Broken: a new object on every call
function getSnapshot() {
    return { count: store.count, user: store.user };
}

// Also broken: filter returns a new array every time
function getSnapshot() {
    return store.todos.filter((t) => !t.done);
}

تعرض React، وتستدعي getSnapshot، فتحصل على قيمة «مختلفة»، فتعيد العرض، وهكذا، حتى تتوقف بـ "Maximum update depth exceeded". وفي التطوير تسجّل React أولًا أيضًا "The result of getSnapshot should be cached to avoid an infinite loop". أما بناء الإنتاج، مثل المعاينة هنا، فيتخطى هذا التحذير ولا يبلّغ إلا عن الخطأ الأخير كرمز قصير (Minified React error #185).

الإصلاح هو إبقاء البيانات غير قابلة للتعديل في المخزن: استبدل الكائن عندما يتغير، وأرجع المرجع المخزن كما هو.

import { useSyncExternalStore } from 'react';

let state = { todos: [{ id: 1, text: 'Write docs', done: false }] };
const listeners = new Set();

const todoStore = {
    add(text) {
        state = { ...state, todos: [...state.todos, { id: Date.now(), text, done: false }] };
        listeners.forEach((l) => l());
    },
    subscribe(listener) {
        listeners.add(listener);
        return () => listeners.delete(listener);
    },
    getSnapshot() {
        return state;
    },
};

export default function App() {
    const { todos } = useSyncExternalStore(todoStore.subscribe, todoStore.getSnapshot);
    const open = todos.filter((t) => !t.done);
    console.log('render,', todos.length, 'todos');
    return (
        <div>
            <button onClick={() => todoStore.add('Another task')}>Add task</button>
            <ul>
                {open.map((t) => (
                    <li key={t.id}>{t.text}</li>
                ))}
            </ul>
        </div>
    );
}

تُرجع getSnapshot الكائن state نفسه حتى تستبدله add، فيُعرض المكوّن مرة لكل تغيير. ويحدث الترشيح في المكوّن، بعد قراءة اللقطة، وهذا آمن. وللترشيح داخل المخزن بدلًا من ذلك، احسب المصفوفة المرشحة عندما تتغير البيانات وخزّنها، لتتمكن getSnapshot من إرجاع النسخة المخزنة.

getServerSnapshot والإماهة

على الخادم لا توجد نافذة ولا navigator ولا اشتراك. يخبر الوسيط الثالث React بما تعرضه هناك:

const width = useSyncExternalStore(
    subscribe,
    () => window.innerWidth, // in the browser
    () => 1024 // on the server, and during hydration
);

تستخدم React أيضًا getServerSnapshot للعرض الأول في المتصفح عندما تُميه HTML الخادم، ليتطابق الاثنان. وبعد الإماهة مباشرة تقرأ getSnapshot، وإذا اختلفت القيمة الحقيقية، تعيد العرض بها. ومن دون الوسيط الثالث، يرمي العرض على الخادم "Missing getServerSnapshot, which is required for server-rendered content. Will revert to client rendering." إذا كانت هناك حدود <Suspense> فوق المكوّن، يرسل الخادم المحتوى البديل لتلك الحدود ويعرض المتصفح محتواها بدلًا منه؛ ومن دون حدود، يفشل العرض على الخادم.

useSyncExternalStore مقابل useEffect وuseState

يمكنك الاشتراك بتأثير:

function useOnlineStatus() {
    const [online, setOnline] = useState(true);
    useEffect(() => {
        const update = () => setOnline(navigator.onLine);
        update();
        window.addEventListener('online', update);
        window.addEventListener('offline', update);
        return () => {
            window.removeEventListener('online', update);
            window.removeEventListener('offline', update);
        };
    }, []);
    return online;
}

هذا يعمل، لكن فيه نقطتا ضعف. يُظهر العرض الأول دائمًا التخمين الابتدائي، وتصل القيمة الحقيقية بعد عرض واحد، بعد أن يعمل التأثير. ومع العرض المتزامن (أثناء انتقال، مثلًا)، قد توقف React عرضًا في منتصفه؛ وإذا تغير المخزن أثناء التوقف، فقد تُظهر المكوّنات المعروضة قبله وبعده قيمًا مختلفة. يُسمى هذا التضارب tearing (التمزق). أما useSyncExternalStore فيقرأ القيمة أثناء العرض ويجعل React تعيد العرض بشكل متزامن إذا تغير المخزن، فيرى كل مكوّن القيمة نفسها.

استخدمه عندما تعيش البيانات خارج React: وحدة المخزن الخاصة بك، أو واجهة متصفح، أو مكتبة خارجية. معظم مكتبات الحالة (Redux وZustand وغيرهما) تستدعيه نيابة عنك داخل خطافاتها. أما للبيانات التي تنتمي إلى مكوّناتك، فما زالت useState وuseReducer والسياق هي الأدوات المناسبة.