Accordionv1.0.0
فهرستی از بخش‌های تاشو که هر کدام با کلیک یا صفحه‌کلید باز و بسته می‌شوند؛ برای پرسش‌های متداول، تنظیمات پیشرفته و هر محتوای بلندی که نباید یک‌جا دیده شود.
این کامپوننت فعلاً برای ۱ فریم‌ورک از ۴ فریم‌ورک آماده است.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
نصب
با CLI اختصاصی digdesign کامپوننت را از رجیستری دیگ نصب کنید؛ وابستگی‌ها و فایل‌ها خودکار اضافه می‌شوند.
npx digdesign@latest add https://docs.digdesign.ir/r/accordion.jsonpnpm dlx digdesign@latest add https://docs.digdesign.ir/r/accordion.jsonyarn dlx digdesign@latest add https://docs.digdesign.ir/r/accordion.jsonbunx --bun digdesign@latest add https://docs.digdesign.ir/r/accordion.jsonاین کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
استفاده
import {
Accordion,
AccordionContent,
AccordionItem,
AccordionTrigger,
} from "@/components/ui/accordion"
<Accordion type="single" collapsible>
<AccordionItem value="item-1">
<AccordionTrigger>عنوان بخش</AccordionTrigger>
<AccordionContent>محتوای بخش.</AccordionContent>
</AccordionItem>
</Accordion>این کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
ترکیب اجزا
Accordion ریشه است و با پراپی به نام type تعیین می‌کند تک‌بازشو باشد یا چندبازشو؛ variant، compact، hideIndicator، disableAnimation، showDivider و keepContentMounted هم اینجا برای کل مجموعه ست می‌شوند و از راه Context به هر AccordionItem می‌رسند.
هر AccordionItem یک value یکتا می‌گیرد و می‌تواند هرکدام از این حالت‌ها را فقط برای خودش override کند.
AccordionTrigger خودش داخل یک h3 رندر می‌شود تا ساختار عنوان درست بماند، و AccordionContent محتوا را داخل یک div داخلی می‌گذارد؛ برای همین padding را باید روی AccordionContent بدهید نه روی خود محتوا، چون انیمیشن ارتفاع روی عنصر بیرونی اجرا می‌شود و padding روی آن، پرش ایجاد می‌کند.
دسترس‌پذیری
- هر عنوان یک دکمهٔ واقعی داخل هدر است؛ Space و Enter بخش را باز و بسته می‌کنند.
- کلیدهای بالا و پایین بین عنوان‌ها حرکت می‌کنند و Home و End به اولین و آخرین بخش می‌روند؛ جهت افقی نیازی به تنظیم RTL ندارد چون ناوبری عمودی است.
- aria-expanded و aria-controls خودکار ست می‌شوند و وقتی keepContentMounted نیست، محتوای بسته اصلاً در DOM نمی‌ماند.
- اگر آکاردئون در صفحه‌ای است که باید در آن جستجوی مرورگر (Ctrl+F) کار کند، به‌جای آکاردئون از محتوای همیشه‌باز استفاده کنید؛ keepContentMounted فقط محتوا را در DOM نگه می‌دارد (مثلاً برای حفظ مقدار یک فرم)، نه اینکه متنِ بسته را برای Ctrl+F قابل‌جست‌وجو کند.
مرجع API
Accordion
ریشهٔ آکاردئون؛ نوع رفتار، مقدار باز و ظاهر کل مجموعه اینجا تعیین می‌شود. مقادیر variant تا keepContentMounted پیش‌فرضِ همهٔ AccordionItemها هستند و هرکدام قابل override در سطح آیتم‌اند.
| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| type | "single" | "multiple" | — | الزامی. single یعنی هر بار فقط یک بخش باز است، multiple یعنی چند بخش هم‌زمان. |
| collapsible | boolean | false | فقط در حالت single؛ اجازه می‌دهد بخشِ باز با کلیک دوباره بسته شود. |
| value / onValueChange | string | string[] / (value) => void | — | کنترل‌شده. در حالت multiple نوع مقدار آرایهٔ رشته است. |
| defaultValue | string | string[] | — | بخش‌های بازِ اولیه در حالت کنترل‌نشده. |
| variant | "light" | "shadow" | "bordered" | "splitted" | "soft" | light | ظاهر کلی مجموعه: light بدون قاب، shadow با سایه، bordered با حاشیه، splitted هر بخش یک کارت جدا، soft بی‌خط با زمینهٔ ملایم برای بخش باز. |
| indicator | "chevron" | "plus" | chevron | نشانگر باز و بسته: فلشی که می‌چرخد، یا به‌علاوه در دایره که منها می‌شود. |
| showDivider | boolean | true | خط جداکننده زیر هر بخش؛ در variant=splitted همیشه نادیده گرفته می‌شود چون هر بخش خودش کارت جداست. |
| compact | boolean | false | فاصله و اندازهٔ متن همهٔ بخش‌ها را کوچک‌تر می‌کند. |
| disabled | boolean | false | کل آکاردئون را غیرفعال می‌کند؛ AccordionItem با disabled خودش می‌تواند این را override کند. |
| hideIndicator | boolean | false | فلش باز/بسته را برای همهٔ بخش‌ها مخفی می‌کند. |
| disableAnimation | boolean | false | انیمیشن ارتفاع باز/بسته‌شدن را حذف می‌کند؛ تغییر حالت آنی است. |
| keepContentMounted | boolean | false | محتوای بسته را هم در DOM نگه می‌دارد (مثلاً برای حفظ مقدار یک فرم داخل بخش)؛ جای‌گزین جست‌وجوی مرورگر نیست. |
AccordionItem
variant و showDivider همیشه از ریشه می‌آیند؛ بقیهٔ prop های زیر می‌توانند مقدار ریشه را فقط برای همین بخش override کنند.
| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| value | string | — | الزامی و یکتا؛ شناسهٔ این بخش برای باز و بسته شدن. |
| disabled | boolean | — | این بخش را از تعامل و ناوبری صفحه‌کلید خارج می‌کند. نبودش یعنی از disabled ریشه پیروی کند. |
| compact | boolean | — | override فشرده‌بودن فقط برای همین بخش. |
| hideIndicator | boolean | — | override مخفی‌بودن فلش فقط برای همین بخش. |
| disableAnimation | boolean | — | override بی‌انیمیشن‌بودن فقط برای همین بخش. |
| keepContentMounted | boolean | — | override نگه‌داشتن محتوا در DOM فقط برای همین بخش. |
AccordionTrigger
| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| children | React.ReactNode | — | عنوان بخش. فلش خودکار بعد از محتوا اضافه می‌شود و هنگام باز شدن ۱۸۰ درجه می‌چرخد. |
| className | string | — | با cn ادغام می‌شود و بر کلاس‌های پایه اولویت دارد. |
AccordionContent
| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| className | string | — | روی div داخلی می‌نشیند، نه روی عنصر انیمیشن‌دار؛ پس padding را بی‌خطر می‌توانید عوض کنید. |
این کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
نمونه‌ها
Variants
محور variant پنج ظاهر دارد: light (پیش‌فرض، فقط خط جداکننده)، shadow (سایه‌دار)، bordered (قاب‌دار)، splitted (هر بخش یک کارت جدا با فاصله) و soft (بی‌خط؛ فقط بخش باز زمینهٔ ملایم می‌گیرد).
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
نشانگر به‌علاوه (indicator="plus")
به‌جای فلش، یک به‌علاوه در دایره که با باز شدن منها می‌شود؛ با variant="soft" پرسش باز در فهرست بلند پیدا است.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
Compact
compact فاصله و اندازهٔ متن هر بخش را کوچک‌تر می‌کند؛ برای فهرست‌های بلند یا پنل‌های کناری مناسب است.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
Subtitle
AccordionTrigger یک flex است؛ برای زیرنویسِ زیر عنوان کافی است داخلش یک ستون بگذارید، نیازی به prop جدا نیست.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
Hide Indicator
hideIndicator فلش را حذف می‌کند؛ برای طراحی‌هایی که خودشان نشانهٔ باز/بسته دارند (مثل تغییر رنگ پس‌زمینه).
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
Disable Animation
disableAnimation انیمیشن ارتفاع را حذف می‌کند و باز/بسته‌شدن آنی می‌شود؛ برای کاربرانی که reduce-motion می‌خواهند یا صرفاً کارایی بالاتر.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
Disabled Accordion
disabled روی خودِ Accordion همهٔ بخش‌ها را با هم غیرفعال می‌کند؛ برای غیرفعال‌سازی فقط یک بخش از disabled روی همان AccordionItem استفاده کنید (مثال بعدی).
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
Multiple
با type="multiple" هر تعداد بخش می‌تواند هم‌زمان باز بماند و defaultValue آرایه می‌گیرد.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
With Icon and Badge
AccordionTrigger یک flex است؛ هر چیزی داخلش بگذارید سمت شروع می‌نشیند و فلش سمت پایان می‌ماند.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
Disabled Item
disabled را روی AccordionItem بگذارید تا آن بخش نه با ماوس باز شود و نه با صفحه‌کلید فوکوس بگیرد.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
Inside a Card
کلاس‌های خودتان روی هر جزء با cn ادغام می‌شوند؛ اینجا حاشیه و padding به آکاردئون شکل کارت داده است.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
آیتم غیرفعال (Disabled)
آیتم را حذف نکنید. دیدنش به کاربر می‌گوید این قابلیت وجود دارد و چرا الان بسته است؛ حذف‌کردن، همان اطلاعات را پنهان می‌کند.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
در حال دریافت (Loading)
آکاردئون برای همین ساخته شده: محتوا را تا لحظهٔ نیاز نگیرید. ولی بعد از باز شدن، جای خالی نشان دهید نه فضای خالی، وگرنه کاربر فکر می‌کند بخش خالی است.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
عنوان بلند (Overflow)
عنوان می‌شکند و آیکون جهت سر جایش می‌ماند، چون تریگر یک flex است. عنوان بلندتر از دو سطر یعنی احتمالاً باید به چند آیتم شکسته شود.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
کدام نمونه برای کدام موقعیت
| نمونه | کجا به کار می‌آید |
|---|---|
| Variants | محور variant پنج ظاهر دارد: light (پیش‌فرض، فقط خط جداکننده)، shadow (سایه‌دار)، bordered (قاب‌دار)، splitted (هر بخش یک کارت جدا با فاصله) و soft (بی‌خط؛ فقط بخش باز زمینهٔ ملایم می‌گیرد). |
| نشانگر به‌علاوه (indicator="plus") | صفحهٔ پرسش‌های متداول |
| Compact | compact فاصله و اندازهٔ متن هر بخش را کوچک‌تر می‌کند؛ برای فهرست‌های بلند یا پنل‌های کناری مناسب است. |
| Subtitle | AccordionTrigger یک flex است؛ برای زیرنویسِ زیر عنوان کافی است داخلش یک ستون بگذارید، نیازی به prop جدا نیست. |
| Hide Indicator | hideIndicator فلش را حذف می‌کند؛ برای طراحی‌هایی که خودشان نشانهٔ باز/بسته دارند (مثل تغییر رنگ پس‌زمینه). |
| Disable Animation | disableAnimation انیمیشن ارتفاع را حذف می‌کند و باز/بسته‌شدن آنی می‌شود؛ برای کاربرانی که reduce-motion می‌خواهند یا صرفاً کارایی بالاتر. |
| Disabled Accordion | disabled روی خودِ Accordion همهٔ بخش‌ها را با هم غیرفعال می‌کند؛ برای غیرفعال‌سازی فقط یک بخش از disabled روی همان AccordionItem استفاده کنید (مثال بعدی). |
| Multiple | با type="multiple" هر تعداد بخش می‌تواند هم‌زمان باز بماند و defaultValue آرایه می‌گیرد. |
| With Icon and Badge | AccordionTrigger یک flex است؛ هر چیزی داخلش بگذارید سمت شروع می‌نشیند و فلش سمت پایان می‌ماند. |
| Disabled Item | disabled را روی AccordionItem بگذارید تا آن بخش نه با ماوس باز شود و نه با صفحه‌کلید فوکوس بگیرد. |
| Inside a Card | کلاس‌های خودتان روی هر جزء با cn ادغام می‌شوند؛ اینجا حاشیه و padding به آکاردئون شکل کارت داده است. |
| آیتم غیرفعال (Disabled) | بخشی که در طرح فعلی کاربر در دسترس نیست |
| در حال دریافت (Loading) | بخشی که محتوایش فقط موقع باز شدن گرفته می‌شود |
| عنوان بلند (Overflow) | بندهای شرایط و ضوابط |
دستورالعمل استفاده
عنوان‌های واضح، نه مبهم
انجام بده
عنوان هر بخش باید بدون باز کردن هم قابل‌حدس باشد؛ یک سوال یا جملهٔ کامل بهترین انتخاب است.
انجام نده
عنوانی مثل «بیشتر» یا «جزئیات» به کاربر نمی‌گوید داخل این بخش چه چیزی پنهان شده.
محتوای حیاتی را داخل بخش بسته پنهان نکنید
پیش از پرداخت، آدرس ارسال را دوباره بررسی کنید.
انجام بده
هشدارها و اطلاعات ضروری را بیرون و همیشه قابل‌مشاهده نگه دارید؛ آکاردئون فقط برای جزئیات تکمیلی است.
انجام نده
وقتی تنها راه دیدن یک هشدار مهم، باز کردن یک بخش تاشوست، بیشتر کاربران اصلاً آن را نمی‌بینند.
غیرفعال‌سازی فقط برای محتوای واقعاً قفل
انجام بده
از disabled روی AccordionItem فقط برای بخشی استفاده کنید که واقعاً برای کاربر در دسترس نیست.
انجام نده
قفل‌کردن یک بخش عادی فقط برای جلب توجه یا ترغیب به ارتقا، کاربر را گیج و بدبین می‌کند.