Popover
پنلی شناور که با کلیک باز میشود و برخلاف راهنمای ابزار، محتوای تعاملی میپذیرد: ورودی، کلید، دکمه. موقعیتش خودکار طوری تنظیم میشود که از لبهٔ صفحه بیرون نزند.
این کامپوننت فعلاً برای ۱ فریمورک از ۴ فریمورک آماده است.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
نصب
با CLI اختصاصی dig-ui کامپوننت را از رجیستری دیگ نصب کنید؛ وابستگیها و فایلها خودکار اضافه میشوند.
pnpm dlx dig-ui@latest add https://design-system-tau-green.vercel.app/r/popover.jsonnpx dig-ui@latest add https://design-system-tau-green.vercel.app/r/popover.jsonyarn dlx dig-ui@latest add https://design-system-tau-green.vercel.app/r/popover.jsonbunx --bun dig-ui@latest add https://design-system-tau-green.vercel.app/r/popover.jsonاین کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Reka UI در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Bits UI در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Angular CDK در دست کار است.
استفاده
import {
Popover,
PopoverContent,
PopoverTrigger,
} from "@/components/ui/popover"
<Popover>
<PopoverTrigger asChild>
<Button variant="outline">باز کردن</Button>
</PopoverTrigger>
<PopoverContent>محتوای پنل</PopoverContent>
</Popover>این کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Reka UI در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Bits UI در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Angular CDK در دست کار است.
ترکیب اجزا
دسترسپذیری
- پنل با Escape و با کلیک بیرون بسته میشود و فوکوس به دکمهٔ باز کننده برمیگردد.
- هنگام باز شدن، فوکوس داخل پنل میرود و تا زمان بسته شدن داخلش میماند؛ پس ورودیهای داخل پاپاور با Tab قابل پیمایشاند.
- aria-expanded و aria-controls روی تریگر خودکار ست میشود؛ اگر تریگر فقط آیکون است، حتماً aria-label بدهید.
- برای متن راهنمای صرفاً توضیحی از راهنمای ابزار استفاده کنید نه پاپاور؛ محتوای پاپاور تا باز نشود خوانده نمیشود.
- align و side منطقی نیستند بلکه فیزیکیاند، ولی موتور موقعیتدهی دیگ در حالت rtl مقدار start و end را خودش برعکس میکند؛ در نتیجه align="start" همیشه یعنی «همتراز با ابتدای دکمه».
مرجع API
Popover
| ویژگی | نوع | پیشفرض | توضیح |
|---|---|---|---|
| open / onOpenChange | boolean / (open: boolean) => void | — | مدیریت کنترلشدهٔ باز و بسته بودن. |
| defaultOpen | boolean | false | باز بودن در اولین رندر. |
| modal | boolean | false | در حالت true تعامل با بقیهٔ صفحه بسته میشود و اسکرول قفل میماند. |
PopoverTrigger
| ویژگی | نوع | پیشفرض | توضیح |
|---|---|---|---|
| asChild | boolean | false | رفتار تریگر را به فرزند میدهد؛ برای اینکه Button تودرتو نشود همیشه با Button از این استفاده کنید. |
PopoverContent
| ویژگی | نوع | پیشفرض | توضیح |
|---|---|---|---|
| side | "top" | "right" | "bottom" | "left" | "bottom" | جهت ترجیحی باز شدن؛ اگر فضا نباشد خودکار برعکس میشود. |
| align | "start" | "center" | "end" | "center" | ترازِ پنل نسبت به تریگر. در حالت rtl مقدار start یعنی سمت راست. |
| sideOffset | number | 4 | فاصله (پیکسل) بین پنل و تریگر. |
| showArrow | boolean | false | نمایش فلش کوچک بین پنل و تریگر. |
| onOpenAutoFocus | (event: Event) => void | — | با preventDefault میتوانید جلوی انتقال خودکار فوکوس به پنل را بگیرید. |
| collisionPadding | number | Padding | 0 | حاشیهٔ امن از لبههای صفحه هنگام محاسبهٔ موقعیت. |
PopoverAnchor / PopoverClose
| ویژگی | نوع | پیشفرض | توضیح |
|---|---|---|---|
| PopoverAnchor | Component | — | نقطهٔ مرجع موقعیتیابی، وقتی با تریگر یکی نیست. اختیاری. |
| PopoverClose | Component | — | هر عنصری را به دکمهٔ بستن تبدیل میکند؛ معمولاً با asChild. |
این کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Reka UI در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Bits UI در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Angular CDK در دست کار است.
نمونهها
Side and Align
side جهت باز شدن نسبت به تریگر است و align ترازِ لبهها؛ اگر جا نباشد موتور موقعیتدهی دیگ خودش جهت را برعکس میکند.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
Profile Card
ترکیب رایج: خلاصهٔ اطلاعات یک کاربر با دکمهٔ اقدام.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
Quick Settings
PopoverClose با asChild هر دکمهای را به دکمهٔ بستن تبدیل میکند.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
پاپاور یا دیالوگ
پاپاور برای یک یا دو فیلدِ وابسته به همان دکمه است و صفحه را قفل نمیکند؛ کاربر میتواند بیخیالش شود. اگر کار چندفیلدی است و باید تمام شود، یا اگر بستنِ تصادفیاش داده را از بین میبرد، جایش دیالوگ است.
پاپاور: یک یا دو فیلد، وابسته به همان دکمه، بدون قفل صفحه
دیالوگ: فرم چندفیلدی که کاربر باید تمامش کند و تمرکز صفحه را میگیرد
این نمونه هنوز برای Vue پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
در حال ذخیره (Loading)
پاپاور با کلیک بیرون بسته میشود؛ وسط ذخیره این را ببندید وگرنه کاربر نمیفهمد کارش انجام شد یا نه. بعد از موفقیت خودتان ببندیدش.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
خالی (Empty)
پاپاور خالی شبیه خرابی است. بگویید چه چیزی قرار است اینجا بیاید و چطور ساخته میشود.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
محتوای بلند (Overflow)
سقف ارتفاع بگذارید و اسکرول را داخل خودِ پاپاور نگه دارید. بدون سقف، پاپاور از صفحه بیرون میزند و روی موبایل عملاً غیرقابل استفاده میشود.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
کدام نمونه برای کدام موقعیت
| نمونه | کجا به کار میآید |
|---|---|
| Side and Align | side جهت باز شدن نسبت به تریگر است و align ترازِ لبهها؛ اگر جا نباشد موتور موقعیتدهی دیگ خودش جهت را برعکس میکند. |
| Profile Card | ترکیب رایج: خلاصهٔ اطلاعات یک کاربر با دکمهٔ اقدام. |
| Quick Settings | PopoverClose با asChild هر دکمهای را به دکمهٔ بستن تبدیل میکند. |
| پاپاور یا دیالوگ | تصمیم اول: این کار صفحه را قفل میکند یا نه |
| در حال ذخیره (Loading) | ویرایش سریعی که نتیجهاش به سرور میرود |
| خالی (Empty) | فهرست برچسبها پیش از ساخت اولین برچسب |
| محتوای بلند (Overflow) | فهرست انتخابی که تعداد گزینههایش از قبل معلوم نیست |
دستورالعمل استفاده
پاپاور برای محتوای تعاملی، نه متن صرفاً توضیحی
انجام بده
وقتی داخل پنل ورودی، کلید یا دکمه دارید، پاپاور درست است؛ چون فوکوس داخلش میرود و با Tab قابل پیمایش است.
انجام نده
یک پاراگراف صرفاً توضیحی بدون هیچ کنترل تعاملی داخل پاپاور جای درستی ندارد؛ چون تا کلیک نکنید باز نمیشود، همان متن با راهنمای ابزار سریعتر و کمهزینهتر منتقل میشود.
دکمهٔ عمل را با PopoverClose ببندید
انجام بده
دکمهٔ نهاییِ فرم داخل پاپاور را با PopoverClose بپوشانید تا بعد از ثبت، پنل خودش بسته شود.
انجام نده
دکمهٔ ذخیرهٔ معمولی بدون PopoverClose، بعد از ثبت پنل را باز نگه میدارد و کاربر باید خودش جای دیگری کلیک کند تا بسته شود.
برچسب دسترسپذیر برای تریگر فقطآیکونی
انجام بده
اگر تریگر فقط یک آیکون است، حتماً aria-label بدهید تا صفحهخوان بگوید این دکمه چهکاری میکند.
انجام نده
دکمهٔ فقطآیکونی بدون aria-label برای صفحهخوان فقط «دکمه» است؛ کاربر نمیفهمد با فعالکردنش چه پنلی باز میشود.