Hover Card
کارتی که با توقف نشانگر روی یک لینک باز میشود و پیشنمایشی از مقصد نشان میدهد. محتوایش میتواند غنی باشد (تصویر، آمار، دکمه) ولی چون فقط با ماوس باز میشود، هیچ اطلاعات ضروریای نباید تنها اینجا باشد.
این کامپوننت فعلاً برای ۱ فریمورک از ۴ فریمورک آماده است.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
نصب
با CLI اختصاصی dig-ui کامپوننت را از رجیستری دیگ نصب کنید؛ وابستگیها و فایلها خودکار اضافه میشوند.
pnpm dlx dig-ui@latest add https://design-system-tau-green.vercel.app/r/hover-card.jsonnpx dig-ui@latest add https://design-system-tau-green.vercel.app/r/hover-card.jsonyarn dlx dig-ui@latest add https://design-system-tau-green.vercel.app/r/hover-card.jsonbunx --bun dig-ui@latest add https://design-system-tau-green.vercel.app/r/hover-card.jsonاین کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Reka UI در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Bits UI در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Angular CDK در دست کار است.
استفاده
import {
HoverCard,
HoverCardContent,
HoverCardTrigger,
} from "@/components/ui/hover-card"
<HoverCard>
<HoverCardTrigger asChild>
<a href="/profile">پروفایل</a>
</HoverCardTrigger>
<HoverCardContent>پیشنمایش پروفایل</HoverCardContent>
</HoverCard>این کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Reka UI در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Bits UI در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Angular CDK در دست کار است.
ترکیب اجزا
دسترسپذیری
- کارت با فوکوس صفحهکلید روی تریگر هم باز میشود، ولی فوکوس داخل کارت منتقل نمیشود؛ پس دکمههای داخلش با Tab در دسترس نیستند.
- هیچ اطلاعات ضروریای را فقط اینجا نگذارید؛ کاربر لمسی و کاربر صفحهخوان ممکن است هرگز آن را نبینند.
- تریگر باید خودش یک عنصر تعاملی معنادار باشد (لینک یا دکمه) تا در ناوبری صفحهکلید جا داشته باشد.
- برای متن کوتاه توضیحی از راهنمای ابزار و برای محتوای تعاملی از پاپاور استفاده کنید؛ کارت شناور بین این دو است.
- openDelay را خیلی کوتاه نکنید؛ باز شدن ناگهانی کارت هنگام عبور ماوس آزاردهنده و برای کاربران با اختلال حرکتی گیجکننده است.
مرجع API
HoverCard
| ویژگی | نوع | پیشفرض | توضیح |
|---|---|---|---|
| openDelay | number | 200 | میلیثانیه مکث نشانگر تا باز شدن کارت؛ صفر یعنی فوری. |
| closeDelay | number | 100 | مهلت بستن بعد از خروج نشانگر؛ فرصت میدهد ماوس روی خود کارت برود. |
| open / onOpenChange | boolean / (open: boolean) => void | — | مدیریت کنترلشدهٔ باز و بسته بودن. |
| defaultOpen | boolean | false | باز بودن در اولین رندر. |
HoverCardTrigger
| ویژگی | نوع | پیشفرض | توضیح |
|---|---|---|---|
| asChild | boolean | false | رفتار تریگر را به فرزند میدهد؛ معمولاً یک لینک یا دکمه. |
HoverCardContent
| ویژگی | نوع | پیشفرض | توضیح |
|---|---|---|---|
| side | "top" | "right" | "bottom" | "left" | "bottom" | جهت ترجیحی باز شدن؛ در نبود فضا خودکار برعکس میشود. |
| align | "start" | "center" | "end" | "center" | ترازِ کارت نسبت به تریگر؛ در حالت rtl مقدار start یعنی سمت راست. |
| sideOffset | number | 4 | فاصلهٔ کارت از تریگر بر حسب پیکسل. |
| collisionPadding | number | Padding | 0 | حاشیهٔ امن از لبههای صفحه هنگام محاسبهٔ موقعیت. |
| className | string | — | عرض پیشفرض w-64 است؛ برای محتوای بیشتر بازنویسی کنید. |
این کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Reka UI در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Bits UI در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Angular CDK در دست کار است.
نمونهها
Repository Preview
پیشنمایش یک مخزن با آمار؛ اعداد با ارقام فارسی قالببندی شدهاند.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
Inline in Text
رایجترین کاربرد: توضیح یک اصطلاح یا نام داخل متن، بدون بیرون بردن کاربر از جریان خواندن.
این پروژه با پریمیتیوهای دیگ ساخته شده تا مدیریت فوکوس و ناوبری با صفحهکلید از پایه درست باشد.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
Delay and Position
openDelay و closeDelay سرعت واکنش را تنظیم میکنند و side جهت باز شدن را.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
روی لمس باز نمیشود
HoverCard فقط با نشانگر باز میشود. اگر اطلاعاتی فقط اینجا باشد، کاربر موبایل و کاربر کیبورد هرگز آن را نمیبینند. تریگر را قابل کلیک و فوکوس بگذارید و همان اطلاعات را جای دیگری هم در دسترس بگذارید.
نادرست: روی موبایل هیچوقت دیده نمیشود
درست: تریگر قابل کلیک و فوکوس است و همان اطلاعات جای دیگری هم هست
این نمونه هنوز برای Vue پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
در حال دریافت (Loading)
کارت را خالی باز نکنید. جای خالیِ هماندازه بگذارید تا موقع رسیدن داده، کارت جابهجا نشود و اندازهاش نپرد.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
کدام نمونه برای کدام موقعیت
| نمونه | کجا به کار میآید |
|---|---|
| Repository Preview | پیشنمایش یک مخزن با آمار؛ اعداد با ارقام فارسی قالببندی شدهاند. |
| Inline in Text | رایجترین کاربرد: توضیح یک اصطلاح یا نام داخل متن، بدون بیرون بردن کاربر از جریان خواندن. |
| Delay and Position | openDelay و closeDelay سرعت واکنش را تنظیم میکنند و side جهت باز شدن را. |
| روی لمس باز نمیشود | هر پیشنمایشی که کاربر موبایل هم باید ببیند |
| در حال دریافت (Loading) | پیشنمایش کاربر یا لینک که با باز شدن کارت گرفته میشود |
دستورالعمل استفاده
بدون عمل حیاتی که فقط با هاور در دسترس باشد
انجام بده
کارت فقط یک پیشنمایش است؛ تریگر خودش یک لینک واقعی به مقصد کامل است، پس کاربر لمسی و صفحهخوان هم با فعالکردن همان لینک به اطلاعات کامل میرسند.
انجام نده
دکمهٔ «دنبال کردن» را فقط داخل محتوای کارت نگذارید؛ چون فوکوس داخل کارت نمیرود، این دکمه با کیبورد قابل تبزدن نیست و کاربر لمسی هم که کارت را باز نمیبیند، هرگز به آن نمیرسد.
برای متن کوتاه از راهنمای ابزار، نه کارت شناور
انجام بده
برای یک جملهٔ کوتاه توضیحی، Tooltip سبکتر و سریعتر است؛ کارت شناور را برای پیشنمایش غنی (تصویر، آمار، چند خط متن) نگه دارید.
انجام نده
استفاده از کارت شناور برای یک عبارت کوتاه، هم بهخاطر تأخیر پیشفرض دیرتر باز میشود و هم قاب و فاصلهٔ اضافهاش برای یک خط متن اندازهاش بیش از حد است.
openDelay متناسب با حجم محتوا
انجام بده
برای کارتهای پرمحتوا (پروفایل، آمار مخزن) از تأخیر پیشفرض یا بیشتر استفاده کنید تا عبور اتفاقی ماوس هر بار یک کارت بزرگ باز نکند.
انجام نده
openDelay={0} روی یک کارت پرمحتوا یعنی هر عبور سادهی ماوس روی لینک، بلافاصله یک بلوک بزرگ باز میکند؛ برای این حجم محتوا آزاردهنده است.