کاروسل (Carousel)

کاروسل با انیمیشن و سوایپ ساخته‌شده با کتابخانه Embla. پشتیبانی کامل از RTL و زبان فارسی.

نصب (Installation)

1npx @quark-lab/rad-ui add carousel

نمونه‌ها (Examples)

نمونه پایه (Basic)

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

مشاهده کد

1import {
2  Carousel,
3  CarouselContent,
4  CarouselItem,
5  CarouselNext,
6  CarouselPrevious,
7} from "@/components/ui/carousel";
8import { Card, CardContent } from "@/components/ui/card";
9
10export default function BasicCarouselExample() {
11  return (
12    <Carousel className="w-full max-w-xs">
13      <CarouselContent>
14        <CarouselItem>
15          <Card>
16            <CardContent className="flex aspect-square items-center justify-center p-6">
17              <span className="text-4xl font-semibold">۱</span>
18            </CardContent>
19          </Card>
20        </CarouselItem>
21        <CarouselItem>
22          <Card>
23            <CardContent className="flex aspect-square items-center justify-center p-6">
24              <span className="text-4xl font-semibold">۲</span>
25            </CardContent>
26          </Card>
27        </CarouselItem>
28        <CarouselItem>
29          <Card>
30            <CardContent className="flex aspect-square items-center justify-center p-6">
31              <span className="text-4xl font-semibold">۳</span>
32            </CardContent>
33          </Card>
34        </CarouselItem>
35        <CarouselItem>
36          <Card>
37            <CardContent className="flex aspect-square items-center justify-center p-6">
38              <span className="text-4xl font-semibold">۴</span>
39            </CardContent>
40          </Card>
41        </CarouselItem>
42        <CarouselItem>
43          <Card>
44            <CardContent className="flex aspect-square items-center justify-center p-6">
45              <span className="text-4xl font-semibold">۵</span>
46            </CardContent>
47          </Card>
48        </CarouselItem>
49      </CarouselContent>
50      <CarouselPrevious />
51      <CarouselNext />
52    </Carousel>
53  );
54}
55

اندازه اسلایدها (Sizes)

استفاده از basis-1/3 برای نمایش سه اسلاید هم‌زمان.

مشاهده کد

1import {
2  Carousel,
3  CarouselContent,
4  CarouselItem,
5  CarouselNext,
6  CarouselPrevious,
7} from "@/components/ui/carousel";
8import { Card, CardContent } from "@/components/ui/card";
9
10export default function SizesCarouselExample() {
11  return (
12    <Carousel className="w-full max-w-sm">
13      <CarouselContent>
14        <CarouselItem className="basis-1/3">
15          <Card>
16            <CardContent className="flex aspect-square items-center justify-center p-6">
17              <span className="text-4xl font-semibold">۱</span>
18            </CardContent>
19          </Card>
20        </CarouselItem>
21        <CarouselItem className="basis-1/3">
22          <Card>
23            <CardContent className="flex aspect-square items-center justify-center p-6">
24              <span className="text-4xl font-semibold">۲</span>
25            </CardContent>
26          </Card>
27        </CarouselItem>
28        <CarouselItem className="basis-1/3">
29          <Card>
30            <CardContent className="flex aspect-square items-center justify-center p-6">
31              <span className="text-4xl font-semibold">۳</span>
32            </CardContent>
33          </Card>
34        </CarouselItem>
35        <CarouselItem className="basis-1/3">
36          <Card>
37            <CardContent className="flex aspect-square items-center justify-center p-6">
38              <span className="text-4xl font-semibold">۴</span>
39            </CardContent>
40          </Card>
41        </CarouselItem>
42        <CarouselItem className="basis-1/3">
43          <Card>
44            <CardContent className="flex aspect-square items-center justify-center p-6">
45              <span className="text-4xl font-semibold">۵</span>
46            </CardContent>
47          </Card>
48        </CarouselItem>
49      </CarouselContent>
50      <CarouselPrevious />
51      <CarouselNext />
52    </Carousel>
53  );
54}
55

مرجع API (API Reference)

Carousel

کامپوننت ریشه که کاروسل را مدیریت می‌کند.

پراپ (Prop)	نوع (Type)	پیش‌فرض (Default)	توضیحات (Description)
`opts`	`EmblaOptionsType`	`undefined`	گزینه‌های Embla Carousel (مثل align، loop، و غیره). مستندات Embla را ببینید.
`plugins`	`EmblaPluginType[]`	`undefined`	پلاگین‌های Embla (مثل Autoplay).
`orientation`	`"horizontal" \| "vertical"`	`"horizontal"`	جهت کاروسل: افقی یا عمودی.
`dir`	`"ltr" \| "rtl"`	`"rtl"`	جهت متن. پیش‌فرض RTL برای پشتیبانی از زبان فارسی.
`setApi`	`(api: CarouselApi) => void`	`undefined`	تابع فراخوانی‌شده با نمونه API کاروسل برای کنترل برنامه‌ای.
`className`	`string`	`undefined`	کلاس‌های CSS سفارشی.

