Carouselv1.0.0
اسلایدهایی که با کشیدن، کیبورد یا دکمه‌های قبلی/بعدی پیمایش می‌شوند. موتور اسکرول Embla است؛ جهتش (rtl/ltr) هم روی چیدمان بصری و هم روی معنای کلیدهای جهت‌نما اثر می‌گذارد.
این کامپوننت فعلاً برای ۱ فریم‌ورک از ۴ فریم‌ورک آماده است.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
نصب
با CLI اختصاصی digdesign کامپوننت را از رجیستری دیگ نصب کنید؛ وابستگی‌ها و فایل‌ها خودکار اضافه می‌شوند.
npx digdesign@latest add https://docs.digdesign.ir/r/carousel.jsonpnpm dlx digdesign@latest add https://docs.digdesign.ir/r/carousel.jsonyarn dlx digdesign@latest add https://docs.digdesign.ir/r/carousel.jsonbunx --bun digdesign@latest add https://docs.digdesign.ir/r/carousel.jsonاین کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
استفاده
import {
Carousel,
CarouselContent,
CarouselItem,
CarouselNext,
CarouselPrevious,
} from "@/components/ui/carousel"
<Carousel>
<CarouselContent>
<CarouselItem>...</CarouselItem>
<CarouselItem>...</CarouselItem>
</CarouselContent>
<CarouselPrevious />
<CarouselNext />
</Carousel>این کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
ترکیب اجزا
Carousel یک CarouselContext می‌سازد که carouselRef، وضعیت اسکرول (canScrollPrev/canScrollNext) و همان api خام Embla را نگه می‌دارد؛ useCarousel این context را در اختیار می‌گذارد تا بتوانید کنترل سفارشی (نقطه‌های صفحه، شمارندهٔ اسلاید) بسازید.
CarouselContent همان ویوپورت overflow-hidden است و CarouselItem هر اسلاید.
پراپ opts مستقیم به useEmblaCarousel می‌رود، پس هر گزینهٔ Embla (loop، align، dragFree، startIndex و …) در دسترس است؛ setApi هم نمونهٔ api را برای کنترل بیرونی (مثل دکمهٔ Play/Pause) می‌دهد.
دسترس‌پذیری
- ریشهٔ Carousel با role="region" و aria-roledescription="carousel" مشخص می‌شود؛ هر CarouselItem هم role="group" و aria-roledescription="slide" دارد.
- کلید جهت‌نمای فیزیکی راست/چپ همیشه به سمت واقعی خودش حرکت می‌کند، نه به معنای منطقی «قبلی/بعدی»؛ یعنی در چیدمان rtl فلش چپ اسلاید بعدی را نشان می‌دهد، دقیقاً مثل رفتار slider.
- دکمه‌های CarouselPrevious و CarouselNext یک sr-only دارند («اسلاید قبلی» / «اسلاید بعدی»)؛ اگر آیکون یا متن دیگری جایگزین کردید همین برچسب را نگه دارید.
- وقتی اسلاید اول یا آخر نمایش داده می‌شود، دکمهٔ متناظر خودش disabled می‌شود؛ کاربر کیبورد به یک کنترل بی‌اثر نمی‌رسد.
- اگر پلاگین autoplay اضافه می‌کنید، حتماً یک دکمهٔ توقف/شروع در کنارش بگذارید؛ حرکت خودکار بدون کنترل برای کاربرانی که با صفحه‌خوان یا حساسیت حرکتی کار می‌کنند مشکل‌ساز است.
مرجع API
Carousel
| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| orientation | "horizontal" | "vertical" | "horizontal" | محور اسکرول و پیمایش کیبورد. |
| dir | "rtl" | "ltr" | "rtl" | جهت خواندن؛ روی direction موتور Embla و جای/آیکون دکمه‌های قبلی و بعدی اثر می‌گذارد. |
| opts | EmblaOptionsType | — | تنظیمات خام Embla (align، loop، dragFree، startIndex، containScroll و…). |
| plugins | EmblaPluginType[] | — | پلاگین‌های Embla، مثل Autoplay یا WheelGestures. |
| setApi | (api: CarouselApi) => void | — | دسترسی به نمونهٔ خام api برای کنترل بیرونی. |
CarouselItem
| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| className | string | — | برای عرض/ارتفاع هر اسلاید از basis-* استفاده کنید (مثلاً basis-1/2). |
CarouselPrevious / CarouselNext
| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| variant / size | ButtonProps | "outline" / "icon" | چون روی Button ساخته شده، همهٔ پراپ‌های آن را می‌پذیرد. |
useCarousel()
| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| api, scrollPrev, scrollNext | CarouselApi, () => void, () => void | — | برای ساخت کنترل سفارشی (نقطه‌های صفحه، شمارنده) داخل فرزندان Carousel. |
| canScrollPrev / canScrollNext | boolean | — | برای فعال/غیرفعال کردن دکمه‌های سفارشی. |
این کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
نمونه‌ها
Multiple Items
با basis-1/3 روی CarouselItem و opts.align="start"، سه اسلاید هم‌زمان دیده می‌شود.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
Vertical
orientation="vertical" محور اسکرول را عوض می‌کند؛ کلیدهای بالا/پایین به‌جای راست/چپ کار می‌کنند.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
LTR Content
برای محتوایی که خودش انگلیسی/لاتین است (مثلاً گالری بین‌المللی)، dir="ltr" هم چیدمان و هم جهت اسکرول Embla و کلیدها را عوض می‌کند.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
شمارندهٔ اسلاید با setApi
با useState و setApi می‌توانید اندیس اسلاید فعال را بیرون از کامپوننت بخوانید؛ همین الگو پایهٔ ساخت نقطه‌های صفحه (dots) هم هست.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
یک اسلاید (Empty/Edge)
دکمه‌های قبلی و بعدی را پنهان نکنید؛ خودِ Carousel وقتی حرکتی ممکن نیست آن‌ها را بی‌اثر می‌کند. حذف‌کردن، جای دکمه‌ها را در رفت‌وآمدهای بعدی جابه‌جا می‌کند.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
کدام نمونه برای کدام موقعیت
| نمونه | کجا به کار می‌آید |
|---|---|
| Multiple Items | با basis-1/3 روی CarouselItem و opts.align="start"، سه اسلاید هم‌زمان دیده می‌شود. |
| Vertical | orientation="vertical" محور اسکرول را عوض می‌کند؛ کلیدهای بالا/پایین به‌جای راست/چپ کار می‌کنند. |
| LTR Content | برای محتوایی که خودش انگلیسی/لاتین است (مثلاً گالری بین‌المللی)، dir="ltr" هم چیدمان و هم جهت اسکرول Embla و کلیدها را عوض می‌کند. |
| شمارندهٔ اسلاید با setApi | با useState و setApi می‌توانید اندیس اسلاید فعال را بیرون از کامپوننت بخوانید؛ همین الگو پایهٔ ساخت نقطه‌های صفحه (dots) هم هست. |
| یک اسلاید (Empty/Edge) | گالری‌ای که موقتاً فقط یک آیتم دارد |
دستورالعمل استفاده
دکمه‌های قبلی/بعدی همیشه در کنار اسلایدها
انجام بده
CarouselPrevious و CarouselNext را همیشه بگذارید تا کسی که نمی‌خواهد یا نمی‌تواند بکشد هم بتواند پیمایش کند.
انجام نده
چرخانده‌ای که فقط با کشیدن پیمایش می‌شود، روی دسکتاپ و برای کاربر کیبورد یا موتوری، بخشی از اسلایدها را کاملاً غیرقابل‌دسترس می‌کند.
عرض اسلاید را با basis مشخص کنید، نه اندازهٔ ثابت پیکسلی
انجام بده
با کلاس basis-1/2 یا basis-1/3 روی CarouselItem، تعداد آیتم دیده‌شده نسبت به عرض کانتینر تنظیم می‌شود و در صفحهٔ کوچک هم درست می‌شکند.
انجام نده
عرض ثابت پیکسلی روی خودِ کارت داخل اسلاید، محاسبهٔ اسنپ Embla را با basis پیش‌فرض (تمام‌عرض) هم‌خوان نمی‌کند و اسلایدها نامنظم می‌شوند.