القوالب والتخصيص·6 min read·

كيف يعمل الوضع الداكن على مدوّنة VeloCMS (وكيف تضيف زر تبديل للقراء)

لا يوجد زر تبديل جاهز للقراء اليوم — الوضع الفاتح/الداكن على مدوّنة المستأجر إعداد يتحكم فيه صاحب المدوّنة. إليك كيف يعمل النظام الحقيقي وكيف تبني زر تبديل خاص بك باستخدام next-themes.

الوضع الداكن هو ثاني أكثر الميزات طلباً على أي مدوّنة بعد شريط بحث يعمل، لذا يستحق فهم كيفية عمله فعلياً في VeloCMS قبل أن تبني زر تبديل. هناك آليتان منفصلتان: `ThemeProvider` العام (المبني على next-themes) الذي يعمل في كل مكان، وإعداد `default_theme_mode` الخاص بكل مدوّنة والذي يقرر ما إذا كانت المدوّنة العامة للمستأجر تسمح أصلاً بمرور تفضيل القارئ.

أين يقع المزوّد

افتح `src/components/theme/theme-provider.tsx`. يُغلّف next-themes بـ `attribute="class"`، الذي يُبدّل فئة `.dark` على `<html>` — وليس سمة `data-theme`. (سمة `data-theme` في VeloCMS محجوزة لمفهوم مختلف تماماً: أي قالب معروض حالياً، مثل `data-theme="atelier"` — منفصل كلياً عن الوضع الفاتح/الداكن.) يحفظ المزوّد الاختيار في ملف تعريف ارتباط عبر إجراء خادم، ويتولى مصافحة الترطيب التي تمنع الوميض الأبيض عند التحميل.

لماذا قد تكون مدوّنتك مقفلة على وضع واحد بالفعل

لا ترث مدونات المستأجرين العامة تفضيل نظام تشغيل القارئ تلقائياً. يضبط صاحب المدونة `default_theme_mode` (الإدارة ← الإعدادات) على أحد الخيارات: `preset` (يتبع ما صُمم له القالب النشط)، أو `system` (يتبع تفضيل نظام تشغيل/متصفح القارئ)، أو `light` (مقفل)، أو `dark` (مقفل). فقط في حالة `system` يُطبَّق تفضيل الوضع الداكن الخاص بالقارئ فعلياً — وحتى في تلك الحالة، لا يوجد زر تبديل ظاهر مُشحَن لواجهة المدونة العامة اليوم. تحقق من إعداد مدونتك أولاً؛ بناء زر تبديل على مدونة مقفلة لن يُحدث أي أثر.

بناء زر التبديل الخاص بك

إذا كانت مدونتك مضبوطة على وضع `system` وأردت منح القراء تجاوزاً يدوياً (بدلاً من الاعتماد فقط على إعداد نظام التشغيل لديهم)، يمكنك بناء مكوّن عميل صغير باستخدام خطّاف `useTheme()` من next-themes مباشرةً — لا يُشحن أي مكوّن تبديل خاص بـ VeloCMS اليوم، لكن المكتبة الأساسية تبعية موجودة بالفعل.

"use client";
import { useTheme } from "next-themes";
import { useEffect, useState } from "react";

export function ReaderThemeToggle() {
  const { resolvedTheme, setTheme } = useTheme();
  const [mounted, setMounted] = useState(false);
  useEffect(() => setMounted(true), []);
  if (!mounted) return null; // avoid SSR/client mismatch

  return (
    <button
      type="button"
      aria-label="Toggle dark mode"
      onClick={() => setTheme(resolvedTheme === "dark" ? "light" : "dark")}
    >
      {resolvedTheme === "dark" ? "\u2600\uFE0F" : "\u{1F319}"}
    </button>
  );
}

ضع هذا داخل تخطيط شريط التنقل الخاص بثيمك (مثلاً داخل كتلة `<nav className="site-nav">`). صمّمه بـ CSS الخاص بثيمك بدلاً من افتراض وجود مكوّن مشترك جاهز.

التحقق باستخدام لوحة المفاتيح

اضغط Tab للتنقل عبر رأس مدوّنتك. يجب أن يتلقى زر التبديل الخاص بك التركيز ويستجيب لـ Space/Enter — عنصر `<button>` عادي يحصل على هذا مجاناً. أعطه `aria-label` حقيقياً (لا مجرد رمز تعبيري كمحتوى وحيد) حتى يعرف مستخدمو قارئ الشاشة وظيفته، وتحقق من أن إعادة تعيين CSS في ثيمك لم تُزل حلقة التركيز بقاعدة `outline: none` عرضية.