پاپاور (Popover)
نمایش محتوای غنی در یک پورتال که با کلیک روی یک دکمه فعال میشود.
نصب (Installation)
npx @quark-lab/rad-ui add popoverنمونهها (Examples)
استفاده پایه (Basic)
یک پاپاور ساده با هدر، عنوان و توضیحات.
مشاهده کد
1import {
2 Popover,
3 PopoverContent,
4 PopoverDescription,
5 PopoverHeader,
6 PopoverTitle,
7 PopoverTrigger,
8} from "@/components/ui/popover";
9import { Button } from "@/components/ui/button";
10
11export default function BasicPopover() {
12 return (
13 <Popover>
14 <PopoverTrigger asChild>
15 <Button variant="outline">باز کردن پاپاور</Button>
16 </PopoverTrigger>
17 <PopoverContent>
18 <PopoverHeader>
19 <PopoverTitle>عنوان</PopoverTitle>
20 <PopoverDescription>
21 متن توضیحات در اینجا نمایش داده میشود.
22 </PopoverDescription>
23 </PopoverHeader>
24 </PopoverContent>
25 </Popover>
26 );
27}تراز (Align)
استفاده از پراپ align در PopoverContent برای کنترل تراز افقی.
مشاهده کد
1import {
2 Popover,
3 PopoverContent,
4 PopoverDescription,
5 PopoverHeader,
6 PopoverTitle,
7 PopoverTrigger,
8} from "@/components/ui/popover";
9import { Button } from "@/components/ui/button";
10
11export default function AlignPopover() {
12 return (
13 <div className="flex flex-wrap gap-4">
14 <Popover>
15 <PopoverTrigger asChild>
16 <Button variant="outline">شروع</Button>
17 </PopoverTrigger>
18 <PopoverContent align="start">
19 <PopoverHeader>
20 <PopoverTitle>تراز شروع</PopoverTitle>
21 <PopoverDescription>
22 محتوا از سمت شروع تراز شده است.
23 </PopoverDescription>
24 </PopoverHeader>
25 </PopoverContent>
26 </Popover>
27
28 <Popover>
29 <PopoverTrigger asChild>
30 <Button variant="outline">مرکز</Button>
31 </PopoverTrigger>
32 <PopoverContent align="center">
33 <PopoverHeader>
34 <PopoverTitle>تراز مرکز</PopoverTitle>
35 <PopoverDescription>
36 محتوا در مرکز تراز شده است.
37 </PopoverDescription>
38 </PopoverHeader>
39 </PopoverContent>
40 </Popover>
41
42 <Popover>
43 <PopoverTrigger asChild>
44 <Button variant="outline">پایان</Button>
45 </PopoverTrigger>
46 <PopoverContent align="end">
47 <PopoverHeader>
48 <PopoverTitle>تراز پایان</PopoverTitle>
49 <PopoverDescription>
50 محتوا از سمت پایان تراز شده است.
51 </PopoverDescription>
52 </PopoverHeader>
53 </PopoverContent>
54 </Popover>
55 </div>
56 );
57}با فرم (With Form)
یک پاپاور با فیلدهای فرم در داخل.
مشاهده کد
1import {
2 Popover,
3 PopoverContent,
4 PopoverDescription,
5 PopoverHeader,
6 PopoverTitle,
7 PopoverTrigger,
8} from "@/components/ui/popover";
9import { Field, FieldGroup, FieldLabel } from "@/components/ui/field";
10import { Input } from "@/components/ui/input";
11import { Button } from "@/components/ui/button";
12
13export default function WithFormPopover() {
14 return (
15 <Popover>
16 <PopoverTrigger asChild>
17 <Button variant="outline">باز کردن پاپاور</Button>
18 </PopoverTrigger>
19 <PopoverContent className="w-80">
20 <PopoverHeader>
21 <PopoverTitle>ایجاد حساب کاربری</PopoverTitle>
22 <PopoverDescription>
23 اطلاعات خود را وارد کنید تا حساب کاربری جدید ایجاد شود.
24 </PopoverDescription>
25 </PopoverHeader>
26 <div className="mt-4 space-y-4">
27 <Field>
28 <FieldGroup>
29 <FieldLabel>نام</FieldLabel>
30 <Input placeholder="نام خود را وارد کنید" />
31 </FieldGroup>
32 </Field>
33 <Field>
34 <FieldGroup>
35 <FieldLabel>ایمیل</FieldLabel>
36 <Input type="email" placeholder="ایمیل خود را وارد کنید" />
37 </FieldGroup>
38 </Field>
39 <div className="flex justify-end gap-2">
40 <Button variant="outline" size="sm">انصراف</Button>
41 <Button size="sm">ایجاد</Button>
42 </div>
43 </div>
44 </PopoverContent>
45 </Popover>
46 );
47}مرجع API (API Reference)
Popover
کامپوننت اصلی که به عنوان کانتینر برای پاپاور عمل میکند.
| پراپ (Prop) | نوع (Type) | پیشفرض (Default) | توضیحات (Description) |
|---|---|---|---|
open | boolean | undefined | وضعیت باز/بسته بودن (کنترلشده) |
defaultOpen | boolean | false | وضعیت پیشفرض (غیرکنترلشده) |
onOpenChange | (open: boolean) => void | undefined | تابع فراخوانی هنگام تغییر وضعیت |
modal | boolean | true | آیا پاپاور به صورت مودال نمایش داده شود |
PopoverTrigger
عنصری که پاپاور را فعال میکند. معمولاً یک دکمه است.
| پراپ (Prop) | نوع (Type) | پیشفرض (Default) | توضیحات (Description) |
|---|---|---|---|
className | string | - | کلاسهای CSS سفارشی |
PopoverContent
محتوای پاپاور که نمایش داده میشود.
| پراپ (Prop) | نوع (Type) | پیشفرض (Default) | توضیحات (Description) |
|---|---|---|---|
side | "top" | "bottom" | "left" | "right" | "bottom" | جهت نمایش پاپاور نسبت به تریگر |
sideOffset | number | 4 | فاصله از تریگر به پیکسل |
align | "start" | "center" | "end" | "center" | تراز پاپاور نسبت به تریگر |
alignOffset | number | 0 | آفست تراز به پیکسل |
className | string | - | کلاسهای CSS سفارشی |
PopoverHeader
برای گروهبندی عنوان و توضیحات استفاده میشود.
| پراپ (Prop) | نوع (Type) | پیشفرض (Default) | توضیحات (Description) |
|---|---|---|---|
className | string | - | کلاسهای CSS سفارشی |
PopoverTitle
برای نمایش عنوان پاپاور استفاده میشود.
| پراپ (Prop) | نوع (Type) | پیشفرض (Default) | توضیحات (Description) |
|---|---|---|---|
className | string | - | کلاسهای CSS سفارشی |
PopoverDescription
برای نمایش توضیحات پاپاور استفاده میشود.
| پراپ (Prop) | نوع (Type) | پیشفرض (Default) | توضیحات (Description) |
|---|---|---|---|
className | string | - | کلاسهای CSS سفارشی |
دسترسیپذیری (Accessibility)
پشتیبانی از صفحهخوان (Screen Reader Support)
PopoverTitle و PopoverDescription به صورت خودکار با صفحهخوانها ارتباط برقرار میکنند و محتوای پاپاور را به کاربران نابینا اعلام میکنند.
پشتیبانی از RTL
تمام کامپوننتها از ویژگیهای منطقی CSS استفاده میکنند و در هر دو جهت RTL و LTR به درستی کار میکنند.
مدیریت فوکوس (Focus Management)
هنگام باز شدن پاپاور، فوکوس به محتوای آن منتقل میشود و با بسته شدن، به تریگر برمیگردد.
بهترین شیوهها (Best Practices)
ساختار پاپاور (Popover Structure)
- PopoverTrigger: همیشه از
asChildبرای ترکیب با دکمهها استفاده کنید - PopoverHeader: برای گروهبندی عنوان و توضیحات استفاده کنید
- PopoverContent: محتوای اصلی را در این بخش قرار دهید
تراز و موقعیت
- align: برای کنترل تراز افقی استفاده کنید (start, center, end)
- side: برای تعیین جهت نمایش استفاده کنید (top, bottom, left, right)
- sideOffset: برای تنظیم فاصله از تریگر استفاده کنید
استفاده با فرمها
پاپاور برای نمایش فرمهای کوچک، منوهای عملیات یا اطلاعات تکمیلی مناسب است. از آن برای محتوای تعاملی که نیاز به ورودی کاربر دارد استفاده کنید.
نحوه استفاده (Usage)
نمونه کامل از نحوه ایمپورت و استفاده از کامپوننت پاپاور.
مشاهده کد
1import {
2 Popover,
3 PopoverContent,
4 PopoverDescription,
5 PopoverHeader,
6 PopoverTitle,
7 PopoverTrigger,
8} from "@/components/ui/popover";
9import { Button } from "@/components/ui/button";
10
11export default function MyComponent() {
12 return (
13 <Popover>
14 <PopoverTrigger asChild>
15 <Button variant="outline">باز کردن پاپاور</Button>
16 </PopoverTrigger>
17 <PopoverContent>
18 <PopoverHeader>
19 <PopoverTitle>عنوان</PopoverTitle>
20 <PopoverDescription>
21 متن توضیحات در اینجا نمایش داده میشود.
22 </PopoverDescription>
23 </PopoverHeader>
24 </PopoverContent>
25 </Popover>
26 );
27}مثالهای پیشرفته (Advanced Examples)
تراز (Align)
استفاده از پراپ align برای کنترل تراز افقی پاپاور.
مشاهده کد
1import {
2 Popover,
3 PopoverContent,
4 PopoverDescription,
5 PopoverHeader,
6 PopoverTitle,
7 PopoverTrigger,
8} from "@/components/ui/popover";
9import { Button } from "@/components/ui/button";
10
11export default function AlignPopover() {
12 return (
13 <div className="flex flex-wrap gap-4">
14 <Popover>
15 <PopoverTrigger asChild>
16 <Button variant="outline">شروع</Button>
17 </PopoverTrigger>
18 <PopoverContent align="start">
19 <PopoverHeader>
20 <PopoverTitle>تراز شروع</PopoverTitle>
21 <PopoverDescription>
22 محتوا از سمت شروع تراز شده است.
23 </PopoverDescription>
24 </PopoverHeader>
25 </PopoverContent>
26 </Popover>
27
28 <Popover>
29 <PopoverTrigger asChild>
30 <Button variant="outline">مرکز</Button>
31 </PopoverTrigger>
32 <PopoverContent align="center">
33 <PopoverHeader>
34 <PopoverTitle>تراز مرکز</PopoverTitle>
35 <PopoverDescription>
36 محتوا در مرکز تراز شده است.
37 </PopoverDescription>
38 </PopoverHeader>
39 </PopoverContent>
40 </Popover>
41
42 <Popover>
43 <PopoverTrigger asChild>
44 <Button variant="outline">پایان</Button>
45 </PopoverTrigger>
46 <PopoverContent align="end">
47 <PopoverHeader>
48 <PopoverTitle>تراز پایان</PopoverTitle>
49 <PopoverDescription>
50 محتوا از سمت پایان تراز شده است.
51 </PopoverDescription>
52 </PopoverHeader>
53 </PopoverContent>
54 </Popover>
55 </div>
56 );
57}با فرم (With Form)
استفاده از پاپاور برای نمایش فرمهای کوچک.
مشاهده کد
1import {
2 Popover,
3 PopoverContent,
4 PopoverDescription,
5 PopoverHeader,
6 PopoverTitle,
7 PopoverTrigger,
8} from "@/components/ui/popover";
9import { Field, FieldGroup, FieldLabel } from "@/components/ui/field";
10import { Input } from "@/components/ui/input";
11import { Button } from "@/components/ui/button";
12
13export default function WithFormPopover() {
14 return (
15 <Popover>
16 <PopoverTrigger asChild>
17 <Button variant="outline">باز کردن پاپاور</Button>
18 </PopoverTrigger>
19 <PopoverContent className="w-80">
20 <PopoverHeader>
21 <PopoverTitle>ایجاد حساب کاربری</PopoverTitle>
22 <PopoverDescription>
23 اطلاعات خود را وارد کنید تا حساب کاربری جدید ایجاد شود.
24 </PopoverDescription>
25 </PopoverHeader>
26 <div className="mt-4 space-y-4">
27 <Field>
28 <FieldGroup>
29 <FieldLabel>نام</FieldLabel>
30 <Input placeholder="نام خود را وارد کنید" />
31 </FieldGroup>
32 </Field>
33 <Field>
34 <FieldGroup>
35 <FieldLabel>ایمیل</FieldLabel>
36 <Input type="email" placeholder="ایمیل خود را وارد کنید" />
37 </FieldGroup>
38 </Field>
39 <div className="flex justify-end gap-2">
40 <Button variant="outline" size="sm">انصراف</Button>
41 <Button size="sm">ایجاد</Button>
42 </div>
43 </div>
44 </PopoverContent>
45 </Popover>
46 );
47}