حفظ السمة ومنع الوميض

عند تحميل الصفحة، يجب على React تنزيل JavaScript وتحليله وتنفيذه قبل أن يتمكّن من قراءة localStorage وتطبيق السمة الصحيحة. خلال هذه الفترة، يعرض المتصفح الصفحة باستخدام الأنماط الافتراضية. إذا كان المستخدم يفضّل الوضع الداكن وكانت القيمة الافتراضية هي الوضع الفاتح، فسيظهر له وميض أبيض قصير قبل تصحيح السمة.

يكمن الحل في وضع سكربت مضمن داخل document head يُنفّذ بشكل متزامن قبل أي شيفرة أخرى. يقرأ هذا السكربت localStorage فورًا ويعيّن data-theme في document.documentElement. وبما أنه سكربت حاجب، يطبّق المتصفح السمة قبل رسم أي محتوى.

تُنفّذ السكربتات غير المتزامنة أو المؤجلة بعد تحليل HTML، وربما بعد الرسم الأول. وهذا يُفقد الحل هدفه بالكامل. يجب ألا يحتوي السكربت المضمن الحاجب على سمتي async أو defer، وألا يُحمّل من ملف خارجي. كما يجب أن يكون صغيرًا لتقليل تكلفة الأداء.

السكربت الحاجب بسيط: اقرأ localStorage.getItem('theme')، وافحص window.matchMedia('(prefers-color-scheme: dark)').matches كخيار بديل، ثم استدعِ document.documentElement.setAttribute('data-theme', theme). لفّه داخل try-catch تحسبًا لعدم توفر localStorage في وضع التصفح الخاص.

في Next.js، استخدم مكوّن Script من next/script مع strategy="beforeInteractive" داخل _document.js. تحقن استراتيجية beforeInteractive السكربت في HTML الصفحة قبل تشغيل أي JavaScript خاص بالصفحة، محققةً السلوك الحاجب نفسه ضمن مسار إنشاء Next.js.

في مشروع Vite أو Create React App، عدّل index.html مباشرةً وضع وسم السكربت المضمن داخل head قبل أي سكربتات أخرى. بما أن index.html هو نقطة دخول المتصفح، يُنفّذ السكربت قبل بدء React. اجعله موجزًا بحيث يقل حجمه عن 100 بايت.

في التطبيق المعروض من الخادم، يمكن للخادم قراءة السمة من ملف تعريف ارتباط مُرسل مع الطلب. ثم يعيّن الخادم data-theme في HTML المُنشأ قبل إرساله إلى المتصفح. يتجنب هذا أي وميض من جهة العميل، لأن السمة الصحيحة تكون موجودة منذ أول بايت من HTML.

التدفق الكامل هو: ينزّل المتصفح HTML، ويصادف المحلّل سكربتًا مضمنًا حاجبًا، ويقرأ السكربت localStorage ويعيّن data-theme، ثم يواصل المحلّل عمله، وتُرسم الصفحة بالسمة الصحيحة، ويجري React عملية hydration ويلتقط السمة نفسها من localStorage. يرى المستخدم سمة واحدة متسقة منذ البداية.

للتحقق من نجاح الإصلاح، افتح Chrome DevTools، وانتقل إلى علامة التبويب Network، واضبط سرعة الاتصال على Slow 3G. أعد تحميل الصفحة. إذا رأيت تغيّرًا في السمة أثناء التحميل، فهذا يعني أن الوميض لم يُمنع. عند وجود السكربت الحاجب، يجب أن يُظهر الرسم الأول السمة الصحيحة حتى على الاتصالات البطيئة.

إذا كانت الحالة الأولية في React مضبوطة افتراضيًا على السمة الفاتحة، بينما عيّن السكربت الحاجب السمة الداكنة قبل hydration، فقد يصدر React تحذيرًا بشأن عدم تطابق hydration. تجنب ذلك بتهيئة حالة سمة React من خلال قراءة localStorage أيضًا أثناء التصيير الأولي، لضمان تطابق HTML الذي يصيّره React مع حالة DOM التي عيّنها السكربت الحاجب.

لا تحمّل Storybook وبيئات الاختبار ملف index.html الخاص بك، ولذلك لا يُنفّذ السكربت الحاجب. وفّر مزخرفًا أو إعداد اختبار يطبّق سمة data-theme افتراضية في تلك البيئات. يمنع هذا التناقضات المرئية المربكة عند تطوير المكوّنات بشكل معزول.

امنع وميض السمة الخاطئة بحقن سكربت مضمن حاجب صغير في رأس المستند، يقرأ localStorage ويعيّن data-theme قبل أي رسم. في Next.js استخدم strategy="beforeInteractive"، وفي Vite/CRA أضفه مباشرةً إلى index.html. ويمكن لتطبيقات SSR قراءة ملف تعريف ارتباط لتعيين السمة من جهة الخادم.