آکاردئون (Accordion)

مجموعه‌ای عمودی از عناوین تعاملی که هر کدام با کلیک بخشی از محتوا را نمایش می‌دهند. با پشتیبانی کامل از RTL و الگوی دسترسی‌پذیر WAI-ARIA.

نصب (Installation)

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

نمونه‌ها (Examples)

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

آکاردئون ساده با یک آیتم باز در هر زمان. اولین آیتم به‌طور پیش‌فرض باز است.

بله. از الگوی طراحی WAI-ARIA پیروی می‌کند.

مشاهده کد

1import {
2  Accordion,
3  AccordionContent,
4  AccordionItem,
5  AccordionTrigger,
6} from "@/components/ui/accordion";
7
8export default function BasicAccordionExample() {
9  return (
10    <Accordion type="single" collapsible defaultValue="item-1">
11      <AccordionItem value="item-1">
12        <AccordionTrigger>آیا دسترسی‌پذیر است؟</AccordionTrigger>
13        <AccordionContent>
14          بله. از الگوی طراحی WAI-ARIA پیروی می‌کند.
15        </AccordionContent>
16      </AccordionItem>
17      <AccordionItem value="item-2">
18        <AccordionTrigger>چگونه رمز عبور را بازنشانی کنم؟</AccordionTrigger>
19        <AccordionContent>
20          روی «فراموشی رمز عبور» در صفحه ورود کلیک کنید، ایمیل خود را وارد کنید؛
21          لینک بازنشانی را برایتان می‌فرستیم. لینک پس از ۲۴ ساعت منقضی می‌شود.
22        </AccordionContent>
23      </AccordionItem>
24      <AccordionItem value="item-3">
25        <AccordionTrigger>آیا می‌توانم طرح اشتراک را عوض کنم؟</AccordionTrigger>
26        <AccordionContent>
27          بله. از بخش صورتحساب در تنظیمات حساب می‌توانید طرح را تغییر دهید.
28        </AccordionContent>
29      </AccordionItem>
30    </Accordion>
31  );
32}
33

چند آیتم باز (Multiple)

با type="multiple" چند آیتم می‌توانند هم‌زمان باز باشند.

مشاهده کد

1import {
2  Accordion,
3  AccordionContent,
4  AccordionItem,
5  AccordionTrigger,
6} from "@/components/ui/accordion";
7
8export default function MultipleAccordionExample() {
9  return (
10    <Accordion type="multiple" className="w-full">
11      <AccordionItem value="notifications">
12        <AccordionTrigger>تنظیمات اعلان</AccordionTrigger>
13        <AccordionContent>
14          نحوه دریافت اعلان‌ها را مدیریت کنید. می‌توانید اعلان ایمیل برای
15          به‌روزرسانی‌ها یا اعلان push برای دستگاه همراه را فعال کنید.
16        </AccordionContent>
17      </AccordionItem>
18      <AccordionItem value="privacy">
19        <AccordionTrigger>حریم خصوصی و امنیت</AccordionTrigger>
20        <AccordionContent>
21          تنظیمات حریم خصوصی و امنیت حساب شما.
22        </AccordionContent>
23      </AccordionItem>
24      <AccordionItem value="billing">
25        <AccordionTrigger>صورتحساب و اشتراک</AccordionTrigger>
26        <AccordionContent>
27          مدیریت روش پرداخت و طرح اشتراک شما.
28        </AccordionContent>
29      </AccordionItem>
30    </Accordion>
31  );
32}
33

آیتم غیرفعال (Disabled)

با پراپ disabled روی AccordionItem می‌توان یک آیتم را غیرفعال کرد.

مشاهده کد

1import {
2  Accordion,
3  AccordionContent,
4  AccordionItem,
5  AccordionTrigger,
6} from "@/components/ui/accordion";
7
8export default function DisabledAccordionExample() {
9  return (
10    <Accordion type="single" collapsible className="w-full">
11      <AccordionItem value="item-1">
12        <AccordionTrigger>آیا به تاریخچه حساب دسترسی دارم؟</AccordionTrigger>
13        <AccordionContent>
14          بله. از بخش تنظیمات می‌توانید تاریخچه را مشاهده کنید.
15        </AccordionContent>
16      </AccordionItem>
17      <AccordionItem value="item-2" disabled>
18        <AccordionTrigger>اطلاعات ویژگی پریمیوم</AccordionTrigger>
19        <AccordionContent>
20          این آیتم غیرفعال است و فقط برای نمایش است.
21        </AccordionContent>
22      </AccordionItem>
23      <AccordionItem value="item-3">
24        <AccordionTrigger>چگونه ایمیل خود را به‌روز کنم؟</AccordionTrigger>
25        <AccordionContent>
26          از بخش پروفایل در تنظیمات حساب، آدرس ایمیل را ویرایش کنید.
27        </AccordionContent>
28      </AccordionItem>
29    </Accordion>
30  );
31}
32

مرجع API (API Reference)

Accordion

کامپوننت ریشه که وضعیت باز/بسته آیتم‌ها را مدیریت می‌کند.

پراپ (Prop)	نوع (Type)	پیش‌فرض (Default)	توضیحات (Description)
`type`	`"single" \| "multiple"`	`"single"`	نوع آکاردئون: فقط یک آیتم باز (single) یا چند آیتم هم‌زمان (multiple).
`collapsible`	`boolean`	`false`	در حالت single، آیا کلیک روی آیتم باز شده آن را می‌بندد یا خیر.
`value`	`string \| string[]`	`undefined`	مقدار کنترل‌شده آیتم(های) باز.
`defaultValue`	`string \| string[]`	`undefined`	مقدار پیش‌فرض آیتم(های) باز (غیرکنترل‌شده).
`onValueChange`	`(value: string \| string[]) => void`	`undefined`	تابع فراخوانی هنگام تغییر آیتم(های) باز.
`className`	`string`	`-`	کلاس‌های CSS سفارشی برای روت آکاردئون.

