Collapsiblev1.0.0
یک بخش تکی که باز و بسته می‌شود. برخلاف آکاردئون، نه گروهی است و نه ظاهر آماده‌ای دارد؛ فقط رفتار باز و بسته شدن به‌همراه انیمیشن ارتفاع را می‌دهد و چیدمان کاملاً دست شماست.
این کامپوننت فعلاً برای ۱ فریم‌ورک از ۴ فریم‌ورک آماده است.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
نصب
با CLI اختصاصی digdesign کامپوننت را از رجیستری دیگ نصب کنید؛ وابستگی‌ها و فایل‌ها خودکار اضافه می‌شوند.
npx digdesign@latest add https://docs.digdesign.ir/r/collapsible.jsonpnpm dlx digdesign@latest add https://docs.digdesign.ir/r/collapsible.jsonyarn dlx digdesign@latest add https://docs.digdesign.ir/r/collapsible.jsonbunx --bun digdesign@latest add https://docs.digdesign.ir/r/collapsible.jsonاین کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
استفاده
import {
Collapsible,
CollapsibleContent,
CollapsibleTrigger,
} from "@/components/ui/collapsible"
<Collapsible>
<CollapsibleTrigger>نمایش جزئیات</CollapsibleTrigger>
<CollapsibleContent>جزئیات…</CollapsibleContent>
</Collapsible>این کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
ترکیب اجزا
سه جزء دارد و هیچ استایل ظاهری‌ای تحمیل نمی‌کند: Collapsible حالت را نگه می‌دارد، CollapsibleTrigger با asChild روی دکمهٔ خودتان می‌نشیند و CollapsibleContent محتوای تاشو را می‌گیرد.
ارتفاع محتوا با ResizeObserver اندازه‌گیری و در یک متغیر CSS تزریق می‌شود تا انیمیشن باز/بسته شدن نرم باشد؛ برای همین overflow-hidden روی محتوا لازم است و padding عمودی را بهتر است روی یک div داخلی بدهید تا پرش نداشته باشد.
اگر چند بخش تاشو کنار هم دارید و باید هماهنگ باشند، آکاردئون گزینهٔ درست‌تری است.
دسترس‌پذیری
- تریگر یک دکمهٔ واقعی است و aria-expanded و aria-controls خودکار روی آن ست می‌شود.
- اگر تریگر فقط آیکون دارد، یک span با کلاس sr-only داخلش بگذارید تا صفحه‌خوان کار دکمه را بفهمد.
- محتوای بسته از DOM حذف می‌شود، پس نه فوکوس می‌گیرد و نه صفحه‌خوان آن را می‌خواند؛ اگر برای انیمیشن سفارشی لازم دارید بماند، forceMount بدهید.
- محتوایی که باید با Ctrl+F پیدا شود را داخل بخش تاشو نگذارید.
مرجع API
Collapsible
| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| open / onOpenChange | boolean / (open: boolean) => void | — | حالت کنترل‌شده؛ برای وقتی که باز بودن بخش به حالت بیرونی وابسته است. |
| defaultOpen | boolean | false | باز بودن در اولین رندر (کنترل‌نشده). |
| disabled | boolean | false | تریگر را غیرفعال می‌کند و حالت فعلی قفل می‌ماند. |
CollapsibleTrigger
| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| asChild | boolean | false | رفتار تریگر را روی فرزند سوار می‌کند؛ با Button همیشه از این استفاده کنید. |
CollapsibleContent
| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| forceMount | boolean | — | محتوا را در حالت بسته هم در DOM نگه می‌دارد؛ برای کنترل دستی انیمیشن. |
| className | string | — | overflow-hidden و انیمیشن ارتفاع از پیش اعمال شده‌اند؛ کلاس شما با cn روی آن‌ها می‌نشیند. |
این کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
نمونه‌ها
Advanced Filters
کاربرد کلاسیک: پنهان کردن تنظیمات پیشرفته تا وقتی کاربر بخواهد.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
Open by Default
defaultOpen بخش را در اولین رندر باز نگه می‌دارد؛ برای اطلاعاتی که معمولاً لازم است.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
Disabled
با disabled بخش در همان حالت فعلی قفل می‌شود و تریگر کلیک نمی‌گیرد.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
در حال دریافت (Loading)
محتوا را تا لحظهٔ نیاز نگیرید، ولی بعد از باز شدن، جای خالی نشان دهید نه فضای خالی؛ کاربر باید بفهمد چیزی در راه است.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
کدام نمونه برای کدام موقعیت
| نمونه | کجا به کار می‌آید |
|---|---|
| Advanced Filters | کاربرد کلاسیک: پنهان کردن تنظیمات پیشرفته تا وقتی کاربر بخواهد. |
| Open by Default | defaultOpen بخش را در اولین رندر باز نگه می‌دارد؛ برای اطلاعاتی که معمولاً لازم است. |
| Disabled | با disabled بخش در همان حالت فعلی قفل می‌شود و تریگر کلیک نمی‌گیرد. |
| در حال دریافت (Loading) | بخشی که محتوایش فقط با باز شدن گرفته می‌شود |
دستورالعمل استفاده
برچسب دسترس‌پذیر برای تریگر فقط‌آیکونی
انجام بده
وقتی تریگر فقط آیکون دارد، یک span با کلاس sr-only داخلش بگذارید تا صفحه‌خوان اسم دکمه را بگوید، نه فقط «دکمه».
انجام نده
بدون متن جایگزین، صفحه‌خوان فقط می‌گوید «دکمه» و کاربر نمی‌فهمد با کلیک چه اتفاقی می‌افتد.
پیش‌فرض باز برای اطلاعاتی که معمولاً لازم است
وضعیت: در حال آماده‌سازی
انجام بده
اگر محتوای تاشو چیزی است که اغلب کاربران بلافاصله لازم دارند (مثل جزئیات سفارش)، با defaultOpen از ابتدا بازش کنید.
انجام نده
بستن پیش‌فرضِ اطلاعاتی که هر بار لازم است، کاربر را مجبور به یک کلیک اضافه در هر بازدید می‌کند.
برای چند بخش هماهنگ از آکاردئون استفاده کنید
انجام بده
Collapsible را برای یک بخش مستقل و تنها به‌کار ببرید که باز و بسته شدنش به بخش‌های دیگر ربطی ندارد.
محتوای بخش یک
محتوای بخش دو
انجام نده
چیدن چند Collapsible مستقل کنار هم برای رفتار آکاردئونی (فقط یکی باز بماند) کار نمی‌کند؛ هرکدام جدا از بقیه باز و بسته می‌شود و همه می‌توانند هم‌زمان باز باشند.