راهنما (Tooltip)
کامپوننت نمایش راهنمای کوتاه هنگام hover
معرفی
کامپوننت Tooltip برای نمایش اطلاعات توضیحی کوتاه هنگام hover یا focus روی یک المنت استفاده می‌شود.
چه زمانی استفاده کنیم:
- برای توضیح آیکون‌دکمه‌ها (icon-only buttons) که بدون متن هستند
- برای نمایش متن کامل المنت‌هایی که truncate شده‌اند
- برای راهنمای کوتاه (یک جمله) درباره عملکرد یک المنت
چه زمانی استفاده نکنیم:
- برای محتوای تعاملی (لینک، دکمه) داخل tooltip — از
Popoverاستفاده کنید - در رابط‌های موبایل‌اول — tooltip روی touch کار نمی‌کند
- برای اطلاعات ضروری — کاربر نباید مجبور باشد hover کند تا اطلاعات ببیند
استفاده
import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, Button } from '@partodata/ui'
;<TooltipProvider>
<Tooltip>
<TooltipTrigger asChild>
<Button variant="outline">راهنما</Button>
</TooltipTrigger>
<TooltipContent>
<p>این یک راهنمای ابزار است</p>
</TooltipContent>
</Tooltip>
</TooltipProvider>زمین بازی
با تغییر تنظیمات زیر، راهنما را به صورت زنده مشاهده کنید.
import { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider, Button } from '@partodata/ui'
<TooltipProvider delayDuration={200}>
<Tooltip>
<TooltipTrigger asChild>
<Button type="outline">روی من هاور کنید</Button>
</TooltipTrigger>
<TooltipContent variant="default" size="sm" side="top" align="center">
<p>این یک راهنمای ابزار است</p>
</TooltipContent>
</Tooltip>
</TooltipProvider>حالت‌ها و انواع
پیش‌فرض
انواع ظاهری
<div className="flex gap-4">
<Tooltip>
<TooltipTrigger asChild>
<Button variant="outline">پیش‌فرض</Button>
</TooltipTrigger>
<TooltipContent variant="default">تولتیپ پیش‌فرض</TooltipContent>
</Tooltip>
<Tooltip>
<TooltipTrigger asChild>
<Button variant="outline">روشن</Button>
</TooltipTrigger>
<TooltipContent variant="light">تولتیپ روشن</TooltipContent>
</Tooltip>
<Tooltip>
<TooltipTrigger asChild>
<Button variant="outline">خطا</Button>
</TooltipTrigger>
<TooltipContent variant="error">تولتیپ خطا</TooltipContent>
</Tooltip>
</div>با آیکون
import { Icons } from '@partodata/ui/icons'
;<TooltipProvider>
<Tooltip>
<TooltipTrigger asChild>
<Button variant="ghost" icon={<Icons.info className="h-4 w-4" />} aria-label="اطلاعات" />
</TooltipTrigger>
<TooltipContent>
<p>اطلاعات بیشتر</p>
</TooltipContent>
</Tooltip>
</TooltipProvider>تنظیم موقعیت
<Tooltip>
<TooltipTrigger>راهنما</TooltipTrigger>
<TooltipContent side="bottom">
<p>نمایش در پایین</p>
</TooltipContent>
</Tooltip>موقعیت‌های ممکن: top, right, bottom, left
با تاخیر سفارشی
<TooltipProvider delayDuration={300}>
<Tooltip>
<TooltipTrigger>راهنما</TooltipTrigger>
<TooltipContent>
<p>با تاخیر 300 میلی‌ثانیه</p>
</TooltipContent>
</Tooltip>
</TooltipProvider>محتوای پیچیده
<Tooltip>
<TooltipTrigger>اطلاعات</TooltipTrigger>
<TooltipContent className="max-w-xs">
<div className="space-y-2">
<p className="font-medium">عنوان</p>
<p className="text-sm">این یک راهنمای ابزار با محتوای پیچیده‌تر است که می‌تواند شامل چندین خط متن باشد.</p>
</div>
</TooltipContent>
</Tooltip>ترکیب کامپوننت‌ها
Tooltip از اجزای زیر تشکیل شده است:
- TooltipProvider: کانتینر برای مدیریت تنظیمات کلی
- Tooltip: کانتینر اصلی tooltip
- TooltipTrigger: المنت trigger کننده
- TooltipContent: محتوای tooltip
روی کنترل‌های غیرفعال
یک دکمه disabled در DS با disabled:pointer-events-none هیچ رویداد pointerای دریافت نمی‌کند و در tab
order هم قرار نمی‌گیرد، بنابراین Tooltip روی آن هرگز باز نمی‌شود — دقیقاً همان لحظه‌ای که «چرا این دکمه
غیرفعال است؟» بیشترین ارزش را دارد. برای رفع این مشکل، TooltipTrigger با wrapDisabled کنترل (هنوز
غیرفعال) را در یک <span> قابل focus می‌پیچد تا رویدادهای hover/focus به جای کنترل غیرفعال، به آن span برسند:
<Tooltip>
<TooltipTrigger asChild wrapDisabled>
<Button disabled>خروجی گرفتن</Button>
</TooltipTrigger>
<TooltipContent>سهمیه خروجی این ماه تمام شده است</TooltipContent>
</Tooltip>بدون wrapDisabled، این الگو باید دستی پیاده‌سازی شود.
اقدام صفحه‌ای که کاربر اجازه‌اش را ندارد: GatedAction
برای اقدامی در جایگاه‌های اقدام قالب صفحه (primaryAction، secondaryActions، actions یک بخش، اقدام‌های گروهی)
این ترکیب را دستی نسازید: GatedAction (<GatedAction allowed={canCreate} reason="…"> دور Button) همان دکمهٔ غیرفعال با دلیل را می‌سازد، دکمه را با aria-disabled در ترتیب Tab نگه
می‌دارد، دلیل را به‌عنوان توضیح دکمه می‌خواند و با لمس هم نشان می‌دهد.
راهنمای استفاده
بکنید
- از Tooltip برای اطلاعات کوتاه و غیر ضروری استفاده کنید - همیشه
TooltipProviderرا در بالای درخت کامپوننت قرار دهید - برای المنت‌هایی که فقط آیکون دارند حتماً Tooltip ارائه دهید - برای توضیح دلیل غیرفعال بودن یک کنترل، از
wrapDisabledرویTooltipTriggerاستفاده کنید
نکنید
- اطلاعات ضروری را فقط در Tooltip قرار ندهید — کاربر نباید مجبور به hover باشد - محتوای تعاملی (لینک، دکمه) داخل
Tooltip قرار ندهید — از
Popoverاستفاده کنید - در رابط‌های لمسی (mobile-first) به Tooltip تکیه نکنید — روی touch کار نمی‌کند - یکTooltipTriggerرا روی کنترل غیرفعال بدونwrapDisabledقرار ندهید — tooltip هرگز باز نمی‌شود
جدول ویژگی‌ها
TooltipProvider
Tooltip
TooltipTrigger
TooltipContent
دسترسی‌پذیری
- با focus کیبورد نمایش داده می‌شود
- با Escape بسته می‌شود
- از
role="tooltip"استفاده می‌شود aria-describedbyبه trigger اضافه می‌شود- برای screen readers قابل دسترسی است
ملاحظات RTL
- موقعیت‌های
rightوleftدر RTL معکوس می‌شوند - محتوا به‌صورت خودکار راست‌چین می‌شود
- فاصله‌گذاری با Logical Properties