پرتوپرتو

کاروسل (Carousel)

یک کامپوننت کاروسل برای نمایش محتوا به صورت اسلایدی

معرفی

کامپوننت Carousel برای نمایش مجموعه‌ای از محتوا به صورت اسلایدی استفاده می‌شود. این کامپوننت از Embla 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

ویژگی‌ها

  • اسلایدشو خودکار
  • حلقه بی‌نهایت
  • لمس و کشیدن (Drag)
  • پشتیبانی از کیبورد
  • پشتیبانی کامل از RTL

پشتیبانی RTL

کامپوننت Carousel به‌صورت کامل از RTL پشتیبانی می‌کند:

تشخیص خودکار جهت

کاروسل به‌صورت خودکار جهت صفحه (dir attribute روی html) را تشخیص داده و متناسب با آن عمل می‌کند.

دکمه‌های ناوبری

  • در RTL، دکمه Previous در سمت راست با آیکون فلش راست (→) قرار می‌گیرد
  • در RTL، دکمه Next در سمت چپ با آیکون فلش چپ (←) قرار می‌گیرد

پیمایش کیبورد

  • کلید ArrowRight در RTL به اسلاید قبلی می‌رود
  • کلید ArrowLeft در RTL به اسلاید بعدی می‌رود

انیمیشن‌ها

تمام انیمیشن‌های اسلاید در RTL به‌درستی معکوس می‌شوند.

دسترسی‌پذیری

  • از role="region" و aria-roledescription="carousel" استفاده می‌شود
  • هر اسلاید دارای role="group" و aria-roledescription="slide" است
  • دکمه‌های ناوبری دارای aria-label توصیفی هستند
  • پشتیبانی کامل از پیمایش با کیبورد