CarouselContent

کانتینر اسکرول‌پذیر که اسلایدها را در بر می‌گیرد.

پراپ (Prop)	نوع (Type)	پیش‌فرض (Default)	توضیحات (Description)
`className`	`string`	`undefined`	کلاس‌های CSS سفارشی برای کانتینر اسکرول.

CarouselItem

هر اسلاید در کاروسل.

پراپ (Prop)	نوع (Type)	پیش‌فرض (Default)	توضیحات (Description)
`className`	`string`	`undefined`	کلاس‌های CSS سفارشی. از basis-1/3 برای نمایش چند اسلاید استفاده کنید.

دسترسی‌پذیری (Accessibility)

نقش‌های ARIA

هر CarouselItem دارای role="group" و aria-roledescription="slide" است. دکمه‌های قبلی/بعدی دارای متن جایگزین برای خوانندگان صفحه هستند.

پشتیبانی RTL

کاروسل به‌طور پیش‌فرض با dir="rtl" کار می‌کند. آیکون‌های ناوبری با rtl:rotate-180 در جهت صحیح نمایش داده می‌شوند.

بهترین شیوه‌ها (Best Practices)

چه زمانی از کاروسل استفاده کنیم؟

گالری تصاویر و محصولات.
بنرهای تبلیغاتی و هیرو اسکشن.
تستیمونیال‌ها و نظرات کاربران.
نمایش کارت‌ها یا آیتم‌ها در فضای محدود.

گزینه opts

برای حلقه بی‌نهایت از opts={{ loop: true }} استفاده کنید. مستندات کامل Embla Carousel را برای گزینه‌های بیشتر ببینید.

نحوه استفاده (Usage)

1import {
2  Carousel,
3  CarouselContent,
4  CarouselItem,
5  CarouselNext,
6  CarouselPrevious,
7} from "@/components/ui/carousel";
8import { Card, CardContent } from "@/components/ui/card";
9
10export default function MyCarousel() {
11  return (
12    <Carousel>
13      <CarouselContent>
14        <CarouselItem>
15          <Card>
16            <CardContent className="flex aspect-square items-center justify-center p-6">
17              <span className="text-4xl font-semibold">۱</span>
18            </CardContent>
19          </Card>
20        </CarouselItem>
21        <CarouselItem>
22          <Card>
23            <CardContent className="flex aspect-square items-center justify-center p-6">
24              <span className="text-4xl font-semibold">۲</span>
25            </CardContent>
26          </Card>
27        </CarouselItem>
28        <CarouselItem>
29          <Card>
30            <CardContent className="flex aspect-square items-center justify-center p-6">
31              <span className="text-4xl font-semibold">۳</span>
32            </CardContent>
33          </Card>
34        </CarouselItem>
35      </CarouselContent>
36      <CarouselPrevious />
37      <CarouselNext />
38    </Carousel>
39  );
40}
41

مثال‌های پیشرفته (Advanced Examples)

دسترسی به API (API Access)

استفاده از setApi برای کنترل کاروسل به‌صورت برنامه‌ای و نمایش شماره اسلاید فعلی.

نمونه زنده در بخش API Reference قابل مشاهده است.

مشاهده کد

1import * as React from "react";
2import {
3  Carousel,
4  CarouselContent,
5  CarouselItem,
6  CarouselNext,
7  CarouselPrevious,
8} from "@/components/ui/carousel";
9import { type CarouselApi } from "@/components/ui/carousel";
10
11export default function ApiExample() {
12  const [api, setApi] = React.useState<CarouselApi>();
13  const [current, setCurrent] = React.useState(0);
14
15  React.useEffect(() => {
16    if (!api) return;
17    setCurrent(api.selectedScrollSnap() + 1);
18    api.on("select", () => {
19      setCurrent(api.selectedScrollSnap() + 1);
20    });
21  }, [api]);
22
23  return (
24    <div>
25      <Carousel setApi={setApi}>
26        <CarouselContent>
27          <CarouselItem>...</CarouselItem>
28        </CarouselContent>
29        <CarouselPrevious />
30        <CarouselNext />
31      </Carousel>
32      <p className="text-sm text-muted-foreground mt-2">
33        اسلاید {current} از ...
34      </p>
35    </div>
36  );
37}