ناحیه اسکرول (Scroll Area)
کامپوننت ناحیه اسکرول برای ایجاد نوار اسکرول سفارشی با ظاهر یکسان در تمام مرورگرها استفاده میشود. این کامپوننت رفتار اسکرول بومی مرورگر را حفظ میکند.
نصب (Installation)
1npx @quark-lab/rad-ui add scroll-areaنمونهها (Examples)
پیشفرض (Default)
نمایش لیست عمودی با نوار اسکرول سفارشی.
مشاهده کد
1import { ScrollArea } from "@/components/ui/scroll-area";
2import { Separator } from "@/components/ui/separator";
3
4const tags = Array.from({ length: 50 }).map((_, i) => `نسخه ${i + 1}`);
5
6export default function BasicExample() {
7 return (
8 <ScrollArea className="h-72 w-48 rounded-md border">
9 <div className="p-4">
10 <h4 className="mb-4 text-sm font-medium leading-none">برچسبها</h4>
11 {tags.map((tag) => (
12 <div key={tag}>
13 <div className="text-sm">{tag}</div>
14 <Separator className="my-2" />
15 </div>
16 ))}
17 </div>
18 </ScrollArea>
19 );
20}
21افقی (Horizontal)
اسکرول افقی با استفاده از ScrollBar با orientation='horizontal'.
مشاهده کد
1import { ScrollArea, ScrollBar } from "@/components/ui/scroll-area";
2import { Badge } from "@/components/ui/badge";
3
4const badges = [
5 "جاوااسکریپت",
6 "تایپاسکریپت",
7 "ریاکت",
8 "نکست",
9 "تیلویند",
10 "نود",
11 "پایتون",
12 "گو",
13];
14
15export default function HorizontalExample() {
16 return (
17 <ScrollArea className="w-72 rounded-md border whitespace-nowrap">
18 <div className="flex w-max gap-3 p-4">
19 {badges.map((badge) => (
20 <Badge key={badge} variant="secondary">
21 {badge}
22 </Badge>
23 ))}
24 </div>
25 <ScrollBar orientation="horizontal" />
26 </ScrollArea>
27 );
28}
29نوار اسکرول سفارشی (Styled Scrollbar)
سفارشیسازی رنگ دستگیره نوار اسکرول.
مشاهده کد
1import { ScrollArea } from "@/components/ui/scroll-area";
2
3export default function StyledExample() {
4 return (
5 <ScrollArea
6 className="h-72 w-48 rounded-md border"
7 scrollbarThumbClassName="bg-primary hover:bg-primary/80"
8 >
9 <div className="p-4">
10 {Array.from({ length: 30 }).map((_, i) => (
11 <div key={i} className="mb-2 text-sm">
12 آیتم شماره {i + 1}
13 </div>
14 ))}
15 </div>
16 </ScrollArea>
17 );
18}
19اسکرول دوطرفه (Both Scrollbars)
محتوایی که هم به اسکرول عمودی و هم افقی نیاز دارد.
مشاهده کد
1import { ScrollArea, ScrollBar } from "@/components/ui/scroll-area";
2
3export default function BothScrollbarsExample() {
4 return (
5 <ScrollArea className="h-72 w-72 rounded-md border">
6 <div className="p-4 w-[500px]">
7 {Array.from({ length: 20 }).map((_, i) => (
8 <div key={i} className="mb-4">
9 <p className="whitespace-nowrap">
10 این یک متن طولانی است که نیاز به اسکرول افقی دارد - ردیف {i + 1}
11 </p>
12 </div>
13 ))}
14 </div>
15 <ScrollBar orientation="horizontal" />
16 <ScrollBar orientation="vertical" />
17 </ScrollArea>
18 );
19}
20بدون نوار اسکرول (Hidden Scrollbar)
مخفی کردن نوار اسکرول با حفظ قابلیت اسکرول.
مشاهده کد
1import { ScrollArea } from "@/components/ui/scroll-area";
2
3export default function HiddenScrollbarExample() {
4 return (
5 <ScrollArea className="h-72 w-48 rounded-md border" hideScrollbar>
6 <div className="p-4">
7 {Array.from({ length: 30 }).map((_, i) => (
8 <div key={i} className="mb-2 text-sm">
9 آیتم شماره {i + 1}
10 </div>
11 ))}
12 </div>
13 </ScrollArea>
14 );
15}
16مثالهای پیشرفته (Advanced Examples)
ناحیه اسکرول با پسزمینه (Custom Container)
سفارشیسازی ظاهر ناحیه اسکرول و آیتمهای داخلی.
مشاهده کد
1import { ScrollArea, ScrollBar } from "@/components/ui/scroll-area";
2
3export default function CustomContainerExample() {
4 return (
5 <ScrollArea className="h-72 w-48 rounded-md border bg-muted/50">
6 <div className="p-4">
7 {Array.from({ length: 30 }).map((_, i) => (
8 <div
9 key={i}
10 className="mb-2 p-2 rounded bg-card border border-border"
11 >
12 آیتم شماره {i + 1}
13 </div>
14 ))}
15 </div>
16 <ScrollBar className="bg-muted" />
17 </ScrollArea>
18 );
19}
20مرجع API (API Reference)
ScrollArea
پراپهای کامپوننت ScrollArea.
| پراپ (Prop) | نوع (Type) | پیشفرض (Default) | توضیحات (Description) |
|---|---|---|---|
type | "auto" | "always" | "scroll" | "hover" | "hover" | نحوه نمایش نوار اسکرول |
scrollHideDelay | number | 600 | تاخیر مخفی شدن نوار اسکرول (میلیثانیه) |
dir | "ltr" | "rtl" | "rtl" | جهت متن (پیشفرض RTL) |
hideScrollbar | boolean | false | مخفی کردن نوار اسکرول با حفظ قابلیت اسکرول |
scrollbarThumbClassName | string | undefined | کلاسهای CSS برای سفارشیسازی رنگ دستگیره نوار اسکرول |
className | string | undefined | کلاسهای CSS اضافی |
ScrollBar
پراپهای کامپوننت ScrollBar.
| پراپ (Prop) | نوع (Type) | پیشفرض (Default) | توضیحات (Description) |
|---|---|---|---|
orientation | "vertical" | "horizontal" | "vertical" | جهت نوار اسکرول |
forceMount | boolean | undefined | نمایش اجباری حتی وقتی محتوا نیاز به اسکرول ندارد |
thumbClassName | string | undefined | کلاسهای CSS برای دستگیره نوار اسکرول |
className | string | undefined | کلاسهای CSS اضافی برای track نوار اسکرول |
بهترین شیوهها (Best Practices)
تعیین ارتفاع ثابت (Fixed Height)
برای فعال شدن اسکرول عمودی، حتماً یک ارتفاع ثابت (مثل h-72 یا h-[300px]) روی ScrollArea تنظیم کنید
اسکرول افقی (Horizontal Scroll)
برای اسکرول افقی، از whitespace-nowrap روی container و ScrollBar با orientation="horizontal" استفاده کنید
پشتیبانی RTL
برای زبانهای راست به چپ، prop dir="rtl" را روی ScrollArea تنظیم کنید تا نوار اسکرول در سمت صحیح نمایش داده شود