Tooltipv1.0.0
توضیحی کوتاه که با توقف نشانگر یا فوکوس صفحه‌کلید روی یک عنصر ظاهر می‌شود.
این کامپوننت فعلاً برای ۱ فریم‌ورک از ۴ فریم‌ورک آماده است.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
نصب
با CLI اختصاصی digdesign کامپوننت را از رجیستری دیگ نصب کنید؛ وابستگی‌ها و فایل‌ها خودکار اضافه می‌شوند.
npx digdesign@latest add https://docs.digdesign.ir/r/tooltip.jsonpnpm dlx digdesign@latest add https://docs.digdesign.ir/r/tooltip.jsonyarn dlx digdesign@latest add https://docs.digdesign.ir/r/tooltip.jsonbunx --bun digdesign@latest add https://docs.digdesign.ir/r/tooltip.jsonاین کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
استفاده
import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip"
<Tooltip>
<TooltipTrigger>راهنما</TooltipTrigger>
<TooltipContent>توضیح بیشتر</TooltipContent>
</Tooltip>این کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
دسترس‌پذیری
- با فوکوس صفحه‌کلید هم باز می‌شود و با Escape بسته می‌شود.
- راهنمای ابزار جایگزین برچسب نیست؛ برای دکمه‌های آیکونی همچنان aria-label بگذارید.
مرجع API
TooltipContent
| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| side | "top" | "right" | "bottom" | "left" | "top" | سمت نمایش نسبت به عنصر مبدأ. |
| sideOffset | number | 4 | فاصله از عنصر مبدأ به پیکسل. |
این کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
نمونه‌ها
روی کنترل غیرفعال (Disabled)
دکمهٔ غیرفعال رویداد ماوس نمی‌فرستد، پس تولتیپ رویش هرگز باز نمی‌شود. اگر می‌خواهید دلیلِ غیرفعال‌بودن را بگویید، یک پوششِ قابل‌فوکوس دور دکمه بگذارید و آن را تریگر کنید.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
با صفحه‌کلید (Focus)
تولتیپ فقط برای ماوس نیست. با رسیدن فوکوس هم باز می‌شود و با Escape بسته. اگر محتوایی فقط با هاور در دسترس باشد، کاربر کیبورد و لمس آن را هرگز نمی‌بیند. نکتهٔ ترکیب: onFocus را روی فرزندِ asChild ندهید، چون هندلر خودِ TooltipTrigger را بازنویسی می‌کند و تولتیپ دیگر با فوکوس باز نمی‌شود.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
جهت‌ها (Side)
جهت‌ها فیزیکی‌اند نه منطقی: در راست‌به‌چپ، right همان سمتِ شروع صفحه است. برخلاف Sidebar که side="start" می‌گیرد، اینجا باید فیزیکی فکر کنید.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
متن بلند (Overflow)
تولتیپ برای متن کوتاه است. اگر ناچار به متن بلندترید، عرض بیشینه بدهید تا بشکند؛ وگرنه یک خطِ دراز از لبهٔ صفحه بیرون می‌زند. متن بلندتر از دو خط یعنی جایش تولتیپ نیست.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
کدام نمونه برای کدام موقعیت
| نمونه | کجا به کار می‌آید |
|---|---|
| روی کنترل غیرفعال (Disabled) | دکمهٔ تاییدی که تا تکمیل فرم غیرفعال است |
| با صفحه‌کلید (Focus) | پنل‌هایی که کاربرشان با کیبورد کار می‌کند |
| جهت‌ها (Side) | آیکون کنار لبهٔ صفحه یا داخل ردیف جدول |
| متن بلند (Overflow) | وقتی توضیح از یک خط بیشتر می‌شود |
دستورالعمل استفاده
فقط متن کوتاه و مکمل
انجام بده
TooltipContent برای یک عبارت کوتاه ساخته شده (پس‌زمینهٔ کوچک، متن text-xs)؛ همان چیزی که با یک نگاه خوانده می‌شود.
انجام نده
اطلاعات ضروری یا قابل‌اقدام (مثل شرایط یک خطا یا مراحل بعدی) را داخل تولتیپ جا ندهید؛ چون فقط با هاور یا فوکوس صفحه‌کلید دیده می‌شود و در تاچ اصلاً در دسترس نیست.
aria-label جدا از تولتیپ، نه جایگزین آن
انجام بده
روی دکمهٔ فقط‌آیکونی هم aria-label بگذارید هم TooltipContent؛ صفحه‌خوان از aria-label نام دکمه را می‌گوید، تولتیپ فقط برای کاربر دیداری است.
انجام نده
اگر aria-label را حذف کنید و فقط به TooltipContent تکیه کنید، صفحه‌خوانی که تولتیپ را دنبال نمی‌کند دکمه را بی‌نام اعلام می‌کند.