واجهة API useSyncExternalStore ومعلماتها

تقبل useSyncExternalStore ما يصل إلى ثلاث وسائط: subscribe وgetSnapshot وgetServerSnapshot الاختيارية. وتوضح هذه الوسائط مجتمعةً لـ React كيفية الاستماع إلى التغييرات وكيفية قراءة القيمة الحالية.

يُعد فهم كل وسيطة أمرًا أساسيًا، إذ إن الأخطاء الصغيرة فيها هي المصدر الأكثر شيوعًا للأخطاء عند استخدام هذه الوصلة.

تتلقى subscribe استدعاءً من React، ويجب أن تسجله في المخزن كي يُنفَّذ الاستدعاء كلما تغيّر المخزن. ويجب أن تعيد دالة لإلغاء الاشتراك، تستدعيها React عند التنظيف.

تستخدم React هذه الآلية لمعرفة وقت إعادة قراءة اللقطة، لذا تقتصر مهمة subscribe على إعداد إشعارات التغيير وإزالتها.

تعيد getSnapshot القيمة الحالية للمخزن. تستدعيها React أثناء التصيير لقراءة الحالة، ثم تستدعيها مجددًا بعد الإشعارات لاكتشاف ما إذا كانت القيمة قد تغيّرت.

والأهم أنها يجب أن تعيد نتيجة مستقرة مرجعيًا عندما لا تكون البيانات الأساسية قد تغيّرت، أي أن تعيد المرجع نفسه بدلًا من إنشاء كائن جديد في كل مرة.

توفر getServerSnapshot الاختيارية القيمة المستخدمة أثناء التصيير من جانب الخادم وأثناء مرحلة إعادة الإماهة الأولية. وهي ضرورية لأن getSnapshot المخصصة للمتصفح قد تعتمد على واجهات برمجية غير موجودة على الخادم.

ويمنع توفيرها عدم تطابق إعادة الإماهة، إذ يمنح الخادم قيمة منطقية لتصييرها، تطابق ما سينتجه العميل مبدئيًا.

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

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

يجب أن تُنفَّذ getSnapshot بشكل متزامن وأن تعيد قيمة مشتقة حصريًا من حالة المخزن الحالية. وينبغي ألا تنفّذ عملًا غير متزامن أو تنتج نتائج مختلفة للبيانات الأساسية نفسها.

تعتمد React على استدعائها مرارًا ومقارنة النتائج، لذلك قد يؤدي أي سلوك غير حتمي أو آثار جانبية داخلها إلى سلوك غير صحيح.

تجعل المخازن التي تحتفظ بحالة غير قابلة للتغيير من السهل تنفيذ getSnapshot، إذ لا يتغير مرجع كائن الحالة الحالية إلا عند تغيّر البيانات. ويمنحك إعادة هذا المرجع مقارنات مستقرة تلقائيًا.

ولهذا تتوافق أنماط التحديث غير القابلة للتغيير جيدًا مع هذه الوصلة: البيانات المتساوية تعني مرجعًا متساويًا، وتتجاوز React عمليات إعادة التصيير غير الضرورية.

من الأخطاء الشائعة إعادة كائن أو مصفوفة جديدة تمامًا من getSnapshot في كل استدعاء، مثل تنفيذ عملية mapping أو filtering داخلها. ترى React مرجعًا جديدًا في كل مرة، فتظن أن القيمة قد تغيّرت.

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

لتجنب الحلقة، احسب البيانات المشتقة خارج getSnapshot أو استخدم memoize بحيث تعيد الدالة مرجعًا مخزّنًا مؤقتًا. ويوجد نمط شبيه بالمحدِّد تستخدمه مكتبات كثيرة تحديدًا لإدارة هذا الاستقرار.

القاعدة الإرشادية هي أن يعيد استدعاءان لـ getSnapshot، مع عدم تغيّر بيانات المخزن، المرجع نفسه تمامًا.

عمليًا، تكتب subscribe تضيف مستمعًا وتزيله، وgetSnapshot تقرأ قيمة حالية مستقرة، وgetServerSnapshot تعيد قيمة آمنة للخادم عند استخدام SSR.

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

حدّد دور getSnapshot.

تقبل الوصلة subscribe وgetSnapshot، وتقبل getServerSnapshot اختياريًا. تربط subscribe مستمعًا وتعيد دالة لإلغاء الاشتراك؛ وتقرأ getSnapshot القيمة الحالية بشكل متزامن، ويجب أن تكون مستقرة مرجعيًا؛ أما getServerSnapshot فتوفّر قيمة آمنة لـ SSR.

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