پاپ‌اور — Popover

یک پنل شناور کوچک است که کنار محرک خودش باز می‌شود و محتوای تعاملی کوتاه نشان می‌دهد، مثل راهنمای یک‌فیلدی یا جزئیات یک امتیاز. برخلاف پرده ندارد و صفحه را مسدود نمی‌کند (با بقیهٔ صفحه تعاملی می‌ماند). جای‌گذاری با انجام می‌شود و مقادیر و در RTL برعکس می‌شوند. در موبایل از یا برگهٔ داک استفاده کنید؛ شناور فقط برای مکان‌یابی نسبت به محرک است.

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

TSX

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

نمونهٔ زنده

کد قابل کپی

پایه: جزئیات با عنوان

TSX

import { Popover, Button } from '@tokapps/tuk';export function ScoreDetails() {  return (    <Popover      trigger={<Button variant="secondary">جزئیات</Button>}      title="دربارهٔ امتیاز"      size="sm"    >      <p>امتیاز از میانگین نظر ارزیاب‌ها و حمایت جامعه محاسبه می‌شود.</p>    </Popover>  );}

پیشرفته: کنترل‌شده، بالای محرک، بدون عنوان مرئی

TSX

import { useState } from 'react';import { Popover, Button } from '@tokapps/tuk';export function HelpHint() {  const [open, setOpen] = useState(false);  return (    <Popover      open={open}      onOpenChange={setOpen}      placement="top"      offset={12}      size="lg"      aria-label="راهنمای بودجه"      trigger={<Button variant="ghost" onClick={() => setOpen((value) => !value)}>راهنما</Button>}    >      <p>بودجه تا پایان کمپین قابل تغییر است؛ کاهش آن پس از شروع حمایت ممکن نیست.</p>    </Popover>  );}

حالت غیرمودال: صفحه قابل تعامل می‌ماند

TSX

import { Popover, Button } from '@tokapps/tuk';export function FilterPeek() {  return (    <Popover      nonModal      placement="end"      size="sm"      aria-label="خلاصهٔ فیلتر"      trigger={<Button variant="ghost">خلاصه</Button>}    >      <p>سه فیلتر فعال است. بقیهٔ صفحه همچنان قابل کار کردن است.</p>    </Popover>  );}

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

پراپ‌ها را از (در ) می‌گیرد؛ این کامپوننت را ارث نمی‌برد. پیش‌فرض‌ها از پارامترهای تابع در خوانده شده‌اند.

نوع	پیش‌فرض	توضیح
	بدون پیش‌فرض (الزامی)	محرک؛ و خودکار روی آن می‌نشیند. عنصر باید ref را به DOM برساند ( می‌رساند).
	—	حالت کنترل‌شده.
	—	حالت کنترل‌نشدهٔ اولیه.
	—	با هر تغییر باز یا بسته صدا می‌خورد.
	—	عنوان اختیاری (). بدون آن بدهید.
	—	نام دسترسی؛ فقط وقتی نیست روی پنل می‌نشیند.
	—	محتوای پنل. فقط گره است؛ تابع پشتیبانی نمی‌شود.
(از React Aria، مثل ، ، ، )		جای‌گذاری نسبت به محرک. و در RTL برعکس می‌شوند.
		فاصله از محرک بر حسب پیکسل.
		عرض ؛ عرض ؛ بر اساس محتوا تا .
		یعنی بقیهٔ صفحه تعاملی می‌ماند.
	—	مقصد اختصاصی صدا (opt-in).
		رفتار چاپ.
	از	جهت صریح برای locale React Aria.
	—	کلاس اضافه روی ریشهٔ شناور.

در کد تعریف نشده: ، ، ، ، ، و .

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

code

RacPopover  [data-tds="popover"][data-overlay="floating"][data-size][data-print]│           style: z-index از --tds-overlay-z-floating└── RacDialog  [data-part="dialog"]    ├── Heading  [data-part="title"]           (فقط وقتی title)    └── children

بنیان ثابت: ساختار و ، ارتباط محرک با ، و z-index از توکن.
قابل تغییر: محتوای ، ، و متغیرهای .
در کد تعریف نشده: دکمهٔ بستن، فوتر و پرده. بستن فقط با Escape، کلیک بیرون، یا کنترل از بیرون با و ممکن است.

همهٔ حالت‌ها

