Scroll Areav1.0.0
ناحیه‌ای با ارتفاع یا عرض ثابت که محتوای بلندتر از خودش را اسکرول می‌کند و به‌جای نوار بومی مرورگر، یک نوار باریک و هماهنگ با تم نشان می‌دهد. در چیدمان راست‌به‌چپ، نوار عمودی خودکار سمت چپ می‌نشیند.
این کامپوننت فعلاً برای ۱ فریم‌ورک از ۴ فریم‌ورک آماده است.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
نصب
با CLI اختصاصی digdesign کامپوننت را از رجیستری دیگ نصب کنید؛ وابستگی‌ها و فایل‌ها خودکار اضافه می‌شوند.
npx digdesign@latest add https://docs.digdesign.ir/r/scroll-area.jsonpnpm dlx digdesign@latest add https://docs.digdesign.ir/r/scroll-area.jsonyarn dlx digdesign@latest add https://docs.digdesign.ir/r/scroll-area.jsonbunx --bun digdesign@latest add https://docs.digdesign.ir/r/scroll-area.jsonاین کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
استفاده
import { ScrollArea } from "@/components/ui/scroll-area"
<ScrollArea className="h-72 w-48 rounded-md border">
محتوای بلند…
</ScrollArea>این کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
ترکیب اجزا
ارتفاع (یا عرض) را روی خود ScrollArea بدهید، وگرنه ناحیه با محتوا رشد می‌کند و هیچ‌وقت اسکرول نمی‌شود.
محتوا داخل یک Viewport رندر می‌شود؛ padding را روی یک div داخلی بگذارید نه روی ScrollArea، تا نوار اسکرول به لبهٔ کادر بچسبد و فاصلهٔ محتوا از نوار جدا بماند.
نسخهٔ پیش‌فرض فقط نوار عمودی می‌سازد؛ برای اسکرول افقی ScrollBar را با orientation="horizontal" خودتان اضافه کنید.
دسترس‌پذیری
- Viewport با tabIndex قابل فوکوس است، پس کاربر صفحه‌کلید می‌تواند با کلیدهای جهت‌دار و PageUp/PageDown داخل ناحیه اسکرول کند.
- نوار سفارشی جای اسکرول بومی را می‌گیرد ولی رفتار چرخ ماوس و لمس دست‌نخورده باقی می‌ماند.
- ناحیه‌ای که اسکرول می‌شود بهتر است عنوان یا برچسبی داشته باشد؛ برای فهرست‌های بلند یک aria-label روی ScrollArea بگذارید.
- ارتفاع ثابت را با واحد نسبی بدهید تا با بزرگ‌کردن اندازهٔ قلم مرورگر، محتوا بریده نشود.
- در راست‌به‌چپ نوار عمودی سمت چپ می‌نشیند؛ این را در محاسبهٔ فاصله‌های داخلی در نظر بگیرید تا متن زیر نوار نرود.
مرجع API
ScrollArea
| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| type | "auto" | "always" | "scroll" | "hover" | "hover" | زمان نمایش نوار: hover هنگام نزدیک شدن نشانگر، scroll هنگام اسکرول، always همیشه و auto فقط وقتی محتوا سرریز کند. |
| scrollHideDelay | number | 600 | میلی‌ثانیه تا پنهان شدن نوار بعد از توقف اسکرول (در حالت‌های hover و scroll). |
| dir | "rtl" | "ltr" | — | جهت ناحیه؛ معمولاً از dir صفحه ارث می‌رسد و جای نوار عمودی را تعیین می‌کند. |
| className | string | — | اینجا حتماً ارتفاع یا عرض بدهید؛ بدون اندازهٔ ثابت اسکرولی در کار نیست. |
ScrollBar
نوار عمودی خودکار داخل ScrollArea رندر می‌شود؛ این کامپوننت را فقط برای نوار افقی دستی اضافه کنید.
| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| orientation | "vertical" | "horizontal" | "vertical" | جهت نوار اسکرول. |
| forceMount | boolean | — | نوار را همیشه در DOM نگه می‌دارد؛ برای انیمیشن‌های سفارشی. |
data-slot
| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| scroll-area-viewport | div | — | ناحیهٔ واقعی اسکرول؛ اگر لازم شد اسکرول را از کد کنترل کنید، همین را انتخاب کنید. |
| scroll-area-thumb | div | — | دستهٔ نوار؛ رنگش از توکن border می‌آید. |
این کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
نمونه‌ها
Horizontal Scroll
برای اسکرول افقی یک ScrollBar با orientation="horizontal" اضافه کنید؛ در راست‌به‌چپ حرکت از راست به چپ شروع می‌شود.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
List of People
کاربرد رایج: فهرست اعضا یا نتایج جستجو در یک پنل با ارتفاع محدود.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
Always Visible Scrollbar
پیش‌فرض type="hover" رفتار سیستم است. با type="always" نوار همیشه دیده می‌شود؛ مفید وقتی کاربر باید بفهمد محتوا ادامه دارد.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
خالی (Empty)
ناحیهٔ اسکرول خالی نباید فضای خالیِ بی‌توضیح باشد؛ بگویید چرا خالی است.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
در حال دریافت (Loading)
جای خالیِ هم‌شکل با محتوای واقعی بگذارید تا با رسیدن داده، ارتفاع نپرد.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
کدام نمونه برای کدام موقعیت
| نمونه | کجا به کار می‌آید |
|---|---|
| Horizontal Scroll | برای اسکرول افقی یک ScrollBar با orientation="horizontal" اضافه کنید؛ در راست‌به‌چپ حرکت از راست به چپ شروع می‌شود. |
| List of People | کاربرد رایج: فهرست اعضا یا نتایج جستجو در یک پنل با ارتفاع محدود. |
| Always Visible Scrollbar | پیش‌فرض type="hover" رفتار سیستم است |
| خالی (Empty) | فهرست بلندی که هنوز محتوایی ندارد |
| در حال دریافت (Loading) | فهرستی که محتوایش از سرور می‌آید |
دستورالعمل استفاده
ارتفاع یا عرض ثابت مشخص
انجام بده
همیشه روی ScrollArea یک ارتفاع یا عرض ثابت بدهید (مثل h-56)، وگرنه هیچ‌وقت اسکرول فعال نمی‌شود.
انجام نده
بدون کلاس ارتفاع/عرض، ناحیه با محتوا رشد می‌کند و کل صفحه را طولانی می‌کند؛ نوار سفارشی هرگز دیده نمی‌شود.
برای ناحیهٔ محدود، نه کل صفحه
انجام بده
از ScrollArea برای بخش‌های محدود مثل یک فهرست یا پنل داخل کارت استفاده کنید؛ اسکرول اصلی صفحه را دست‌نخورده بگذارید.
انجام نده
پیچیدن کل محتوای صفحه در یک ScrollArea یک اسکرول تودرتو با اسکرول اصلی مرورگر می‌سازد که هم گیج‌کننده است و هم رفتار PageUp/PageDown را دوپهلو می‌کند.