پرتوپرتو

راهنما (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

Prop

Type

Tooltip

Prop

Type

TooltipContent

Prop

Type

دسترسی‌پذیری

  • با focus کیبورد نمایش داده می‌شود
  • با Escape بسته می‌شود
  • از role="tooltip" استفاده می‌شود
  • aria-describedby به trigger اضافه می‌شود
  • برای screen readers قابل دسترسی است

ملاحظات RTL

  • موقعیت‌های right و left در RTL معکوس می‌شوند
  • محتوا به‌صورت خودکار راست‌چین می‌شود
  • فاصله‌گذاری با Logical Properties

کامپوننت‌های مرتبط

  • Popover — وقتی محتوا تعاملی است (لینک، دکمه، فرم) و با کلیک باز می‌شود
  • HoverCard — وقتی می‌خواهید preview غنی (آواتار، بیو، آمار) نمایش دهید نه فقط متن ساده