حالت	نشانه (data-attribute یا prop)	نمایش
بسته (closed)	شناور در DOM نیست	—
باز (open)	روی محرک (از React Aria)	شناور کنار محرک با ماده شیشه‌ای
در حال ورود	(از React Aria)	با
در حال خروج
غیرمودال		بدون پرده؛ بقیهٔ صفحه تعاملی
اندازه		عرض
اندازه		عرض بر اساس محتوا، حداکثر
اندازه		عرض
focus-visible	روی کنترل‌های داخل پنل	حلقهٔ
چاپ	(پیش‌فرض)	پنهان در چاپ
hover، pressed، disabled، خطا، بارگذاری	در کد تعریف نشده روی پنل	— (کنترل‌های داخل محتوا حالت خودشان را دارند)

رفتار پوشش (از قرارداد در )

فوکوس: شناور فوکوس را مدیریت می‌کند؛ با بسته شدن فوکوس به محرک برمی‌گردد.
Escape: فقط بالاترین شناور را می‌بندد.
کلیک بیرون: شناور را می‌بندد و پرده‌ای رسم نمی‌شود.
قفل اسکرول: ندارد. موقعیت با اسکرول محرک به‌روز می‌شود یا شناور بسته می‌شود.
تودرتو: زیرمنو یا شناور داخل مودال پشتیبانی می‌شود؛ z شناور بالاتر از مودال است.

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

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

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

افزودن پرده یا قفل اسکرول به شناور. این کار آن را به تبدیل می‌کند.
حذف یا تغییر نقش پنل از .
حذف نام دسترسی: بدون باید باشد.
استفاده از شناور برای فهرست کنش (از استفاده کنید) یا متن کوتاه غیرتعاملی (از ).
قرار دادن z-index خام به‌جای . React Aria به‌طور پیش‌فرض z-index بزرگ درون‌خطی می‌دهد که استایل توکنی آن را جایگزین می‌کند.
استایل خام برای پس‌زمینه شیشه‌ای یا گرادیان. فقط توکن‌های از طریق .

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

RTL: در RTL سمت راست و سمت چپ می‌نشیند. ویژگی‌های منطقی برای فاصله‌ها استفاده شده‌اند.
کلیدها: یا روی محرک، پنل را باز و بسته می‌کند؛ درون شناور حرکت می‌کند؛ می‌بندد و فوکوس به محرک برمی‌گردد.
صفحه‌خوان: محرک و دارد؛ پنل است و نام آن از یا می‌آید.
هدف لمسی: کنترل‌های داخل محتوا باید حداقل ۴۴px باشند.
کنتراست: روشن، تیره و کنتراست بالا با بررسی می‌شوند.

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

صدا: پیش‌فرض بی‌صداست (opt-in). باز و بسته شدن است؛ هیچ صدایی روی hover پخش نمی‌شود. معادل بصری: ظاهر شدن شناور.
حرکت: نام معنایی (opacity و scale) در .
کاهش حرکت: با یا انیمیشن حذف و شناور فوری ظاهر می‌شود.
چاپ: پیش‌فرض و شناور در چاپ حذف می‌شود.

توکن‌ها

فایل توکن‌های مصرفی: . استایل‌ها در و ماده شیشه‌ای مشترک در . مقدار مرجع در .

معنایی: ، ، ، ، ، ، .
کامپوننتی: ، ، ، ، ، ، ، ، ، ، ، ، ، ، ، ، ، .
تایپوگرافی، کنترل و مقیاس: ، ، ، ، ، ، ، ، ، ، ، .

قرارداد ARCH

این کامپوننت آیکون ندارد. اگر آیکون لازم شد فقط با و نام معنایی بیاید.
تم فقط حرکت () و توکن‌های شیشه‌ای را تغییر می‌دهد؛ جای‌گذاری و ساختار ثابت‌اند.
gesture ندارد. معادل کیبوردی بستن Escape است.

نکات

برای توضیح کوتاه یک‌خطی بدون تعامل: Tooltip.
برای فهرست کنش‌ها: ContextMenu.
برای نمای موبایل: ResponsiveDialog.
برای محتوای مرکزی با پرده: Dialog.

پاپ‌اور — Popover

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

TSX

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

نمونهٔ زنده

کد قابل کپی

پایه: جزئیات با عنوان

TSX

