منوی زمینه — ContextMenu

ContextMenu فهرست کنش‌های ثانویهٔ یک ناحیه را در مختصات اشاره‌گر نشان می‌دهد؛ مثلاً کارت یک ایده یا ردیف یک جدول. با کلیک راست، کلید منو یا Shift+F10 و لمس طولانی باز می‌شود. منو فقط یک میان‌بر است: هر کنش باید از مسیر دیگری هم در دسترس باشد. ساختار منو، رفتار کیبورد (از React Aria) و برچسب «(مخرب)» برای کنش‌های خطرناک ثابت است.

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

TSX

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

نمونهٔ زنده

روی این ناحیه کلیک راست کنید یا Shift+F10 بزنید.

کارت کمپین

کد قابل کپی

پایه: فهرست تخت با میان‌بر

TSX

import { ContextMenu } from '@tokapps/tuk';import { Icon } from '@tokapps/icons';const items = [  { id: 'copy', label: 'کپی متن', icon: <Icon name="copy" size="sm" />, shortcut: '⌘C' },  { id: 'link', label: 'کپی پیوند', icon: <Icon name="link.copy" size="sm" /> },  { id: 'delete', label: 'حذف ایده', icon: <Icon name="delete" size="sm" />, danger: true },];export function IdeaContextArea() {  return (    <ContextMenu items={items} aria-label="کنش‌های ایده" onAction={(id) => console.log(id)}>      <div tabIndex={0}>متن ایده را اینجا بنویسید</div>    </ContextMenu>  );}

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

TSX

import { ContextMenu } from '@tokapps/tuk';import { Icon } from '@tokapps/icons';const copy = { id: 'copy', label: 'کپی متن', icon: <Icon name="copy" size="sm" />, shortcut: '⌘C' };const link = { id: 'link', label: 'کپی پیوند', icon: <Icon name="link.copy" size="sm" /> };const remove = { id: 'delete', label: 'حذف ایده', icon: <Icon name="delete" size="sm" />, danger: true };export function CampaignCardMenu({ onAction }: { onAction: (id: string) => void }) {  return (    <ContextMenu      aria-label="کنش‌های کارت"      longPressMs={500}      onAction={onAction}      sections={[        { id: 'share', items: [copy, link] },        { id: 'danger', heading: 'خطرناک', items: [remove] },      ]}    >      <div tabIndex={0}>کارت کمپین</div>    </ContextMenu>  );}

حالت غیرفعال: منوی بسته و کنش‌های آیتم

TSX

import { ContextMenu } from '@tokapps/tuk';const items = [  { id: 'copy', label: 'کپی متن' },  { id: 'publish', label: 'انتشار', disabled: true },];export function ReadOnlyRow({ locked }: { locked: boolean }) {  return (    <ContextMenu items={items} aria-label="کنش‌های ردیف" disabled={locked}>      <div tabIndex={0}>ردیف جدول</div>    </ContextMenu>  );}

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

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

فیلدهای

فیلد	نوع	پیش‌فرض	توضیح
		— (الزامی)	شناسهٔ یکتا؛ در برگردانده می‌شود.
		— (الزامی)	برچسب آیتم؛ نام دسترسی آیتم از آن گرفته می‌شود.
		—	آیکون، معمولاً با نام معنایی.
		—	میان‌بر نمایشی (مثلاً ) که همیشه LTR نمایش داده می‌شود.
			رنگ خطر و برچسب متنی «(مخرب)» برای صفحه‌خوان.
			آیتم غیرفعال.
		—	هنگام اجرای همین آیتم صدا زده می‌شود. هم‌زمان سطح منو با شناسهٔ آیتم هم صدا زده می‌شود.

فیلدهای

فیلد	نوع	پیش‌فرض	توضیح
		— (الزامی)	شناسهٔ بخش.
		—	عنوان بخش؛ گروه نام‌دار برای صفحه‌خوان.
		— (الزامی)	آیتم‌های بخش.

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

ترتیب اجزا: و پس از آن لنگر مجازی و منوی شناور .

بنیان ثابت: ناحیه · لنگر مجازی (، ثابت‌شده در مختصات اشاره‌گر) · منوی با نقش · آیتم‌های با نقش · · (کلید ) · · .
قابل‌تغییر: روی منو، آیکون و میان‌بر آیتم، و توکن‌های و .

همهٔ حالت‌ها

حالت	نشانه (data-attribute یا prop)	نمایش
بسته (پیش‌فرض)	منو در DOM دیده نمی‌شود	فقط ناحیه نمایش داده می‌شود.
باز	·	منو با محو و بزرگ‌شدن کوچک در مختصات اشاره‌گر ظاهر می‌شود.
بسته‌شدن		منو محو می‌شود.
آیتم focused		پس‌زمینهٔ .
آیتم hover		پس‌زمینهٔ .
آیتم pressed		پس‌زمینهٔ .
آیتم focus-visible		حلقهٔ داخل آیتم.
آیتم disabled	(prop )	رنگ کم‌رنگ و بدون پاسخ به کلیک.
آیتم danger	(prop )	رنگ و برچسب «(مخرب)» برای صفحه‌خوان.
منو غیرفعال	prop روی ContextMenu	منوی زمینه باز نمی‌شود؛ منوی مرورگر دیده می‌شود.
لمس طولانی		پس از مدت تعیین‌شده باز می‌شود؛ اگر انگشت بیش از ۱۰px جابه‌جا شود، لغو می‌شود.

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

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

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

