کالپس (Collapsible)
کامپوننت تعاملی برای باز و بسته کردن بخشهای محتوا؛ مناسب برای جزئیات اضافی، تنظیمات پیشرفته و ساخت درخت فایل. کاملاً سازگار با RTL و قابل ترکیب با سایر کامپوننتهای Rad UI.
نصب (Installation)
1npx @quark-lab/rad-ui add collapsibleنمونهها (Examples)
نمونه پایه (Basic)
کالپس ساده برای نمایش جزئیات بیشتر یک کارت محصول.
مشاهده کد
1import { Button, Card, CardContent } from "@/components/ui/card";
2import {
3 Collapsible,
4 CollapsibleContent,
5 CollapsibleTrigger,
6} from "@/components/ui/collapsible";
7
8export default function BasicCollapsibleExample() {
9 return (
10 <Card className="mx-auto w-full max-w-sm">
11 <CardContent className="p-2">
12 <Collapsible className="w-full rounded-md border border-border data-[state=open]:bg-muted">
13 <CollapsibleTrigger className="group flex w-full items-center justify-between px-3 py-2 text-sm font-medium">
14 جزئیات محصول
15 <span className="ms-auto text-xs text-muted-foreground group-data-[state=open]:rotate-180">
16 ▼
17 </span>
18 </CollapsibleTrigger>
19 <CollapsibleContent className="flex flex-col items-start gap-2 border-t border-border px-3 pb-3 pt-2 text-sm text-muted-foreground data-[state=closed]:border-t-0 data-[state=closed]:p-0">
20 <div>
21 این بخش میتواند برای نمایش توضیحات تکمیلی محصول باز و بسته شود.
22 </div>
23 <Button size="sm">بیشتر بدانید</Button>
24 </CollapsibleContent>
25 </Collapsible>
26 </CardContent>
27 </Card>
28 );
29}
30حالت کنترلشده (Controlled State)
مدیریت وضعیت باز/بسته توسط state خارجی با onOpenChange.
مشاهده کد
1import * as React from "react";
2
3import {
4 Button,
5 Collapsible,
6 CollapsibleContent,
7 CollapsibleTrigger,
8} from "@/components/ui/collapsible";
9
10export default function ControlledCollapsibleExample() {
11 const [open, setOpen] = React.useState(false);
12
13 return (
14 <div className="flex w-full max-w-sm flex-col items-stretch gap-3">
15 <Button
16 variant="outline"
17 className="w-full"
18 onClick={() => setOpen((prev) => !prev)}
19 >
20 {open ? "بستن جزئیات" : "نمایش جزئیات"}
21 </Button>
22
23 <Collapsible
24 open={open}
25 onOpenChange={setOpen}
26 className="space-y-2 w-full"
27 >
28 <CollapsibleTrigger className="text-sm font-medium text-primary underline-offset-4 hover:underline">
29 تغییر وضعیت از داخل کامپوننت
30 </CollapsibleTrigger>
31 <CollapsibleContent className="text-sm text-muted-foreground">
32 این نمونه نشان میدهد چگونه میتوانید وضعیت باز/بسته را به صورت
33 کنترلشده مدیریت کنید.
34 </CollapsibleContent>
35 </Collapsible>
36 </div>
37 );
38}
39پنل تنظیمات (Settings Panel)
استفاده از Collapsible برای نمایش تنظیمات پیشرفته در فرم.
شعاع گوشهها
شعاع گوشههای المان را تنظیم کنید.
مشاهده کد
1import * as React from "react";
2import {
3 Button,
4 Card,
5 CardContent,
6 CardDescription,
7 CardHeader,
8 CardTitle,
9 Collapsible,
10 CollapsibleContent,
11 CollapsibleTrigger,
12 Field,
13 FieldGroup,
14 FieldLabel,
15 Input,
16} from "@/components/ui/collapsible";
17import { Maximize, Minimize } from "lucide-react";
18
19export default function CollapsibleSettingsPanel() {
20 const [open, setOpen] = React.useState(false);
21
22 return (
23 <Card className="mx-auto w-full max-w-xs" size="sm">
24 <CardHeader>
25 <CardTitle>شعاع گوشهها</CardTitle>
26 <CardDescription>شعاع گوشههای المان را تنظیم کنید.</CardDescription>
27 </CardHeader>
28 <CardContent>
29 <Collapsible
30 open={open}
31 onOpenChange={setOpen}
32 className="flex items-start gap-2"
33 >
34 <FieldGroup className="grid w-full grid-cols-2 gap-2">
35 <Field>
36 <FieldLabel htmlFor="radius-x" className="sr-only">
37 Radius X
38 </FieldLabel>
39 <Input id="radius-x" placeholder="0" defaultValue={0} />
40 </Field>
41 <Field>
42 <FieldLabel htmlFor="radius-y" className="sr-only">
43 Radius Y
44 </FieldLabel>
45 <Input id="radius-y" placeholder="0" defaultValue={0} />
46 </Field>
47 <CollapsibleContent className="col-span-full grid grid-cols-subgrid gap-2">
48 <Field>
49 <FieldLabel htmlFor="radius-top" className="sr-only">
50 Radius Top
51 </FieldLabel>
52 <Input id="radius-top" placeholder="0" defaultValue={0} />
53 </Field>
54 <Field>
55 <FieldLabel htmlFor="radius-bottom" className="sr-only">
56 Radius Bottom
57 </FieldLabel>
58 <Input id="radius-bottom" placeholder="0" defaultValue={0} />
59 </Field>
60 </CollapsibleContent>
61 </FieldGroup>
62 <CollapsibleTrigger asChild>
63 <Button
64 variant="outline"
65 size="sm"
66 className="aspect-square p-0"
67 aria-label={open ? "بستن تنظیمات پیشرفته" : "نمایش تنظیمات پیشرفته"}
68 >
69 {open ? (
70 <Minimize className="w-4 h-4" />
71 ) : (
72 <Maximize className="w-4 h-4" />
73 )}
74 </Button>
75 </CollapsibleTrigger>
76 </Collapsible>
77 </CardContent>
78 </Card>
79 );
80}
81مرجع API (API Reference)
Collapsible
کامپوننت ریشه که وضعیت باز/بسته را مدیریت میکند.
| پراپ (Prop) | نوع (Type) | پیشفرض (Default) | توضیحات (Description) |
|---|---|---|---|
open | boolean | undefined | وضعیت باز/بسته به صورت کنترلشده. در صورت استفاده باید همراه با onOpenChange باشد. |
defaultOpen | boolean | false | باز بودن اولیه کامپوننت در حالت غیرکنترلشده. |
onOpenChange | (open: boolean) => void | undefined | تابع فراخوانی هنگام تغییر وضعیت باز/بسته. |
disabled | boolean | false | غیرفعال کردن تعامل با کامپوننت. |
className | string | - | کلاسهای CSS سفارشی برای ریشه Collapsible. |
CollapsibleTrigger
تریگری که با کلیک روی آن محتوا باز یا بسته میشود.
| پراپ (Prop) | نوع (Type) | پیشفرض (Default) | توضیحات (Description) |
|---|---|---|---|
asChild | boolean | false | در صورت true شدن، به جای دکمه پیشفرض، کامپوننت فرزند به عنوان ریشه رندر میشود. |
className | string | - | کلاسهای CSS سفارشی برای تریگر. |
CollapsibleContent
محتوای جمعشونده که زیر تریگر نمایش داده میشود.
| پراپ (Prop) | نوع (Type) | پیشفرض (Default) | توضیحات (Description) |
|---|---|---|---|
className | string | - | کلاسهای CSS سفارشی برای محتوای جمعشونده (روی روت محتوا اعمال میشود). |
دسترسیپذیری (Accessibility)
نقش و وضعیت (Role & State)
کالپس بر پایه Radix Collapsible ساخته شده و به صورت خودکار نقشها و وضعیت data-state="open" | "closed" را مدیریت میکند.
کیبورد (Keyboard)
EnterوSpace— باز یا بسته کردن کالپس در هنگام فوکوس روی تریگر.Tab— حرکت بین تریگر و سایر المانهای قابل فوکوس.
پشتیبانی RTL
از کلاسهایی مثل ms-auto و text-start استفاده کنید تا چیدمان در جهت راستبهچپ و چپبهراست درست عمل کند.
بهترین شیوهها (Best Practices)
چه زمانی از Collapsible استفاده کنیم؟
- نمایش جزئیات سفارش، محصول یا رکورد دیتابیس.
- تنظیمات پیشرفته که همیشه لازم نیست دیده شوند.
- درخت فایل یا ساختارهای سلسلهمراتبی کوچک.
برچسبگذاری واضح
متن تریگر را واضح و توصیفی انتخاب کنید تا کاربر بداند با باز کردن چه محتوایی نمایش داده میشود.
ترکیب با سایر کامپوننتها
Collapsible را میتوانید با کامپوننتهایی مثل Card، Field، Input و Tabs ترکیب کنید تا الگوهای UI غنیتری بسازید.
نحوه استفاده (Usage)
1import {
2 Collapsible,
3 CollapsibleContent,
4 CollapsibleTrigger,
5} from "@/components/ui/collapsible";
6
7export default function CollapsibleUsage() {
8 return (
9 <Collapsible className="space-y-2">
10 <CollapsibleTrigger className="text-sm font-medium underline-offset-4 hover:underline">
11 آیا میتوانم از این کامپوننت در پروژه استفاده کنم؟
12 </CollapsibleTrigger>
13 <CollapsibleContent className="text-sm text-muted-foreground">
14 بله. استفاده شخصی و تجاری آزاد است و نیازی به ذکر منبع نیست.
15 </CollapsibleContent>
16 </Collapsible>
17 );
18}
19