AccordionItem

هر بخش قابل باز/بسته در آکاردئون.

پراپ (Prop)	نوع (Type)	پیش‌فرض (Default)	توضیحات (Description)
`value`	`string`	`-`	شناسه یکتای آیتم برای کنترل باز/بسته.
`disabled`	`boolean`	`false`	غیرفعال کردن این آیتم و جلوگیری از باز/بسته شدن.
`className`	`string`	`-`	کلاس‌های CSS سفارشی برای آیتم.

AccordionTrigger

دکمه‌ای که با کلیک آن محتوا باز یا بسته می‌شود.

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

AccordionContent

محتوای قابل جمع شدن که زیر تریگر نمایش داده می‌شود.

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

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

الگوی WAI-ARIA

آکاردئون از الگوی طراحی WAI-ARIA برای آکاردئون پیروی می‌کند: نقش‌های مناسب، وضعیت expanded/collapsed و ارتباط تریگر با محتوا برای خوانندگان صفحه و کیبورد.

کیبورد

Tab — حرکت بین تریگرها.
Enter و Space — باز یا بسته کردن آیتم فوکوس‌شده.
ArrowDown / ArrowUp — حرکت به تریگر بعدی/قبلی.
Home / End — رفتن به اولین یا آخرین تریگر.

پشتیبانی RTL

از text-start و ms-2 برای چیدمان و فاصله آیکون استفاده شده تا در جهت راست‌به‌چپ درست نمایش داده شود.

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

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

سوالات متداول (FAQ) و محتوای قابل جمع‌شدن.
لیست آیتم‌هایی که هر کدام توضیح یا جزئیات بیشتری دارند.
تنظیمات یا بخش‌های طولانی که نمی‌خواهید همه را یک‌جا نشان دهید.

single در مقابل multiple

برای FAQ معمولاً type="single" و collapsible مناسب است. برای مقایسه چند بخش یا مرور سریع، type="multiple" مفید است.

عنوان تریگر

عناوین را کوتاه و واضح نگه دارید تا کاربر قبل از باز کردن بداند محتوا درباره چیست.

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

1import {
2  Accordion,
3  AccordionContent,
4  AccordionItem,
5  AccordionTrigger,
6} from "@/components/ui/accordion";
7
8export default function MyAccordion() {
9  return (
10    <Accordion type="single" collapsible defaultValue="item-1">
11      <AccordionItem value="item-1">
12        <AccordionTrigger>عنوان اول</AccordionTrigger>
13        <AccordionContent>
14          محتوای بخش اول.
15        </AccordionContent>
16      </AccordionItem>
17      <AccordionItem value="item-2">
18        <AccordionTrigger>عنوان دوم</AccordionTrigger>
19        <AccordionContent>
20          محتوای بخش دوم.
21        </AccordionContent>
22      </AccordionItem>
23    </Accordion>
24  );
25}
26

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

آکاردئون داخل کارت (Accordion in Card)

قرار دادن آکاردئون درون کارت برای بخش‌بندی و ظاهر منظم (مثلاً FAQ یا تنظیمات).

اشتراک و صورتحساب

سوالات متداول درباره حساب، طرح‌ها، پرداخت و لغو اشتراک.

مشاهده کد

1import {
2  Accordion,
3  AccordionContent,
4  AccordionItem,
5  AccordionTrigger,
6} from "@/components/ui/accordion";
7import { Card, CardContent, CardHeader, CardTitle, CardDescription } from "@/components/ui/card";
8
9export default function AccordionInCardExample() {
10  return (
11    <Card>
12      <CardHeader>
13        <CardTitle>اشتراک و صورتحساب</CardTitle>
14        <CardDescription>
15          سوالات متداول درباره حساب، طرح‌ها، پرداخت و لغو اشتراک.
16        </CardDescription>
17      </CardHeader>
18      <CardContent>
19        <Accordion type="single" collapsible className="w-full">
20          <AccordionItem value="plans">
21            <AccordionTrigger>چه طرح‌های اشتراکی دارید؟</AccordionTrigger>
22            <AccordionContent>
23              سه سطح: استارتر (۹ دلار/ماه)، حرفه‌ای (۲۹ دلار/ماه) و سازمانی
24              (۹۹ دلار/ماه). هر طرح ذخیره، دسترسی API و پشتیبانی بیشتری دارد.
25            </AccordionContent>
26          </AccordionItem>
27          <AccordionItem value="billing">
28            <AccordionTrigger>صورتحساب چگونه کار می‌کند؟</AccordionTrigger>
29            <AccordionContent>
30              صورتحساب در ابتدای هر دوره شارژ می‌شود و هر زمان می‌توانید لغو
31              کنید. پشتیبانی ۲۴/۷ و اعضای نامحدود تیم در همه طرح‌ها هست.
32            </AccordionContent>
33          </AccordionItem>
34          <AccordionItem value="cancel">
35            <AccordionTrigger>چگونه اشتراک را لغو کنم؟</AccordionTrigger>
36            <AccordionContent>
37              از بخش صورتحساب در تنظیمات، گزینه «لغو اشتراک» را انتخاب کنید.
38            </AccordionContent>
39          </AccordionItem>
40        </Accordion>
41      </CardContent>
42    </Card>
43  );
44}
45