import { Popover, Button } from '@tokapps/tuk';export function ScoreDetails() {  return (    <Popover      trigger={<Button variant="secondary">جزئیات</Button>}      title="دربارهٔ امتیاز"      size="sm"    >      <p>امتیاز از میانگین نظر ارزیاب‌ها و حمایت جامعه محاسبه می‌شود.</p>    </Popover>  );}

پیشرفته: کنترل‌شده، بالای محرک، بدون عنوان مرئی

TSX

import { useState } from 'react';import { Popover, Button } from '@tokapps/tuk';export function HelpHint() {  const [open, setOpen] = useState(false);  return (    <Popover      open={open}      onOpenChange={setOpen}      placement="top"      offset={12}      size="lg"      aria-label="راهنمای بودجه"      trigger={<Button variant="ghost" onClick={() => setOpen((value) => !value)}>راهنما</Button>}    >      <p>بودجه تا پایان کمپین قابل تغییر است؛ کاهش آن پس از شروع حمایت ممکن نیست.</p>    </Popover>  );}

حالت غیرمودال: صفحه قابل تعامل می‌ماند

TSX

import { Popover, Button } from '@tokapps/tuk';export function FilterPeek() {  return (    <Popover      nonModal      placement="end"      size="sm"      aria-label="خلاصهٔ فیلتر"      trigger={<Button variant="ghost">خلاصه</Button>}    >      <p>سه فیلتر فعال است. بقیهٔ صفحه همچنان قابل کار کردن است.</p>    </Popover>  );}

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

پراپ‌ها را از (در ) می‌گیرد؛ این کامپوننت را ارث نمی‌برد. پیش‌فرض‌ها از پارامترهای تابع در خوانده شده‌اند.

نوع	پیش‌فرض	توضیح
	بدون پیش‌فرض (الزامی)	محرک؛ و خودکار روی آن می‌نشیند. عنصر باید ref را به DOM برساند ( می‌رساند).
	—	حالت کنترل‌شده.
	—	حالت کنترل‌نشدهٔ اولیه.
	—	با هر تغییر باز یا بسته صدا می‌خورد.
	—	عنوان اختیاری (). بدون آن بدهید.
	—	نام دسترسی؛ فقط وقتی نیست روی پنل می‌نشیند.
	—	محتوای پنل. فقط گره است؛ تابع پشتیبانی نمی‌شود.
(از React Aria، مثل ، ، ، )		جای‌گذاری نسبت به محرک. و در RTL برعکس می‌شوند.
		فاصله از محرک بر حسب پیکسل.
		عرض ؛ عرض ؛ بر اساس محتوا تا .
		یعنی بقیهٔ صفحه تعاملی می‌ماند.
	—	مقصد اختصاصی صدا (opt-in).
		رفتار چاپ.
	از	جهت صریح برای locale React Aria.
	—	کلاس اضافه روی ریشهٔ شناور.

در کد تعریف نشده: ، ، ، ، ، و .

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

code

RacPopover  [data-tds="popover"][data-overlay="floating"][data-size][data-print]│           style: z-index از --tds-overlay-z-floating└── RacDialog  [data-part="dialog"]    ├── Heading  [data-part="title"]           (فقط وقتی title)    └── children

بنیان ثابت: ساختار و ، ارتباط محرک با ، و z-index از توکن.
قابل تغییر: محتوای ، ، و متغیرهای .
در کد تعریف نشده: دکمهٔ بستن، فوتر و پرده. بستن فقط با Escape، کلیک بیرون، یا کنترل از بیرون با و ممکن است.

همهٔ حالت‌ها

حالت	نشانه (data-attribute یا prop)	نمایش
بسته (closed)	شناور در DOM نیست	—
باز (open)	روی محرک (از React Aria)	شناور کنار محرک با ماده شیشه‌ای
در حال ورود	(از React Aria)	با
در حال خروج
غیرمودال		بدون پرده؛ بقیهٔ صفحه تعاملی
اندازه		عرض
اندازه		عرض بر اساس محتوا، حداکثر
اندازه		عرض
focus-visible	روی کنترل‌های داخل پنل	حلقهٔ
چاپ	(پیش‌فرض)	پنهان در چاپ
hover، pressed، disabled، خطا، بارگذاری	در کد تعریف نشده روی پنل	— (کنترل‌های داخل محتوا حالت خودشان را دارند)

رفتار پوشش (از قرارداد در )

