دیگ

Popoverv1.0.0

پنلی شناور که با کلیک باز می‌شود و برخلاف راهنمای ابزار، محتوای تعاملی می‌پذیرد: ورودی، کلید، دکمه. موقعیتش خودکار طوری تنظیم می‌شود که از لبهٔ صفحه بیرون نزند.

شبیه به این هم هست:DialogSheetDrawerکدام را انتخاب کنم؟
ری‌اکت ۱۹ و Next.js با پیاده‌سازی دسترس‌پذیری داخلی دیگویو ۳ با Composition API — هنوز برای این کامپوننت پورت نشدهSvelte ۵ با runes — هنوز برای این کامپوننت پورت نشدهانگولار با signals و دایرکتیوهای standalone — هنوز برای این کامپوننت پورت نشده

این کامپوننت فعلاً برای ۱ فریم‌ورک از ۴ فریم‌ورک آماده است.

این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.

این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.

این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.

نصب

با CLI اختصاصی digdesign کامپوننت را از رجیستری دیگ نصب کنید؛ وابستگی‌ها و فایل‌ها خودکار اضافه می‌شوند.

پکیج‌منیجر پیش‌فرض Node.jsنصب سریع با لینک سخت و دیسک مشترکYarn نسخهٔ ۲ به بالا (Berry)رانتایم و پکیج‌منیجر Bun
npx digdesign@latest add https://docs.digdesign.ir/r/popover.json
pnpm dlx digdesign@latest add https://docs.digdesign.ir/r/popover.json
yarn dlx digdesign@latest add https://docs.digdesign.ir/r/popover.json
bunx --bun digdesign@latest add https://docs.digdesign.ir/r/popover.json

این کامپوننت هنوز برای Vue پورت نشده است.

نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.

این کامپوننت هنوز برای Svelte پورت نشده است.

نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.

این کامپوننت هنوز برای Angular پورت نشده است.

نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.

استفاده

import {
  Popover,
  PopoverContent,
  PopoverTrigger,
} from "@/components/ui/popover"

<Popover>
  <PopoverTrigger asChild>
    <Button variant="outline">باز کردن</Button>
  </PopoverTrigger>
  <PopoverContent>محتوای پنل</PopoverContent>
</Popover>

این کامپوننت هنوز برای Vue پورت نشده است.

نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.

این کامپوننت هنوز برای Svelte پورت نشده است.

نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.

این کامپوننت هنوز برای Angular پورت نشده است.

نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.

ترکیب اجزا

PopoverTrigger با asChild روی دکمهٔ خودتان می‌نشیند تا دکمهٔ تودرتو ساخته نشود.

PopoverContent داخل یک Portal انتهای body رندر می‌شود، پس overflow: hidden والدها آن را نمی‌بُرد.

برای مواقعی که دکمهٔ بازکننده و نقطهٔ لنگر یکی نیستند (مثلاً منویی که باید نسبت به یک فیلد باز شود) PopoverAnchor را جای دیگری بگذارید؛ محاسبهٔ موقعیت روی anchor انجام می‌شود و trigger فقط باز و بسته می‌کند.

PopoverClose هم هر عنصری را به دکمهٔ بستن تبدیل می‌کند.

دسترس‌پذیری

  • پنل با Escape و با کلیک بیرون بسته می‌شود و فوکوس به دکمهٔ باز کننده برمی‌گردد.
  • هنگام باز شدن، فوکوس داخل پنل می‌رود و تا زمان بسته شدن داخلش می‌ماند؛ پس ورودی‌های داخل پاپ‌اور با Tab قابل پیمایش‌اند.
  • aria-expanded و aria-controls روی تریگر خودکار ست می‌شود؛ اگر تریگر فقط آیکون است، حتماً aria-label بدهید.
  • برای متن راهنمای صرفاً توضیحی از راهنمای ابزار استفاده کنید نه پاپ‌اور؛ محتوای پاپ‌اور تا باز نشود خوانده نمی‌شود.
  • align و side منطقی نیستند بلکه فیزیکی‌اند، ولی موتور موقعیت‌دهی دیگ در حالت rtl مقدار start و end را خودش برعکس می‌کند؛ در نتیجه align="start" همیشه یعنی «هم‌تراز با ابتدای دکمه».

مرجع API

Popover

ویژگینوعپیش‌فرضتوضیح
open / onOpenChangeboolean / (open: boolean) => void—مدیریت کنترل‌شدهٔ باز و بسته بودن.
defaultOpenbooleanfalseباز بودن در اولین رندر.
modalbooleanfalseدر حالت true تعامل با بقیهٔ صفحه بسته می‌شود و اسکرول قفل می‌ماند.

PopoverTrigger

ویژگینوعپیش‌فرضتوضیح
asChildbooleanfalseرفتار تریگر را به فرزند می‌دهد؛ برای اینکه Button تودرتو نشود همیشه با Button از این استفاده کنید.

PopoverContent

ویژگینوعپیش‌فرضتوضیح
side"top" | "right" | "bottom" | "left""bottom"جهت ترجیحی باز شدن؛ اگر فضا نباشد خودکار برعکس می‌شود.
align"start" | "center" | "end""center"ترازِ پنل نسبت به تریگر. در حالت rtl مقدار start یعنی سمت راست.
sideOffsetnumber4فاصله (پیکسل) بین پنل و تریگر.
showArrowbooleanfalseنمایش فلش کوچک بین پنل و تریگر.
onOpenAutoFocus(event: Event) => void—با preventDefault می‌توانید جلوی انتقال خودکار فوکوس به پنل را بگیرید.
collisionPaddingnumber | Padding0حاشیهٔ امن از لبه‌های صفحه هنگام محاسبهٔ موقعیت.

PopoverAnchor / PopoverClose

ویژگینوعپیش‌فرضتوضیح
PopoverAnchorComponent—نقطهٔ مرجع موقعیت‌یابی، وقتی با تریگر یکی نیست. اختیاری.
PopoverCloseComponent—هر عنصری را به دکمهٔ بستن تبدیل می‌کند؛ معمولاً با asChild.

این کامپوننت هنوز برای Vue پورت نشده است.

نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.

این کامپوننت هنوز برای Svelte پورت نشده است.

نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.

این کامپوننت هنوز برای Angular پورت نشده است.

نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.