مفتاح التبديل (Switch)

يتيح لك مكوّن مفتاح التبديل (Switch) تشغيل إعداد أو إيقافه.

التثبيت

bash

npx @smicolon/cli add switch

قبل إضافة أي مكوّن، شغّل الأمر init مرة واحدة في مشروعك. التفاصيل في صفحة التثبيت.

معاينة

وضع الطيرانالإشعاراتتصلك الإشعارات الفوريةتنزيل التحديثات تلقائيًا عبر بيانات الجوّال عند غياب شبكة Wi-Fi

الأنماط (variant)

يأتي مفتاح التبديل بنمطين (variant) كما في Figma. النمط (variant) solid هو الافتراضي، ويملأ المسار باللون الأساسي عند التشغيل. أما النمط (variant) outline فيُبقي المسار بلون خلفية الصفحة ويرسم حوله خطًا بسماكة 1px، ويلوّن المقبض بدلًا منه.

solidالمزامنة التلقائيةخدمات الموقع

outlineالمزامنة التلقائيةخدمات الموقع

الأحجام

يتوفر مفتاح التبديل بثلاثة أحجام، والحجم الافتراضي هو md. يبلغ عرض المسار 32 أو 40 أو 48px، ويبقى حجم التسمية ثابتًا.

التخطيط (layout)

في التخطيط (layout) الافتراضي control-first يأتي المسار قبل التسمية، ويبدأ الوصف تحت التسمية مباشرة. أما التخطيط (layout) label-first فيضع التسمية في بداية سطر بعرض كامل والمسار في نهايته، وهو مناسب لقوائم الإعدادات.

control-firstالوضع الداكنشغّل الوضع الداكن أو أوقفهالإشعاراتتصلك الإشعارات الفورية

label-first

الوضع الداكنشغّل الوضع الداكن أو أوقفهالإشعاراتتصلك الإشعارات الفوريةوضع الطيران

الحالات

تأتي حالة التركيز (focus) من CSS مباشرة، لا من خاصية. انتقل إلى مفتاح التبديل بمفتاح Tab لترى حلقة التركيز. وعند التعطيل يظهر المكوّن كله باهتًا، بما فيه التسمية والوصف.

إتاحة الوصول (accessibility)

يعمل مفتاح التبديل مع لوحة المفاتيح تلقائيًا: تبدّل حالته بمفتاح المسافة، ويُرسَل مع النموذج دون شيفرة إضافية، لأنه مبني على عنصر <input type="checkbox" role="switch"> الأصلي.
يقرأ قارئ الشاشة نص description بعد التسمية مباشرة، لأنه مرتبط بمفتاح التبديل عبر aria-describedby. أما المسار المرسوم فمخفي عن قارئ الشاشة.
أضف aria-label لمفتاح التبديل الذي يظهر بلا label، ليعرف قارئ الشاشة ما يتحكم فيه.
يتبع مفتاح التبديل اتجاه الصفحة المحدد في السمة (attribute) dir، فيتحرك المقبض دائمًا نحو نهاية السطر عند التشغيل.

الخصائص (props)

الخاصية	النوع	الافتراضي	الوصف
`variant`	`"solid" \| "outline"`	`"solid"`	مسار مملوء أو مسار بإطار.
`layout`	`"control-first" \| "label-first"`	`"control-first"`	المسار قبل التسمية أو بعدها.
`size`	`"sm" \| "md" \| "lg"`	`"md"`	حجم مفتاح التبديل.
`checked`	`boolean`	لا يوجد	حالة التشغيل، وتُستخدم مع `onChange`.
`defaultChecked`	`boolean`	`false`	الحالة الأولى عندما لا تتحكم بالقيمة.
`disabled`	`boolean`	`false`	يعطّل المفتاح ويُظهره باهتًا.
`label`	`string`	لا يوجد	نص التسمية.
`description`	`string`	لا يوجد	سطر ثانوي تحت التسمية.
`name`	`string`	لا يوجد	الاسم الذي يُرسَل مع النموذج.
`onChange`	`(event) => void`	لا يوجد	تُستدعى عند تغيير حالة المفتاح.
`className`	`string`	لا يوجد	أصناف (class) إضافية للمكوّن.

الاستخدام

tsx

import { Switch } from "@/components/ui/switch"

// مفتاح تبديل بسيط
<Switch aria-label="وضع الطيران" />

// مع تسمية
<Switch label="وضع الطيران" defaultChecked />

// مع وصف
<Switch
  label="الوضع الداكن"
  description="شغّل الوضع الداكن أو أوقفه"
/>

// النمط (variant) outline
<Switch variant="outline" label="المزامنة التلقائية" />

// التسمية أولًا والمسار في النهاية
<Switch layout="label-first" label="الإشعارات" />

// أحجام مختلفة
<Switch size="sm" label="صغير" />
<Switch size="md" label="متوسط" />
<Switch size="lg" label="كبير" />

// التحكّم بالقيمة
const [enabled, setEnabled] = useState(true)

<Switch
  label="الإشعارات"
  checked={enabled}
  onChange={(e) => setEnabled(e.target.checked)}
/>

الإشعارات

الحالة الحالية: قيد التشغيل