variant: (فهرست تخت با ) یا (بخش‌بندی با ).
size: فقط .
آیتم: ، ، ، ، .
بخش: برای عنوان و جداکننده خودکار بین بخش‌ها.
نقاط توسعه: ؛ ؛ ؛ ؛ (رویداد و )؛ ؛ توکن‌های سطح کامپوننت ، ، ، ، ، ؛ و پیام‌های متنی .

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

ساختار DOM ناحیه، لنگر مجازی و منو.
نقش و و الزامی منو.
رفتار کیبورد: ، ، ، ، و از React Aria می‌آیند.
برچسب «(مخرب)» برای آیتم‌های .
هدف لمسی ۴۴px روی اشاره‌گر درشت ().
کاهش حرکت: حذف انیمیشن ورود و خروج.
منو فقط میان‌بر است؛ نباید تنها راه رسیدن به یک کنش شود.

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

RTL: جای‌گذاری منطقی است. میان‌بر () LTR و ایزوله () نمایش داده می‌شود.
کیبورد: یا کلید منو باز می‌کند (رویداد مرورگر). و بین آیتم‌ها حرکت می‌کنند، و به ابتدا و انتها می‌روند، کنش را اجرا و منو را می‌بندد.
صفحه‌خوان: منو با است؛ آیتم‌ها هستند؛ بخش‌ها گروه نام‌دار هستند؛ آیتم مخرب با «(مخرب)» اعلام می‌شود.

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

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

توکن‌ها

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

قرارداد ARCH

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

نکات

برای جستجوی سراسری کنش‌ها از CommandMenu استفاده کنید.
برای محتوای غیرمنو (فرم یا انتخاب بلند) از Popover استفاده کنید.
برای ناوبری اصلی از Navigation استفاده کنید، نه منوی زمینه.
در موبایل، کنش‌های مهم را در برگهٔ زندهٔ داک هم در دسترس بگذارید تا فقط به لمس طولانی وابسته نباشند.

منوی زمینه — ContextMenu

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

TSX

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

نمونهٔ زنده

روی این ناحیه کلیک راست کنید یا Shift+F10 بزنید.

کارت کمپین

کد قابل کپی

پایه: فهرست تخت با میان‌بر

TSX

import { ContextMenu } from '@tokapps/tuk';import { Icon } from '@tokapps/icons';const items = [  { id: 'copy', label: 'کپی متن', icon: <Icon name="copy" size="sm" />, shortcut: '⌘C' },  { id: 'link', label: 'کپی پیوند', icon: <Icon name="link.copy" size="sm" /> },  { id: 'delete', label: 'حذف ایده', icon: <Icon name="delete" size="sm" />, danger: true },];export function IdeaContextArea() {  return (    <ContextMenu items={items} aria-label="کنش‌های ایده" onAction={(id) => console.log(id)}>      <div tabIndex={0}>متن ایده را اینجا بنویسید</div>    </ContextMenu>  );}

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

TSX

import { ContextMenu } from '@tokapps/tuk';import { Icon } from '@tokapps/icons';const copy = { id: 'copy', label: 'کپی متن', icon: <Icon name="copy" size="sm" />, shortcut: '⌘C' };const link = { id: 'link', label: 'کپی پیوند', icon: <Icon name="link.copy" size="sm" /> };const remove = { id: 'delete', label: 'حذف ایده', icon: <Icon name="delete" size="sm" />, danger: true };export function CampaignCardMenu({ onAction }: { onAction: (id: string) => void }) {  return (    <ContextMenu      aria-label="کنش‌های کارت"      longPressMs={500}      onAction={onAction}      sections={[        { id: 'share', items: [copy, link] },        { id: 'danger', heading: 'خطرناک', items: [remove] },      ]}    >      <div tabIndex={0}>کارت کمپین</div>    </ContextMenu>  );}

حالت غیرفعال: منوی بسته و کنش‌های آیتم

TSX

import { ContextMenu } from '@tokapps/tuk';const items = [  { id: 'copy', label: 'کپی متن' },  { id: 'publish', label: 'انتشار', disabled: true },];export function ReadOnlyRow({ locked }: { locked: boolean }) {  return (    <ContextMenu items={items} aria-label="کنش‌های ردیف" disabled={locked}>      <div tabIndex={0}>ردیف جدول</div>    </ContextMenu>  );}

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

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

فیلدهای

فیلد	نوع	پیش‌فرض	توضیح
		— (الزامی)	شناسهٔ یکتا؛ در برگردانده می‌شود.
		— (الزامی)	برچسب آیتم؛ نام دسترسی آیتم از آن گرفته می‌شود.
		—	آیکون، معمولاً با نام معنایی.
		—	میان‌بر نمایشی (مثلاً ) که همیشه LTR نمایش داده می‌شود.
			رنگ خطر و برچسب متنی «(مخرب)» برای صفحه‌خوان.
			آیتم غیرفعال.
		—	هنگام اجرای همین آیتم صدا زده می‌شود. هم‌زمان سطح منو با شناسهٔ آیتم هم صدا زده می‌شود.

