برچسب راهنما — Tooltip

Tooltip یک حباب کوتاه و غیرتعاملی است که با hover یا فوکوس صفحه‌کلید روی یک محرک ظاهر می‌شود، برای نام یک دکمهٔ فقط‌آیکون یا توضیح یک اصطلاح. محتوای آن فوکوس نمی‌گیرد، روی لمس دیده نمی‌شود و بسته به و باز و بسته می‌شود. ساختار حباب، ارتباط با محرک و بستن با ثابت است؛ ظاهر آن فقط از توکن‌های overlay می‌آید.

وضعیت: beta · لایه: ۳ () · کد:

TSX

import { Tooltip } from '@tokapps/tuk';

نمونهٔ زنده

کد قابل کپی

پایه: نام دکمهٔ فقط‌آیکون

TSX

import { Button, Tooltip } from '@tokapps/tuk';import { Icon } from '@tokapps/icons';export function NotificationButton() {  return (    <Tooltip content="اعلان‌ها">      <Button variant="ghost" aria-label="اعلان‌ها" icon={<Icon name="notification" />} />    </Tooltip>  );}

حالت پیشرفته: جهت، تأخیرها و فاصله

TSX

import { Button, Tooltip } from '@tokapps/tuk';export function SaveDraftButton() {  return (    <Tooltip content="ذخیرهٔ پیش‌نویس در این دستگاه" placement="bottom start" delay={300} closeDelay={100} offset={6}>      <Button variant="secondary">ذخیره</Button>    </Tooltip>  );}

حالت غیرفعال: توضیح بدون نمایش

TSX

import { Button, Tooltip } from '@tokapps/tuk';export function SubmitHint({ canSubmit }: { canSubmit: boolean }) {  return (    <Tooltip content="ابتدا فیلدهای الزامی را تکمیل کنید" disabled={canSubmit}>      <Button variant="primary">ثبت ایده</Button>    </Tooltip>  );}

همهٔ پیکربندی‌ها

نوع	پیش‌فرض	توضیح
	— (الزامی)	متن کوتاه و غیرتعاملی. اطلاعات ضروری را فقط در Tooltip نگذارید.
	— (الزامی)	محرک فوکوس‌پذیر (دکمه، لینک و مانند آن).
(React Aria)		مکان نسبت به محرک؛ مقادیر منطقی مانند پشتیبانی می‌شوند.
(ms)		تأخیر نمایش پس از hover.
(ms)		تأخیر بستن پس از خروج اشاره‌گر.
		فاصله از محرک.
		اگر باشد Tooltip نمایش داده نمی‌شود.
( یا )		رفتار چاپ؛ پیش‌فرض پنهان است (ر.ک. بخش چاپ).
	—	جهت صریح؛ بدون مقدار، جهت از ساختار صفحه می‌آید.
	—	کلاس روی حباب.

پراپ‌های بیشتری در تعریف نشده‌اند.

ساختار و اسلات‌ها

ترتیب اجزا: و در کنار آن حباب با محتوای . حباب اسلات ندارد و یک بلوک متنی یکپارچه است.

بنیان ثابت: حباب با و · نقش (از React Aria) · روی محرک · محرک فوکوس‌پذیر از طریق (بدون press).
قابل‌تغییر: ، ، روی حباب، و توکن‌های .

همهٔ حالت‌ها

حالت	نشانه (data-attribute یا prop)	نمایش
پیش‌فرض (بسته)	بدون یا	حباب دیده نمی‌شود.
hover روی محرک	پس از میلی‌ثانیه	حباب باز می‌شود.
فوکوس صفحه‌کلید روی محرک	فوکوس با	حباب بدون تأخیر باز می‌شود.
visible	· · روی محرک	حباب با محو و بزرگ‌شدن کوچک ظاهر می‌شود.
exiting		حباب محو می‌شود و پس از آن حذف می‌شود.
focus-visible روی محرک	(حلقهٔ )	حلقهٔ فوکوس روی محرک دیده می‌شود؛ خود حباب فوکوس نمی‌گیرد.
disabled	prop	Tooltip هیچ‌وقت باز نمی‌شود.
print	(پیش‌فرض)	در چاپ پنهان است.
کاهش حرکت	یا	بدون انیمیشن ورود و خروج.

قرارداد پوشش (Overlay Contract)

