پرتوپرتو

راهنما (Tooltip)

کامپوننت نمایش راهنمای کوتاه هنگام hover

معرفی

کامپوننت Tooltip برای نمایش اطلاعات توضیحی کوتاه هنگام hover یا focus روی یک المنت استفاده می‌شود.

استفاده

import {
  Tooltip,
  TooltipContent,
  TooltipProvider,
  TooltipTrigger,
  Button,
} from '@parto/ui';

<TooltipProvider>
  <Tooltip>
    <TooltipTrigger asChild>
      <Button variant="outline">راهنما</Button>
    </TooltipTrigger>
    <TooltipContent>
      <p>این یک راهنمای ابزار است</p>
    </TooltipContent>
  </Tooltip>
</TooltipProvider>

با آیکون

import { Icons } from '@parto/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

Props

TooltipProvider

PropTypeDefaultDescription
delayDurationnumber700تاخیر نمایش به میلی‌ثانیه
skipDelayDurationnumber300تاخیر بین tooltips

Tooltip

PropTypeDefaultDescription
openboolean-کنترل وضعیت باز/بسته
defaultOpenbooleanfalseوضعیت پیش‌فرض
onOpenChange(open: boolean) => void-callback تغییر وضعیت

TooltipContent

PropTypeDefaultDescription
side'top' | 'right' | 'bottom' | 'left''top'موقعیت نمایش
align'start' | 'center' | 'end''center'تراز محتوا
sideOffsetnumber4فاصله از trigger

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

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

ملاحظات RTL

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

نکات استفاده

  • از Tooltip برای اطلاعات کوتاه استفاده کنید
  • برای محتوای طولانی از Popover استفاده کنید
  • اطمینان حاصل کنید محتوا با کیبورد قابل دسترسی است
  • از Tooltip برای المنت‌هایی که فقط آیکون دارند استفاده کنید