پرتوپرتو

پاپ‌اور (Popover)

کامپوننت نمایش محتوای شناور

معرفی

کامپوننت Popover برای نمایش محتوای غنی در یک پنجره شناور که روی محتوای اصلی قرار می‌گیرد استفاده می‌شود.

استفاده

import {
  Popover,
  PopoverContent,
  PopoverTrigger,
  Button,
  Separator,
} from '@parto/ui';

<Popover>
  <PopoverTrigger asChild>
    <Button variant="outline">فیلترها</Button>
  </PopoverTrigger>
  <PopoverContent className="w-64" align="start">
    <div className="space-y-2">
      <h4 className="font-medium">محدوده تاریخ</h4>
      <p className="text-sm text-muted-foreground">یک بازه زمانی انتخاب کنید.</p>
    </div>
    <Separator className="my-3" />
    <div className="grid grid-cols-2 gap-2 text-sm">
      <Button variant="outline" size="sm">امروز</Button>
      <Button variant="outline" size="sm">این هفته</Button>
      <Button variant="outline" size="sm">این ماه</Button>
      <Button variant="outline" size="sm">امسال</Button>
    </div>
  </PopoverContent>
</Popover>

با فرم

<Popover>
  <PopoverTrigger asChild>
    <Button variant="outline">تنظیمات</Button>
  </PopoverTrigger>
  <PopoverContent className="w-80">
    <div className="grid gap-4">
      <div className="space-y-2">
        <h4 className="font-medium">ابعاد</h4>
        <p className="text-sm text-muted-foreground">
          تنظیم عرض و ارتفاع
        </p>
      </div>
      <div className="grid gap-2">
        <div className="grid grid-cols-3 items-center gap-4">
          <label htmlFor="width">عرض</label>
          <Input
            id="width"
            defaultValue="100%"
            className="col-span-2 h-8"
          />
        </div>
        <div className="grid grid-cols-3 items-center gap-4">
          <label htmlFor="height">ارتفاع</label>
          <Input
            id="height"
            defaultValue="25px"
            className="col-span-2 h-8"
          />
        </div>
      </div>
    </div>
  </PopoverContent>
</Popover>

کنترل شده

const [open, setOpen] = React.useState(false);

<Popover open={open} onOpenChange={setOpen}>
  <PopoverTrigger asChild>
    <Button variant="outline">منو</Button>
  </PopoverTrigger>
  <PopoverContent>
    <div className="space-y-2">
      <p>محتوای کنترل شده</p>
      <Button onClick={() => setOpen(false)}>بستن</Button>
    </div>
  </PopoverContent>
</Popover>

تنظیم موقعیت

<Popover>
  <PopoverTrigger>باز کردن</PopoverTrigger>
  <PopoverContent side="bottom" align="start">
    <p>نمایش در پایین، تراز راست</p>
  </PopoverContent>
</Popover>

با لیست

<Popover>
  <PopoverTrigger asChild>
    <Button variant="outline">گزینه‌ها</Button>
  </PopoverTrigger>
  <PopoverContent className="w-56">
    <div className="space-y-1">
      <Button variant="ghost" className="w-full justify-start">
        گزینه ۱
      </Button>
      <Button variant="ghost" className="w-full justify-start">
        گزینه ۲
      </Button>
      <Button variant="ghost" className="w-full justify-start">
        گزینه ۳
      </Button>
    </div>
  </PopoverContent>
</Popover>

ترکیب کامپوننت‌ها

Popover از اجزای زیر تشکیل شده است:

  • Popover: کانتینر اصلی و مدیریت state
  • PopoverTrigger: المنت trigger کننده
  • PopoverContent: محتوای popover

Props

Popover

PropTypeDefaultDescription
openboolean-کنترل وضعیت باز/بسته
defaultOpenbooleanfalseوضعیت پیش‌فرض
onOpenChange(open: boolean) => void-callback تغییر وضعیت
modalbooleanfalseحالت modal

PopoverContent

PropTypeDefaultDescription
side'top' | 'right' | 'bottom' | 'left''bottom'موقعیت نمایش
align'start' | 'center' | 'end''center'تراز محتوا
sideOffsetnumber4فاصله از trigger
alignOffsetnumber0جابجایی تراز

دسترسی‌پذیری

  • با Escape بسته می‌شود
  • کلیک خارج popover آن را می‌بندد
  • از role="dialog" استفاده می‌شود
  • aria-haspopup به trigger اضافه می‌شود
  • Focus management مناسب

تفاوت با Tooltip

ویژگیTooltipPopover
محتواکوتاه، متنیغنی، تعاملی
TriggerHover/FocusClick
کاربردراهنمافرم، منو، محتوا

ملاحظات RTL

  • موقعیت‌ها در RTL به‌درستی تنظیم می‌شوند
  • محتوا راست‌چین می‌شود
  • align="start" در RTL به راست اشاره می‌کند
  • فاصله‌گذاری با Logical Properties

نکات استفاده

  • برای محتوای تعاملی از Popover استفاده کنید
  • برای راهنمای ساده از Tooltip استفاده کنید
  • مطمئن شوید popover در موبایل هم کاربردی است
  • از حالت modal برای عملیات مهم استفاده کنید