فوکوس: شناور فوکوس را مدیریت می‌کند؛ با بسته شدن فوکوس به محرک برمی‌گردد.
Escape: فقط بالاترین شناور را می‌بندد.
کلیک بیرون: شناور را می‌بندد و پرده‌ای رسم نمی‌شود.
قفل اسکرول: ندارد. موقعیت با اسکرول محرک به‌روز می‌شود یا شناور بسته می‌شود.
تودرتو: زیرمنو یا شناور داخل مودال پشتیبانی می‌شود؛ z شناور بالاتر از مودال است.

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

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

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

افزودن پرده یا قفل اسکرول به شناور. این کار آن را به تبدیل می‌کند.
حذف یا تغییر نقش پنل از .
حذف نام دسترسی: بدون باید باشد.
استفاده از شناور برای فهرست کنش (از استفاده کنید) یا متن کوتاه غیرتعاملی (از ).
قرار دادن z-index خام به‌جای . React Aria به‌طور پیش‌فرض z-index بزرگ درون‌خطی می‌دهد که استایل توکنی آن را جایگزین می‌کند.
استایل خام برای پس‌زمینه شیشه‌ای یا گرادیان. فقط توکن‌های از طریق .

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

RTL: در RTL سمت راست و سمت چپ می‌نشیند. ویژگی‌های منطقی برای فاصله‌ها استفاده شده‌اند.
کلیدها: یا روی محرک، پنل را باز و بسته می‌کند؛ درون شناور حرکت می‌کند؛ می‌بندد و فوکوس به محرک برمی‌گردد.
صفحه‌خوان: محرک و دارد؛ پنل است و نام آن از یا می‌آید.
هدف لمسی: کنترل‌های داخل محتوا باید حداقل ۴۴px باشند.
کنتراست: روشن، تیره و کنتراست بالا با بررسی می‌شوند.

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

صدا: پیش‌فرض بی‌صداست (opt-in). باز و بسته شدن است؛ هیچ صدایی روی hover پخش نمی‌شود. معادل بصری: ظاهر شدن شناور.
حرکت: نام معنایی (opacity و scale) در .
کاهش حرکت: با یا انیمیشن حذف و شناور فوری ظاهر می‌شود.
چاپ: پیش‌فرض و شناور در چاپ حذف می‌شود.

توکن‌ها

فایل توکن‌های مصرفی: . استایل‌ها در و ماده شیشه‌ای مشترک در . مقدار مرجع در .

معنایی: ، ، ، ، ، ، .
کامپوننتی: ، ، ، ، ، ، ، ، ، ، ، ، ، ، ، ، ، .
تایپوگرافی، کنترل و مقیاس: ، ، ، ، ، ، ، ، ، ، ، .

قرارداد ARCH

این کامپوننت آیکون ندارد. اگر آیکون لازم شد فقط با و نام معنایی بیاید.
تم فقط حرکت () و توکن‌های شیشه‌ای را تغییر می‌دهد؛ جای‌گذاری و ساختار ثابت‌اند.
gesture ندارد. معادل کیبوردی بستن Escape است.

نکات

برای توضیح کوتاه یک‌خطی بدون تعامل: Tooltip.
برای فهرست کنش‌ها: ContextMenu.
برای نمای موبایل: ResponsiveDialog.
برای محتوای مرکزی با پرده: Dialog.

پاپ‌اور — Popover

نمونهٔ زنده

کد قابل کپی

پایه: جزئیات با عنوان

پیشرفته: کنترل‌شده، بالای محرک، بدون عنوان مرئی

حالت غیرمودال: صفحه قابل تعامل می‌ماند

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

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

همهٔ حالت‌ها

رفتار پوشش (از قرارداد floatingBaseکپی کدکپی کد در _shared/contract.tsکپی کدکپی کد)

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

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

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

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

توکن‌ها

قرارداد ARCH

نکات

پاپ‌اور — Popover

نمونهٔ زنده

کد قابل کپی

پایه: جزئیات با عنوان

پیشرفته: کنترل‌شده، بالای محرک، بدون عنوان مرئی

حالت غیرمودال: صفحه قابل تعامل می‌ماند

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

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

همهٔ حالت‌ها

رفتار پوشش (از قرارداد floatingBaseکپی کدکپی کد در _shared/contract.tsکپی کدکپی کد)

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

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

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

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

توکن‌ها

قرارداد ARCH

نکات

رفتار پوشش (از قرارداد در )

رفتار پوشش (از قرارداد در )