سوئیچ (Switch)
کنترلی که به کاربر امکان میدهد بین حالت فعال و غیرفعال جابهجا شود.
نصب (Installation)
1npx @quark-lab/rad-ui add switchنمونهها (Examples)
استفاده پایه (Basic Usage)
استفاده ساده از سوئیچ.
مشاهده کد
1import { Switch } from "@/components/ui/switch";
2
3export default function BasicExample() {
4 return <Switch />;
5}
6با برچسب (With Label)
استفاده از سوئیچ همراه با برچسب.
مشاهده کد
1import { Switch } from "@/components/ui/switch";
2import { Label } from "@/components/ui/label";
3
4export default function WithLabelExample() {
5 return (
6 <div className="flex items-center space-x-2 space-x-reverse">
7 <Switch id="airplane-mode" />
8 <Label htmlFor="airplane-mode">حالت هواپیما</Label>
9 </div>
10 );
11}
12پیشفرض فعال (Default Checked)
تنظیم وضعیت پیشفرض سوئیچ به حالت فعال.
مشاهده کد
1import { Switch } from "@/components/ui/switch";
2import { Label } from "@/components/ui/label";
3
4export default function DefaultCheckedExample() {
5 return (
6 <div className="flex items-center space-x-2 space-x-reverse">
7 <Switch id="notifications" defaultChecked />
8 <Label htmlFor="notifications">اعلانها</Label>
9 </div>
10 );
11}
12حالت غیرفعال (Disabled State)
سوئیچ غیرفعال که کاربر نمیتواند آن را تغییر دهد.
مشاهده کد
1import { Switch } from "@/components/ui/switch";
2import { Label } from "@/components/ui/label";
3
4export default function DisabledExample() {
5 return (
6 <div className="flex flex-col gap-4">
7 <div className="flex items-center space-x-2 space-x-reverse">
8 <Switch id="disabled-off" disabled />
9 <Label htmlFor="disabled-off" className="opacity-50">
10 غیرفعال شده
11 </Label>
12 </div>
13 <div className="flex items-center space-x-2 space-x-reverse">
14 <Switch id="disabled-on" disabled defaultChecked />
15 <Label htmlFor="disabled-on" className="opacity-50">
16 همیشه فعال
17 </Label>
18 </div>
19 </div>
20 );
21}
22کنترل شده (Controlled)
مدیریت وضعیت سوئیچ از طریق state.
وضعیت فعلی: غیرفعال
مشاهده کد
1import { useState } from "react";
2import { Switch } from "@/components/ui/switch";
3import { Label } from "@/components/ui/label";
4
5export default function ControlledExample() {
6 const [isEnabled, setIsEnabled] = useState(false);
7
8 return (
9 <div className="space-y-4">
10 <div className="flex items-center space-x-2 space-x-reverse">
11 <Switch
12 id="controlled"
13 checked={isEnabled}
14 onCheckedChange={setIsEnabled}
15 />
16 <Label htmlFor="controlled">فعال کردن ویژگی</Label>
17 </div>
18 <p className="text-sm text-muted-foreground">
19 وضعیت فعلی: {isEnabled ? "فعال" : "غیرفعال"}
20 </p>
21 </div>
22 );
23}
24با توضیحات (With Description)
افزودن توضیحات بیشتر برای سوئیچ.
دریافت ایمیلها درباره محصولات جدید و پیشنهادات ویژه
دریافت اعلان درباره فعالیتهای مشکوک در حساب کاربری
مشاهده کد
1import { useState } from "react";
2import { Switch } from "@/components/ui/switch";
3import { Label } from "@/components/ui/label";
4
5export default function WithDescriptionExample() {
6 const [marketing, setMarketing] = useState(true);
7 const [security, setSecurity] = useState(false);
8
9 return (
10 <div className="space-y-6">
11 <div className="flex items-center justify-between">
12 <div className="space-y-0.5">
13 <Label htmlFor="marketing">ایمیلهای بازاریابی</Label>
14 <p className="text-sm text-muted-foreground">
15 دریافت ایمیلها درباره محصولات جدید و پیشنهادات ویژه
16 </p>
17 </div>
18 <Switch
19 id="marketing"
20 checked={marketing}
21 onCheckedChange={setMarketing}
22 />
23 </div>
24
25 <div className="flex items-center justify-between">
26 <div className="space-y-0.5">
27 <Label htmlFor="security">اعلانهای امنیتی</Label>
28 <p className="text-sm text-muted-foreground">
29 دریافت اعلان درباره فعالیتهای مشکوک در حساب کاربری
30 </p>
31 </div>
32 <Switch
33 id="security"
34 checked={security}
35 onCheckedChange={setSecurity}
36 />
37 </div>
38 </div>
39 );
40}
41یکپارچگی با فرم (Form Integration)
استفاده از سوئیچ در یک فرم استاندارد.
مشاهده کد
1import { useState } from "react";
2import { Switch } from "@/components/ui/switch";
3import { Label } from "@/components/ui/label";
4import { Button } from "@/components/ui/button";
5
6export default function FormExample() {
7 const [airplane, setAirplane] = useState(false);
8
9 return (
10 <form
11 className="space-y-6"
12 onSubmit={(e) => {
13 e.preventDefault();
14 const formData = new FormData(e.currentTarget);
15 console.log("Form data:", Object.fromEntries(formData));
16 }}
17 >
18 <div className="flex items-center justify-between">
19 <div className="space-y-0.5">
20 <Label htmlFor="form-airplane">حالت هواپیما</Label>
21 <p className="text-sm text-muted-foreground">
22 غیرفعال کردن تمام اتصالات بیسیم
23 </p>
24 </div>
25 <Switch
26 id="form-airplane"
27 name="airplaneMode"
28 checked={airplane}
29 onCheckedChange={setAirplane}
30 />
31 </div>
32
33 <div className="flex gap-4">
34 <Button type="submit">ذخیره تنظیمات</Button>
35 <Button
36 type="button"
37 variant="outline"
38 onClick={() => {
39 setAirplane(false);
40 console.log("Settings reset");
41 }}
42 >
43 بازنشانی
44 </Button>
45 </div>
46 </form>
47 );
48}
49مثالهای پیشرفته (Advanced Examples)
پنل تنظیمات (Settings Panel)
گروهی از سوئیچها برای تنظیمات مختلف.
اعلانها
نمایش اعلان هنگام دریافت پیام جدید
نمایش اعلانها روی دسکتاپ
پخش صدا هنگام دریافت اعلان
حریم خصوصی
نمایش وضعیت حضور شما به دیگران
به اشتراک گذاشتن موقعیت مکانی شما
مشاهده کد
1import { Switch } from "@/components/ui/switch";
2import { Label } from "@/components/ui/label";
3
4export default function SettingsExample() {
5 return (
6 <div className="space-y-6">
7 <div>
8 <h3 className="text-lg font-semibold mb-4">اعلانها</h3>
9 <div className="space-y-4">
10 <div className="flex items-center justify-between">
11 <div className="space-y-0.5">
12 <Label>پیامهای جدید</Label>
13 <p className="text-sm text-muted-foreground">
14 نمایش اعلان هنگام دریافت پیام جدید
15 </p>
16 </div>
17 <Switch defaultChecked />
18 </div>
19
20 <div className="flex items-center justify-between">
21 <div className="space-y-0.5">
22 <Label>اعلانهای دسکتاپ</Label>
23 <p className="text-sm text-muted-foreground">
24 نمایش اعلانها روی دسکتاپ
25 </p>
26 </div>
27 <Switch />
28 </div>
29
30 <div className="flex items-center justify-between">
31 <div className="space-y-0.5">
32 <Label>صدای اعلان</Label>
33 <p className="text-sm text-muted-foreground">
34 پخش صدا هنگام دریافت اعلان
35 </p>
36 </div>
37 <Switch defaultChecked />
38 </div>
39 </div>
40 </div>
41
42 <div className="border-t border-border pt-6">
43 <h3 className="text-lg font-semibold mb-4">حریم خصوصی</h3>
44 <div className="space-y-4">
45 <div className="flex items-center justify-between">
46 <div className="space-y-0.5">
47 <Label>نمایش وضعیت آنلاین</Label>
48 <p className="text-sm text-muted-foreground">
49 نمایش وضعیت حضور شما به دیگران
50 </p>
51 </div>
52 <Switch defaultChecked />
53 </div>
54
55 <div className="flex items-center justify-between">
56 <div className="space-y-0.5">
57 <Label>اشتراکگذاری موقعیت</Label>
58 <p className="text-sm text-muted-foreground">
59 به اشتراک گذاشتن موقعیت مکانی شما
60 </p>
61 </div>
62 <Switch />
63 </div>
64 </div>
65 </div>
66 </div>
67 );
68}
69تنظیمات با ذخیره خودکار (Auto-save Settings)
ذخیره خودکار تنظیمات پس از تغییر.
مشاهده کد
1const [settings, setSettings] = useState({
2 notifications: true,
3 darkMode: false,
4 analytics: true
5});
6
7// Auto-save on change
8const updateSetting = (key, value) => {
9 setSettings(prev => {
10 const newSettings = { ...prev, [key]: value };
11 // Save to API or localStorage
12 localStorage.setItem('settings', JSON.stringify(newSettings));
13 return newSettings;
14 });
15};
16
17<div className="space-y-4">
18 <div className="flex items-center justify-between">
19 <Label>Enable Notifications</Label>
20 <Switch
21 checked={settings.notifications}
22 onCheckedChange={(checked) =>
23 updateSetting('notifications', checked)
24 }
25 />
26 </div>
27 {/* ... other settings */}
28</div>مرجع API (API Reference)
Switch
پراپهای کامپوننت Switch.
| پراپ (Prop) | نوع (Type) | پیشفرض (Default) | توضیحات (Description) |
|---|---|---|---|
checked | boolean | undefined | وضعیت کنترل شده |
defaultChecked | boolean | false | وضعیت پیشفرض (غیرکنترل شده) |
onCheckedChange | (checked: boolean) => void | undefined | تابع فراخوانی هنگام تغییر وضعیت |
disabled | boolean | false | غیرفعال کردن سوئیچ |
required | boolean | false | اجباری بودن در فرم |
name | string | undefined | نام فیلد برای ارسال فرم |
value | string | "on" | مقدار ارسالی در فرم |
className | string | undefined | کلاسهای CSS سفارشی |
دسترسیپذیری (Accessibility)
کیبورد (Keyboard)
Space- تغییر وضعیت سوئیچEnter- تغییر وضعیت سوئیچTab- حرکت به سوئیچ بعدی
ARIA نقش (ARIA Role)
کامپوننت از نقش switch استفاده میکند که برای خوانندگان صفحه مناسب است
برچسبها (Labels)
همیشه از کامپوننت Label با ویژگی htmlFor استفاده کنید تا سوئیچ را با برچسب مرتبط کنید
وضعیت (State)
وضعیت سوئیچ از طریق aria-checked به صورت خودکار اعلام میشود
بهترین شیوهها (Best Practices)
برچسب واضح (Clear Labels)
از برچسبهایی استفاده کنید که عملکرد سوئیچ را به وضوح توضیح میدهند. از فعلهای عملی استفاده کنید.
تاثیر فوری (Immediate Effect)
سوئیچ باید تنظیمات را بلافاصله اعمال کند. اگر نیاز به تایید دارید، از Checkbox استفاده کنید.
توضیحات کمکی (Helper Text)
برای تنظیمات پیچیده، متن توضیحی اضافه کنید تا کاربر بداند چه اتفاقی میافتد
گروهبندی (Grouping)
سوئیچهای مرتبط را در بخشهای منطقی دستهبندی کنید (مثل اعلانها، حریم خصوصی)
تفاوت با Checkbox
از Switch برای تنظیمات فوری (روشن/خاموش) و از Checkbox برای انتخابهای چندگانه که نیاز به ارسال دارند استفاده کنید