پاپاور (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
PopoverContent
دسترسیپذیری
- با Escape بسته میشود
- کلیک خارج popover آن را میبندد
- از
role="dialog"استفاده میشود aria-haspopupبه trigger اضافه میشود- Focus management مناسب
تفاوت با Tooltip
| ویژگی | Tooltip | Popover |
|---|---|---|
| محتوا | کوتاه، متنی | غنی، تعاملی |
| Trigger | Hover/Focus | Click |
| کاربرد | راهنما | فرم، منو، محتوا |
ملاحظات RTL
- موقعیتها در RTL بهدرستی تنظیم میشوند
- محتوا راستچین میشود
align="start"در RTL به راست اشاره میکند- فاصلهگذاری با Logical Properties
کامپوننتهای مرتبط
- DropdownMenu — وقتی محتوا لیست اکشنها است (منوی عملیات)
- Tooltip — وقتی فقط یک متن کوتاه توضیحی بدون تعامل نیاز دارید
- HoverCard — وقتی میخواهید preview غنی با hover نمایش دهید (بدون نیاز به کلیک)