پاپ‌اور (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)
openbooleanundefinedوضعیت باز/بسته بودن (کنترل‌شده)
defaultOpenbooleanfalseوضعیت پیش‌فرض (غیرکنترل‌شده)
onOpenChange(open: boolean) => voidundefinedتابع فراخوانی هنگام تغییر وضعیت
modalbooleantrueآیا پاپ‌اور به صورت مودال نمایش داده شود

PopoverTrigger

عنصری که پاپ‌اور را فعال می‌کند. معمولاً یک دکمه است.

پراپ (Prop)نوع (Type)پیش‌فرض (Default)توضیحات (Description)
classNamestring-کلاس‌های CSS سفارشی

PopoverContent

محتوای پاپ‌اور که نمایش داده می‌شود.

پراپ (Prop)نوع (Type)پیش‌فرض (Default)توضیحات (Description)
side"top" | "bottom" | "left" | "right""bottom"جهت نمایش پاپ‌اور نسبت به تریگر
sideOffsetnumber4فاصله از تریگر به پیکسل
align"start" | "center" | "end""center"تراز پاپ‌اور نسبت به تریگر
alignOffsetnumber0آفست تراز به پیکسل
classNamestring-کلاس‌های CSS سفارشی

PopoverHeader

برای گروه‌بندی عنوان و توضیحات استفاده می‌شود.

پراپ (Prop)نوع (Type)پیش‌فرض (Default)توضیحات (Description)
classNamestring-کلاس‌های CSS سفارشی

PopoverTitle

برای نمایش عنوان پاپ‌اور استفاده می‌شود.

پراپ (Prop)نوع (Type)پیش‌فرض (Default)توضیحات (Description)
classNamestring-کلاس‌های CSS سفارشی

PopoverDescription

برای نمایش توضیحات پاپ‌اور استفاده می‌شود.

پراپ (Prop)نوع (Type)پیش‌فرض (Default)توضیحات (Description)
classNamestring-کلاس‌های 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}