راهنما (Tooltip)
کامپوننت نمایش راهنمای کوتاه هنگام hover
معرفی
کامپوننت Tooltip برای نمایش اطلاعات توضیحی کوتاه هنگام hover یا focus روی یک المنت استفاده میشود.
چه زمانی استفاده کنیم:
- برای توضیح آیکوندکمهها (icon-only buttons) که بدون متن هستند
- برای نمایش متن کامل المنتهایی که truncate شدهاند
- برای راهنمای کوتاه (یک جمله) درباره عملکرد یک المنت
چه زمانی استفاده نکنیم:
- برای محتوای تعاملی (لینک، دکمه) داخل tooltip — از
Popoverاستفاده کنید - در رابطهای موبایلاول — tooltip روی touch کار نمیکند
- برای اطلاعات ضروری — کاربر نباید مجبور باشد hover کند تا اطلاعات ببیند
استفاده
import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, Button } from '@parto-system-design/ui'
;<TooltipProvider>
<Tooltip>
<TooltipTrigger asChild>
<Button variant="outline">راهنما</Button>
</TooltipTrigger>
<TooltipContent>
<p>این یک راهنمای ابزار است</p>
</TooltipContent>
</Tooltip>
</TooltipProvider>زمین بازی
با تغییر تنظیمات زیر، راهنما را به صورت زنده مشاهده کنید.
زمین بازی
تنظیمات
import { Tooltip } from '@parto-system-design/ui'
<Tooltip />حالتها و انواع
پیشفرض
انواع ظاهری
<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 '@parto-system-design/ui'
;<TooltipProvider>
<Tooltip>
<TooltipTrigger asChild>
<Button variant="ghost" size="icon">
<Icons.info className="h-4 w-4" />
</Button>
</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>با تاخیر ۳۰۰ میلیثانیه</p>
</TooltipContent>
</Tooltip>
</TooltipProvider>محتوای پیچیده
<Tooltip>
<TooltipTrigger>اطلاعات</TooltipTrigger>
<TooltipContent className="max-w-xs">
<div className="space-y-2">
<p className="font-semibold">عنوان</p>
<p className="text-sm">این یک راهنمای ابزار با محتوای پیچیدهتر است که میتواند شامل چندین خط متن باشد.</p>
</div>
</TooltipContent>
</Tooltip>ترکیب کامپوننتها
Tooltip از اجزای زیر تشکیل شده است:
- TooltipProvider: کانتینر برای مدیریت تنظیمات کلی
- Tooltip: کانتینر اصلی tooltip
- TooltipTrigger: المنت trigger کننده
- TooltipContent: محتوای tooltip
راهنمای استفاده
بکنید
- از Tooltip برای اطلاعات کوتاه و غیر ضروری استفاده کنید - همیشه
TooltipProviderرا در بالای درخت کامپوننت قرار دهید - برای المنتهایی که فقط آیکون دارند حتماً Tooltip ارائه دهید
نکنید
- اطلاعات ضروری را فقط در Tooltip قرار ندهید — کاربر نباید مجبور به hover باشد - محتوای تعاملی (لینک، دکمه) داخل
Tooltip قرار ندهید — از
Popoverاستفاده کنید - در رابطهای لمسی (mobile-first) به Tooltip تکیه نکنید — روی touch کار نمیکند
جدول ویژگیها
TooltipProvider
Tooltip
TooltipContent
دسترسیپذیری
- با focus کیبورد نمایش داده میشود
- با Escape بسته میشود
- از
role="tooltip"استفاده میشود aria-describedbyبه trigger اضافه میشود- برای screen readers قابل دسترسی است
ملاحظات RTL
- موقعیتهای
rightوleftدر RTL معکوس میشوند - محتوا بهصورت خودکار راستچین میشود
- فاصلهگذاری با Logical Properties