دام فوکوس: Tooltip فوکوس نمی‌گیرد و دام فوکوس ندارد؛ محرک فوکوس‌پذیر همچنان فوکوس را نگه می‌دارد.
Escape: Escape حباب باز را می‌بندد، بی‌آنکه مودال والد بسته شود.
پس‌زمینه (backdrop): پرده ندارد؛ با خروج اشاره‌گر یا فوکوس، یا با Escape بسته می‌شود.
قفل اسکرول: قفل اسکرول ندارد؛ موقعیت با اسکرول محرک به‌روز می‌شود یا حباب بسته می‌شود.
نمایش واکنش‌گرا: در موبایل از یا برگهٔ زندهٔ داک () استفاده کنید؛ حباب فقط برای مکان‌یابی نسبت به محرک است.
کشیدن برای بستن: ندارد.
تودرتو: درون مودال دیده می‌شود، چون z-index آن بالاتر از مودال و شناورهاست.

تغییرات مجاز برای توسعه‌دهنده

موقعیت و زمان‌بندی: (مقادیر React Aria)، ، ، .
وضعیت: برای توقف نمایش.
محتوا: هر کوتاه و غیرتعاملی در . متن را در کد ترجمه‌پذیر نگه دارید.
نقاط توسعه: روی حباب؛ توکن‌های سطح کامپوننت ، ، و ؛ ؛ .
variant و size: فقط یک ظاهر () و یک اندازه () وجود دارد.

تغییرات ممنوع (بنیان ثابت)

ساختار DOM حباب و نقش از React Aria.
ارتباط بین محرک و حباب.
محرک باید فوکوس‌پذیر باشد؛ Tooltip روی عنصر غیرفوکوس‌پذیر کار نمی‌کند.
Tooltip نباید فوکوس بگیرد یا دام فوکوس بسازد.
رفتار و بستن با خروج اشاره‌گر یا فوکوس.
حذف انیمیشن در .
هدف لمسی ۴۴px برای محرک (در قرارداد a11y ثبت شده است).
هیچ صدایی برای Tooltip تعریف نشده و نباید افزوده شود.

RTL، کیبورد و صفحه‌خوان

RTL: ویژگی‌های منطقی (inline/block) و . منطقی است؛ آیکون‌های جهت‌دار داخل محرک در RTL برمی‌گردند.
کیبورد: فوکوس روی محرک حباب را نمایش می‌دهد؛ آن را می‌بندد. از محرک عبور می‌کند.
صفحه‌خوان: محتوای حباب از طریق به‌عنوان توضیح محرک خوانده می‌شود؛ نام محرک از خود محرک می‌آید. برای دکمهٔ فقط‌آیکون، روی محرک الزامی است.

صدا، حرکت، چاپ و کاهش حرکت

صدا: Tooltip بی‌صداست؛ هیچ رویداد صوتی ندارد () و hover هرگز صدا ایجاد نمی‌کند.
حرکت: نام معنایی با خواص و . با یا بدون انیمیشن است.
چاپ: پیش‌فرض و در چاپ پنهان است. در کد قاعدهٔ بدون شرط حباب را پنهان می‌کند؛ یعنی عملاً اثری ندارد.

توکن‌ها

فایل توکن‌های کامپوننتی: (گروه overlays؛ این کامپوننت توکن اختصاصی ندارد).
توکن‌های سطح کامپوننت مصرفی: ، ، ، ، (= modal + 2)، ، ، ، ، و سایر موارد در .
توکن‌های معنایی مصرفی: ، ، ، ، ، ، .
فهرست کامل: .

قرارداد ARCH

آیکون داخل محرک فقط با و نام معنایی (مثلاً ) تعیین می‌شود؛ مسیر asset مستقیم در کد مصرف‌کننده نمی‌آید.
تم فقط حرکت و توکن‌های مجاز را تغییر می‌دهد؛ ساختار DOM و ARIA ثابت است.
Tooltip gesture ندارد؛ معادل صفحه‌کلید فوکوس است.

نکات

برای محتوای تعاملی یا بلند از Popover استفاده کنید.
برای کنش‌های ثانویهٔ یک ناحیه از ContextMenu استفاده کنید؛ Tooltip جایگزین منوی کنش نیست.
اگر اطلاعی ضروری است، در متن صفحه یا در Toast هم نمایش دهید؛ روی لمس Tooltip دیده نمی‌شود.