Sliderv1.0.0
برای انتخاب عددی از یک بازهٔ پیوسته، وقتی مقدار دقیق مهم نیست ولی حس نسبتِ آن مهم است: قیمت، حجم صدا، اندازهٔ قلم. با دو دستگیره تبدیل به انتخابگر بازه می‌شود.
این کامپوننت فعلاً برای ۱ فریم‌ورک از ۴ فریم‌ورک آماده است.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
نصب
با CLI اختصاصی digdesign کامپوننت را از رجیستری دیگ نصب کنید؛ وابستگی‌ها و فایل‌ها خودکار اضافه می‌شوند.
npx digdesign@latest add https://docs.digdesign.ir/r/slider.jsonpnpm dlx digdesign@latest add https://docs.digdesign.ir/r/slider.jsonyarn dlx digdesign@latest add https://docs.digdesign.ir/r/slider.jsonbunx --bun digdesign@latest add https://docs.digdesign.ir/r/slider.jsonاین کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
استفاده
"use client"
import * as React from "react"
import { Slider } from "@/components/ui/slider"
const [volume, setVolume] = React.useState([40])
<Slider value={volume} onValueChange={setVolume} max={100} step={1} />این کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
ترکیب اجزا
مقدار همیشه آرایه است، حتی برای یک دستگیره؛ تعداد دستگیره‌ها از طول همان آرایه خوانده می‌شود، پس برای انتخاب بازه کافی است آرایه‌ای دوعضوی بدهید.
اگر نه value بدهید و نه defaultValue، یک دستگیره روی min می‌نشیند.
جهت حرکت از dir صفحه می‌آید: در چیدمان راست‌به‌چپ، کمینه سمت راست و بیشینه سمت چپ است و کلیدهای جهت‌دار هم برعکس همان کار می‌کنند.
دسترس‌پذیری
- هر دستگیره یک slider واقعی با نقش ARIA است؛ کلیدهای چپ/راست و بالا/پایین مقدار را به اندازهٔ step و PageUp/PageDown با گام بزرگ‌تر تغییر می‌دهند و Home/End به کمینه و بیشینه می‌روند.
- برای هر لغزنده یک برچسب بگذارید؛ اگر برچسب دیداری ندارید aria-label بدهید و در حالت بازه برای هر دستگیره یک aria-label جدا (مثلاً «کمترین قیمت» و «بیشترین قیمت»).
- لغزنده مقدار دقیق را به کاربر نشان نمی‌دهد؛ عدد فعلی را کنار برچسب چاپ کنید تا کاربر صفحه‌خوان و کاربر عادی هر دو بدانند کجا هستند.
- چون در راست‌به‌چپ جهت افقی برعکس می‌شود، dir="rtl" را روی html یا نزدیک‌ترین والد نگه دارید؛ بدون آن جهت پیش‌فرض ltr گرفته می‌شود و کلیدهای جهت‌دار برعکس عمل می‌کنند.
- برای مقادیر حساس (قیمت، تعداد) لغزنده را با یک ورودی عددی جفت کنید؛ کاربران با محدودیت حرکتی نمی‌توانند دقیق بکشند.
مرجع API
Slider
| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| value / onValueChange | number[] / (value: number[]) => void | — | حالت کنترل‌شده. onValueChange در تمام طول کشیدن صدا می‌زند. |
| defaultValue | number[] | [min, max] | مقدار اولیه در حالت کنترل‌نشده؛ طول آرایه تعداد دستگیره‌ها را تعیین می‌کند. |
| onValueCommit | (value: number[]) => void | — | فقط وقتی کاربر دستگیره را رها می‌کند صدا زده می‌شود؛ برای درخواست شبکه از این استفاده کنید نه onValueChange. |
| min | number | 0 | کمینهٔ بازه. |
| max | number | 100 | بیشینهٔ بازه. |
| step | number | 1 | اندازهٔ هر گام؛ با کلیدهای جهت‌دار هم همین گام است. |
| minStepsBetweenThumbs | number | 0 | حداقل فاصلهٔ دو دستگیره برحسب تعداد گام؛ جلوی روی‌هم افتادن بازه را می‌گیرد. |
| orientation | "horizontal" | "vertical" | "horizontal" | جهت لغزنده. |
| dir | "rtl" | "ltr" | — | معمولاً لازم نیست؛ از dir صفحه ارث می‌رسد و جهت حرکت را تعیین می‌کند. |
| inverted | boolean | false | پر شدن نوار را از سمت مخالف شروع می‌کند. |
| disabled | boolean | false | غیرفعال کردن کامل لغزنده. |
| name | string | — | برای ارسال در فرم؛ برای هر دستگیره یک input مخفی ساخته می‌شود. |
| formatOptions | Intl.NumberFormatOptions | — | قالب نمایش مقدار با ارقام فارسی: در aria-valuetext و حباب شناور استفاده می‌شود. برای پول یا درصد مناسب است. |
| showTooltip | boolean | false | نمایش حباب مقدار روی دستگیره حین کشیدن یا فوکوس کیبورد. |
| thumbLabel | string | string[] | — | برچسب صفحه‌خوان هر دستگیره (aria-label). در حالت بازه یک آرایه بدهید تا دستگیره‌ها از هم متمایز شوند؛ در غیر این صورت جای aria-label می‌نشیند. |
data-slot
هر جزء داخلی یک data-slot دارد؛ برای استایل‌دهی سفارشی از همین‌ها استفاده کنید.
| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| slider-track | div | — | نوار پس‌زمینه (کل بازه). |
| slider-range | div | — | بخش پرشدهٔ نوار بین کمینه و مقدار فعلی. |
| slider-thumb | span | — | دستگیره؛ به ازای هر مقدار یکی رندر می‌شود. حین کشیدن data-dragging می‌گیرد. |
| slider-tooltip | span | — | حباب مقدار شناور، فقط وقتی showTooltip فعال است. |
این کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
نمونه‌ها
Range
آرایهٔ دوعضوی یعنی دو دستگیره؛ ناحیهٔ بین آن‌ها پررنگ می‌شود. برچسبِ ابتدا/انتهای بازه با خودِ دستگیره‌ها زنده است.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
Steps
step بزرگ‌تر یعنی مقادیر گسسته؛ برای امتیازدهی یا انتخاب تعداد مناسب است. عدد کنار برچسب با کشیدن دستگیره زنده به‌روز می‌شود.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
Vertical
با orientation="vertical" لغزنده ایستاده می‌شود؛ ارتفاع را روی کلاس خودتان بدهید.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
Disabled
در حالت disabled کل لغزنده کم‌رنگ می‌شود و دستگیره فوکوس نمی‌گیرد.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
With Number Input
الگوی پیشنهادی برای مقادیر دقیق: لغزنده برای حس نسبت، عدد برای دقت. مقدار را در state نگه دارید و به هر دو بدهید.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
راهنمای شناور روی دستگیره
با showTooltip، حین کشیدن یا فوکوس کیبورد، یک حباب مقدار روی دستگیره ظاهر می‌شود؛ برای مقادیری که کاربر نمی‌خواهد چشمش را از دستگیره بردارد مناسب است.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
قالب‌بندی مقدار
formatOptions مقدار را با Intl.NumberFormat و ارقام فارسی قالب‌بندی می‌کند، هم در aria-valuetext برای صفحه‌خوان، هم در حباب شناور. برای واحد پول یا درصد مناسب است.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
معکوس
با inverted، پر شدن نوار و جهت کلیدهای جهت‌دار از سمت مخالفِ حالت عادی شروع می‌شود؛ برای مواردی مثل «فاصله تا هدف» که کم‌ترشدن یعنی نزدیک‌ترشدن به انتها مناسب است.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
نامعتبر (Invalid)
aria-invalid را برای محدودهٔ توصیه‌شده به کار ببرید، نه برای min و max که خودِ اسلایدر جلویشان را می‌گیرد. پیام باید بگوید چرا این مقدار مشکل‌ساز است.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
نمایشِ صرف در برابر کنترل
اسلایدر غیرفعال، مقدار را هم کم‌رنگ و خواندنش را سخت می‌کند. اگر عدد فقط باید دیده شود و تغییر نمی‌کند، Progress با عدد کنارش انتخاب درست‌تری است.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
در حال اعمال (Loading)
با onValueCommit درخواست بفرستید، نه با onValueChange؛ وگرنه برای هر پیکسل حرکت یک درخواست می‌رود. تا پایان کار کنترل را قفل کنید و aria-busy بگذارید.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
کدام نمونه برای کدام موقعیت
| نمونه | کجا به کار می‌آید |
|---|---|
| Range | آرایهٔ دوعضوی یعنی دو دستگیره؛ ناحیهٔ بین آن‌ها پررنگ می‌شود |
| Steps | step بزرگ‌تر یعنی مقادیر گسسته؛ برای امتیازدهی یا انتخاب تعداد مناسب است |
| Vertical | با orientation="vertical" لغزنده ایستاده می‌شود؛ ارتفاع را روی کلاس خودتان بدهید. |
| Disabled | در حالت disabled کل لغزنده کم‌رنگ می‌شود و دستگیره فوکوس نمی‌گیرد. |
| With Number Input | الگوی پیشنهادی برای مقادیر دقیق: لغزنده برای حس نسبت، عدد برای دقت |
| راهنمای شناور روی دستگیره | با showTooltip، حین کشیدن یا فوکوس کیبورد، یک حباب مقدار روی دستگیره ظاهر می‌شود؛ برای مقادیری که کاربر نمی‌خواهد چشمش را از دستگیره بردارد مناسب است. |
| قالب‌بندی مقدار | formatOptions مقدار را با Intl.NumberFormat و ارقام فارسی قالب‌بندی می‌کند، هم در aria-valuetext برای صفحه‌خوان، هم در حباب شناور |
| معکوس | با inverted، پر شدن نوار و جهت کلیدهای جهت‌دار از سمت مخالفِ حالت عادی شروع می‌شود؛ برای مواردی مثل «فاصله تا هدف» که کم‌ترشدن یعنی نزدیک‌ترشدن به انتها مناسب است. |
| نامعتبر (Invalid) | مقداری که فنی مجاز است ولی از نظر کسب‌وکار توصیه نمی‌شود |
| نمایشِ صرف در برابر کنترل | نشان‌دادن مقدار فعلی بدون امکان تغییر |
| در حال اعمال (Loading) | تنظیمی که با رهاکردن دسته، به سرور می‌رود |
دستورالعمل استفاده
مقدار فعلی را کنار برچسب نشان بده
انجام بده
چون خودِ لغزنده عدد دقیق را نشان نمی‌دهد، برای کارهای دقیق (قیمت، حجم صدا) مقدار را کنار برچسب چاپ کنید تا کاربر بداند دقیقاً کجا ایستاده.
انجام نده
بدون هیچ عددی، کاربر فقط موقعیت نسبی دستگیره را می‌بیند و باید حدس بزند مقدار دقیق چقدر است.
برچسب مستقل برای هر دستگیره در حالت بازه
انجام بده
وقتی مقدار دوعضوی است و انتخابگر بازه می‌شود، برای هر دستگیره یک aria-label جدا مثل «کمترین قیمت» بگذارید تا صفحه‌خوان دستگیره‌ها را از هم تشخیص دهد.
انجام نده
یک aria-label مشترک یا خالی روی هر دو دستگیره یعنی کاربر صفحه‌خوان نمی‌فهمد الان کدام دستگیره را حرکت می‌دهد: کمینه یا بیشینه.
گام متناسب با نوع مقدار
انجام بده
برای مقادیر گسسته مثل امتیاز، step را برابر با واحد معنادار بگذارید (مثلاً ۱) تا فقط روی عددهای قابل‌قبول بایستد.
انجام نده
step ریز روی مقداری که ذاتاً گسسته است (امتیاز، تعداد ستاره) باعث می‌شود کاربر بین عددهای بی‌معنی مثل ۳.۲ گیر کند.