فیلدهای

فیلد	نوع	پیش‌فرض	توضیح
		— (الزامی)	شناسهٔ بخش.
		—	عنوان بخش؛ گروه نام‌دار برای صفحه‌خوان.
		— (الزامی)	آیتم‌های بخش.

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

ترتیب اجزا: و پس از آن لنگر مجازی و منوی شناور .

بنیان ثابت: ناحیه · لنگر مجازی (، ثابت‌شده در مختصات اشاره‌گر) · منوی با نقش · آیتم‌های با نقش · · (کلید ) · · .
قابل‌تغییر: روی منو، آیکون و میان‌بر آیتم، و توکن‌های و .

همهٔ حالت‌ها

حالت	نشانه (data-attribute یا prop)	نمایش
بسته (پیش‌فرض)	منو در DOM دیده نمی‌شود	فقط ناحیه نمایش داده می‌شود.
باز	·	منو با محو و بزرگ‌شدن کوچک در مختصات اشاره‌گر ظاهر می‌شود.
بسته‌شدن		منو محو می‌شود.
آیتم focused		پس‌زمینهٔ .
آیتم hover		پس‌زمینهٔ .
آیتم pressed		پس‌زمینهٔ .
آیتم focus-visible		حلقهٔ داخل آیتم.
آیتم disabled	(prop )	رنگ کم‌رنگ و بدون پاسخ به کلیک.
آیتم danger	(prop )	رنگ و برچسب «(مخرب)» برای صفحه‌خوان.
منو غیرفعال	prop روی ContextMenu	منوی زمینه باز نمی‌شود؛ منوی مرورگر دیده می‌شود.
لمس طولانی		پس از مدت تعیین‌شده باز می‌شود؛ اگر انگشت بیش از ۱۰px جابه‌جا شود، لغو می‌شود.

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

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

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

variant: (فهرست تخت با ) یا (بخش‌بندی با ).
size: فقط .
آیتم: ، ، ، ، .
بخش: برای عنوان و جداکننده خودکار بین بخش‌ها.
نقاط توسعه: ؛ ؛ ؛ ؛ (رویداد و )؛ ؛ توکن‌های سطح کامپوننت ، ، ، ، ، ؛ و پیام‌های متنی .

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

ساختار DOM ناحیه، لنگر مجازی و منو.
نقش و و الزامی منو.
رفتار کیبورد: ، ، ، ، و از React Aria می‌آیند.
برچسب «(مخرب)» برای آیتم‌های .
هدف لمسی ۴۴px روی اشاره‌گر درشت ().
کاهش حرکت: حذف انیمیشن ورود و خروج.
منو فقط میان‌بر است؛ نباید تنها راه رسیدن به یک کنش شود.

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

RTL: جای‌گذاری منطقی است. میان‌بر () LTR و ایزوله () نمایش داده می‌شود.
کیبورد: یا کلید منو باز می‌کند (رویداد مرورگر). و بین آیتم‌ها حرکت می‌کنند، و به ابتدا و انتها می‌روند، کنش را اجرا و منو را می‌بندد.
صفحه‌خوان: منو با است؛ آیتم‌ها هستند؛ بخش‌ها گروه نام‌دار هستند؛ آیتم مخرب با «(مخرب)» اعلام می‌شود.

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

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

توکن‌ها

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

قرارداد ARCH

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

نکات

برای جستجوی سراسری کنش‌ها از CommandMenu استفاده کنید.
برای محتوای غیرمنو (فرم یا انتخاب بلند) از Popover استفاده کنید.
برای ناوبری اصلی از Navigation استفاده کنید، نه منوی زمینه.
در موبایل، کنش‌های مهم را در برگهٔ زندهٔ داک هم در دسترس بگذارید تا فقط به لمس طولانی وابسته نباشند.

منوی زمینه — ContextMenu

نمونهٔ زنده

کد قابل کپی

پایه: فهرست تخت با میان‌بر

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

حالت غیرفعال: منوی بسته و کنش‌های آیتم

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

فیلدهای ContextMenuItemکپی کدکپی کد

فیلدهای ContextMenuSectionکپی کدکپی کد

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

همهٔ حالت‌ها

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

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

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

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

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

توکن‌ها

قرارداد ARCH

نکات

منوی زمینه — ContextMenu

نمونهٔ زنده

کد قابل کپی

پایه: فهرست تخت با میان‌بر

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

حالت غیرفعال: منوی بسته و کنش‌های آیتم

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

فیلدهای ContextMenuItemکپی کدکپی کد

فیلدهای ContextMenuSectionکپی کدکپی کد

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

همهٔ حالت‌ها

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

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

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

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

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

توکن‌ها

قرارداد ARCH

نکات

فیلدهای

فیلدهای

فیلدهای

فیلدهای