پرتوپرتو

پاپ‌اور (Popover)

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

معرفی

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

چه زمانی استفاده کنیم:

  • برای فرم‌های کوچک (فیلتر، تنظیمات سریع) که نیاز به dialog کامل ندارند
  • برای محتوای تعاملی (لینک‌ها، دکمه‌ها) که با کلیک باز می‌شود
  • برای color picker، date picker، یا سایر ابزارهای انتخابی

چه زمانی استفاده نکنیم:

  • برای منوهای dropdown — از DropdownMenu استفاده کنید
  • برای tooltip های ساده بدون تعامل — از Tooltip استفاده کنید
  • برای dialog های modal — از Dialog استفاده کنید

استفاده

import { Popover, PopoverContent, PopoverTrigger, Button, Separator } from '@parto-system-design/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="space-y-4" dir="rtl">
      <h4 className="font-medium">تنظیمات نمایش</h4>
      <div className="space-y-2">
        <Label>عرض</Label>
        <Input defaultValue="۱۰۰٪" />
      </div>
    </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

راهنمای استفاده

بکنید

  • برای محتوای تعاملی از Popover و برای راهنمای ساده از Tooltip استفاده کنید - از align="start" در RTL استفاده کنید تا محتوا از سمت راست تراز شود - مطمئن شوید popover در موبایل هم قابل استفاده است

نکنید

  • محتوای بسیار بلند (بیش از ۳۰۰px ارتفاع) در Popover قرار ندهید — از Sheet یا Dialog استفاده کنید - Popover های تودرتو ایجاد نکنید - برای منوی dropdown از Popover استفاده نکنید — از DropdownMenu استفاده کنید

جدول ویژگی‌ها

Popover

Prop

Type

PopoverContent

Prop

Type

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

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

تفاوت با Tooltip

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

ملاحظات RTL

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

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

  • DropdownMenu — وقتی محتوا لیست اکشن‌ها است (منوی عملیات)
  • Tooltip — وقتی فقط یک متن کوتاه توضیحی بدون تعامل نیاز دارید
  • HoverCard — وقتی می‌خواهید preview غنی با hover نمایش دهید (بدون نیاز به کلیک)