کاروسل (Carousel)
یک کامپوننت کاروسل برای نمایش محتوا به صورت اسلایدی
معرفی
کامپوننت Carousel برای نمایش مجموعهای از محتوا به صورت اسلایدی استفاده میشود. این کامپوننت از Embla Carousel استفاده میکند.
چه زمانی استفاده کنیم:
- برای نمایش محتوای بصری (تصاویر، کارتها) که در فضای موجود جا نمیشوند
- وقتی کاربر باید بین آیتمها بچرخد (پروفایلها، پستها)
- برای نمایش اسلایدی محتوا با ناوبری افقی یا عمودی
چه زمانی استفاده نکنیم:
- برای مقایسه آیتمها در کنار هم — از
gridاستفاده کنید - وقتی تعداد آیتمها کم است و همه جا میشوند — از grid استفاده کنید
- برای محتوای دادهمحور — Carousel برای محتوای بصری مناسبتر است
استفاده
۱
۲
۳
import { Carousel, CarouselContent, CarouselItem, CarouselNext, CarouselPrevious } from '@parto-system-design/ui'
export default function MyComponent() {
return (
<Carousel>
<CarouselContent>
<CarouselItem>اسلاید 1</CarouselItem>
<CarouselItem>اسلاید 2</CarouselItem>
<CarouselItem>اسلاید 3</CarouselItem>
</CarouselContent>
<CarouselPrevious />
<CarouselNext />
</Carousel>
)
}اندازهبندی
نمایش چند آیتم
<Carousel
opts={{
align: 'start',
}}
className="w-full max-w-sm"
>
<CarouselContent>
{Array.from({ length: 5 }).map((_, index) => (
<CarouselItem key={index} className="md:basis-1/2 lg:basis-1/3">
<div className="p-1">کارت {index + 1}</div>
</CarouselItem>
))}
</CarouselContent>
<CarouselPrevious />
<CarouselNext />
</Carousel>جهت عمودی
<Carousel orientation="vertical" className="w-full max-w-xs">
<CarouselContent className="-mt-1 h-[200px]">
{Array.from({ length: 5 }).map((_, index) => (
<CarouselItem key={index} className="pt-1 md:basis-1/2">
<div className="p-1">کارت {index + 1}</div>
</CarouselItem>
))}
</CarouselContent>
<CarouselPrevious />
<CarouselNext />
</Carousel>تنظیم جهت (Direction)
کاروسل بهصورت خودکار جهت صفحه را تشخیص میدهد. اما میتوانید جهت را بهصورت دستی تنظیم کنید:
// استفاده از جهت صفحه (پیشفرض)
<Carousel>...</Carousel>
// تنظیم دستی جهت
<Carousel dir="rtl">...</Carousel>
<Carousel dir="ltr">...</Carousel>API دسترسی
import { useCarousel } from '@parto-system-design/ui'
const { api, direction } = useCarousel()
// دسترسی به متدهای کاروسل
api?.scrollNext()
api?.scrollPrev()
api?.scrollTo(index)
// دسترسی به جهت فعلی
console.log(direction) // 'rtl' یا 'ltr'Props
Carousel
پشتیبانی RTL
کامپوننت Carousel بهصورت کامل از RTL پشتیبانی میکند:
تشخیص خودکار جهت
کاروسل بهصورت خودکار جهت صفحه (dir attribute روی html) را تشخیص داده و متناسب با آن عمل میکند.
دکمههای ناوبری
- در RTL، دکمه Previous در سمت راست با آیکون فلش راست (→) قرار میگیرد
- در RTL، دکمه Next در سمت چپ با آیکون فلش چپ (←) قرار میگیرد
پیمایش کیبورد
- کلید ArrowRight در RTL به اسلاید قبلی میرود
- کلید ArrowLeft در RTL به اسلاید بعدی میرود
انیمیشنها
تمام انیمیشنهای اسلاید در RTL بهدرستی معکوس میشوند.
راهنمای استفاده
بکنید
- همیشه
CarouselPreviousوCarouselNextرا اضافه کنید تا کاربر بتواند ناوبری کند - ازbasis-1/3یا مشابه برای نمایش چند آیتم در یک نما استفاده کنید -dirرا برای محیطهای RTL صریح مشخص کنید
نکنید
- از Carousel برای محتوای دادهمحور (جداول، فرمها) استفاده نکنید — Carousel برای محتوای بصری مناسب است - تعداد آیتمها را بیش از حد زیاد نکنید — عملکرد کاهش مییابد - وقتی همه آیتمها در فضای موجود جا میشوند از Carousel استفاده نکنید — از grid استفاده کنید
دسترسیپذیری
- از
role="region"وaria-roledescription="carousel"استفاده میشود - هر اسلاید دارای
role="group"وaria-roledescription="slide"است - دکمههای ناوبری دارای
aria-labelتوصیفی هستند - پشتیبانی کامل از پیمایش با کیبورد
کامپوننتهای مرتبط
- ScrollArea — اگر فقط اسکرول افقی ساده بدون ناوبری اسلایدی نیاز دارید، از ScrollArea استفاده کنید