البث في React 18: كيف يعمل renderToPipeableStream؟

قبل React 18، كان العرض من جانب الخادم يستخدم renderToString، وهو متزامن: إذ يعرض React شجرة المكوّنات كاملةً في صورة سلسلة نصية قبل إرسال أي HTML إلى المتصفح. إذا حمّل أي مكوّن بيانات، فعلى الخادم انتظار اكتمال جميع البيانات قبل وصول البايت الأول إلى المستخدم.

قدّم React 18 الدالة renderToPipeableStream، التي تعرض شجرة المكوّنات باعتبارها تدفقًا من أجزاء HTML. فبدلًا من انتظار جاهزية كل شيء، يرسل React HTML عند اكتمال كل جزء من الشجرة، مما يتيح للمتصفح بدء عرض المحتوى المرئي فورًا.

تعيد renderToPipeableStream كائنًا يحتوي على طريقتين: pipe(writable) وabort(). تقبل pipe تدفق Node.js Writable (وعادةً ما يكون استجابة HTTP) وتبدأ إرسال HTML إليه. تلغي abort() التدفق، وتُستخدم عند إلغاء الطلب أو تجاوز مهلة الانتظار.

يبدأ التدفق بغلاف HTML — أي كل المحتوى غير المحجوب بسبب حدّ Suspense معلّق. ويشمل ذلك رأس المستند، والتنقّل، والتذييل، وعناصر التخطيط الثابتة، وأي محتوى متاح بصورة متزامنة. يتدفق الغلاف فورًا، قبل اكتمال أي مكوّن يعتمد على البيانات.

تتدفق المكوّنات الموجودة داخل حدود Suspense والمنتظرة للبيانات في البداية باعتبارها واجهة المستخدم البديلة (مثل مؤشر تحميل). يرسل React لاحقًا وسم script يستبدل العنصر البديل بالمحتوى المكتمل — وكل ذلك من دون إعادة عرض الغلاف من جانب العميل.

مرّروا bootstrapScripts: ['/static/js/client.js'] إلى renderToPipeableStream لإخبار React بإدراج وسم script في نهاية التدفق. يحمّل المتصفح هذه الحزمة ويستدعي hydrateRoot، ليربط معالجات أحداث React بـ DOM الذي عرضه الخادم.

تُستدعى onShellReady عندما يصبح غلاف HTML (أي كل ما يقع خارج حدود Suspense المعلّقة) جاهزًا للإرسال. وهذه هي اللحظة الصحيحة لاستدعاء pipe(res) — لكن من المهم ضبط رمز حالة HTTP وترويسات الاستجابة قبل استدعاء pipe، لأن بدء التدفق يثبّت حالة HTTP.

بما أن البث يبدأ فور استدعاء pipe()، يجب أن تتم جميع عمليات الإسناد إلى res.setHeader أو res.statusCode قبل استدعاء pipe. من الأنماط الشائعة ضبط الحالة على 200 وضبط Content-Type على text/html داخل استدعاء onShellReady، ثم استدعاء pipe(res) مباشرة بعد ذلك.

يُستدعى onShellError عند حدوث خطأ غير قابل للاسترداد قبل اكتمال عرض هيكل الصفحة، مثل أن يطرح مكوّن في المستوى الأعلى خطأً خارج أي حد من حدود Suspense. في هذه الحالة، لا يمكن بث استجابة جزئية؛ بل يجب إعادة التوجيه إلى صفحة خطأ أو إرسال مستند HTML ثابت لعرض الخطأ.

يُستدعى onAllReady عند اكتمال معالجة شجرة React بأكملها، بما في ذلك جميع حدود Suspense. بالنسبة إلى برامج زحف محركات البحث وأدوات معاينة الروابط في وسائل التواصل الاجتماعي، ينبغي إرسال HTML الكامل من دون بث. تحقّق مما إذا كان الطلب صادرًا عن برنامج روبوت، واستدعِ pipe(res) داخل onAllReady بدلًا من onShellReady.

يُستدعى onError عند حدوث أخطاء داخل حدود Suspense؛ إذ يستطيع React مواصلة بث بقية الصفحة بينما يعرض ذلك الحد واجهة الخطأ البديلة. استخدم onError لتسجيل الخطأ في مسار observability لديك من دون إيقاف البث للمستخدم.

متى ينبغي استخدام onAllReady بدلًا من onShellReady لبدء استدعاء pipe؟

يُعد renderToPipeableStream الواجهة الأساسية للبث في SSR لدى React 18 لخوادم Node.js. فهو يبث هيكل HTML فورًا عبر onShellReady، ويملأ حدود Suspense عند اكتمال البيانات، ويُجري hydration للعميل عبر bootstrapScripts. استخدم onAllReady لبرامج الروبوت وبرامج الزحف، وonShellError للإخفاقات الفادحة، واضبط ترويسات HTTP دائمًا قبل استدعاء pipe().