پرتوپرتو

کاروسل (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

Prop

Type

پشتیبانی 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 استفاده کنید