پالت فرمان — CommandMenu
CommandMenu یک مودال جستجو و اجرای کنش است که با میانبر سراسری کپی کد یا کپی کد باز میشود. ورودی جستجو فوکوس را نگه میدارد و فهرست با کپی کد و کپی کد پیمایش میشود. تطبیق جستجو فارسیمحور است: ی/ک عربی و ارقام فارسی/عربی یکسان فرض میشوند. ساختار پنل، ورودی، فهرست نتایج، پانویس و اعلان تعداد ثابت است؛ هویت بصری فقط حرکت آن را تعیین میکند.
وضعیت: beta · لایه: ۳ (کپی کد) · کد: کپی کد
import { CommandMenu } from '@tokapps/tuk';نمونهٔ زنده
کد قابل کپی
پایه: با دکمهٔ باز کردن و میانبر سراسری
import { Button, CommandMenu } from '@tokapps/tuk';import type { CommandItem } from '@tokapps/tuk';import { Icon } from '@tokapps/icons';const commands: readonly CommandItem[] = [ { id: 'new-idea', label: 'ثبت ایدهٔ جدید', group: 'ایجاد', icon: <Icon name="file.add" size="sm" />, keywords: ['ایده', 'idea', 'جدید'] }, { id: 'search', label: 'جستجو در انجمن', group: 'ناوبری', icon: <Icon name="search" size="sm" />, shortcut: '/' }, { id: 'settings', label: 'تنظیمات حساب', group: 'ناوبری', description: 'پروفایل و اعلانها', icon: <Icon name="settings" size="sm" /> }, { id: 'theme', label: 'تغییر تم تیره', group: 'نمایش', icon: <Icon name="theme.dark" size="sm" />, keywords: ['dark', 'تاریک'] },];export function AppCommandMenu({ onRun }: { onRun: (id: string) => void }) { return ( <CommandMenu items={commands} onSelect={(item) => onRun(item.id)} trigger={<Button variant="secondary">پالت فرمان</Button>} /> );}حالت پیشرفته: جستجوی سرور با فیلتر بیرونی
import { CommandMenu } from '@tokapps/tuk';import type { CommandItem } from '@tokapps/tuk';import { useState } from 'react';export function RemoteCommandMenu({ search, onRun }: { search: (q: string) => Promise<CommandItem[]>; onRun: (id: string) => void }) { const [items, setItems] = useState<CommandItem[]>([]); return ( <CommandMenu items={items} filter={false} limit={20} label="جستجوی ایدهها" placeholder="جستجوی ایده یا انجمن…" onQueryChange={async (query) => setItems(await search(query))} onSelect={(item) => onRun(item.id)} /> );}حالت خالی و بدون راهنما
import { CommandMenu } from '@tokapps/tuk';import type { CommandItem } from '@tokapps/tuk';const commands: readonly CommandItem[] = [{ id: 'theme', label: 'تغییر تم تیره', group: 'نمایش' }];export function MinimalCommandMenu() { return ( <CommandMenu items={commands} hotkey={false} hints={false} emptyLabel="فرمانی با این عبارت پیدا نشد" onSelect={() => undefined} defaultOpen={false} /> );}همهٔ پیکربندیها
| پراپ | نوع | پیشفرض | توضیح |
|---|---|---|---|
| کپی کد | کپی کد | — (الزامی) | فهرست کنشها. |
| کپی کد | کپی کد | — (الزامی) | با انتخاب آیتم صدا زده میشود؛ سپس پالت بسته میشود. |
| کپی کد | کپی کد | — | محرک باز کردن؛ بدون آن با کپی کد کنترل کنید یا از میانبر استفاده کنید. |
| کپی کد | کپی کد | — | حالت کنترلشده. |
| کپی کد | کپی کد | کپی کد | حالت اولیه. |
| کپی کد | کپی کد | — | با هر تغییر باز/بسته. |
| کپی کد | کپی کد | بینهایت | سقف تعداد نتایج نمایشی. |
| کپی کد | کپی کد | — | با هر تغییر پرسوجو و با بستهشدن (کپی کد) صدا زده میشود؛ برای جستجوی سرور. |
| کپی کد | کپی کد | کپی کد | کپی کد یعنی فهرست کپی کد از بیرون فیلتر شده و همان ترتیب نمایش داده میشود. |
| کپی کد | کپی کد یا کپی کد | کپی کد | راهنمای کیبورد در پانویس؛ کپی کد برای پنهان کردن. |
| کپی کد | کپی کد | کپی کد | نام پالت (نام دسترسی دیالوگ و فهرست). |
| کپی کد | کپی کد | کپی کد | متن راهنمای ورودی. |
| کپی کد | کپی کد | کپی کد | پیام بدون نتیجه؛ همچنین در اعلان تعداد استفاده میشود. |
| کپی کد | کپی کد | کپی کد | برچسب دکمهٔ بستن. |
| کپی کد | کپی کد | کپی کد | برچسب دکمهٔ پاککردن جستجو. |
| کپی کد | کپی کد یا کپی کد | کپی کد | میانبر سراسری باز/بسته؛ کپی کد یعنی کپی کد یا کپی کد. اگر چند پالت در صفحه است، فقط یکی میانبر داشته باشد. |
| کپی کد | کپی کد | — | مقصد صدای این نمونه؛ بدون آن، مقصد سراسری (در صورت ثبت) استفاده میشود. |
| کپی کد | کپی کد (کپی کد یا کپی کد) | کپی کد | رفتار چاپ (ر.ک. بخش چاپ). |
| کپی کد | کپی کد | — | جهت صریح؛ بدون مقدار، جهت از ساختار صفحه میآید. |
| کپی کد | کپی کد | — | برچسب دامنه برای تمدهی مشتقها (کپی کد). |
| کپی کد | کپی کد | — | کلاس روی پنل. |
فیلدهای کپی کد
| فیلد | نوع | پیشفرض | توضیح |
|---|---|---|---|
| کپی کد | کپی کد | — (الزامی) | شناسهٔ یکتا؛ در کپی کد برگردانده میشود. |
| کپی کد | کپی کد | — (الزامی) | عنوان آیتم؛ اصلیترین مبنای جستجو. |
| کپی کد | کپی کد | — | توضیح زیر عنوان؛ در جستجو هم دیده میشود. |
| کپی کد | کپی کد | — | آیکون، معمولاً کپی کد با نام معنایی. |
| کپی کد | کپی کد | — | میانبر نمایشی؛ همیشه LTR. |
| کپی کد | کپی کد | — | واژههای جستجوی اضافه (مترادفها). |
| کپی کد | کپی کد | — | عنوان گروه؛ گروهها به ترتیب اولین ظهور چیده میشوند. |
| کپی کد | کپی کد | کپی کد | آیتم غیرفعال. |
ساختار و اسلاتها
ترتیب اجزا: کپی کد · کپی کد شامل کپی کد با کپی کد (ذرهبین، ورودی، خط فوکوس، پاککردن)، کپی کد (گروهها، آیتمها، حالت خالی)، کپی کد (راهنما و تعداد)، کپی کد و کپی کد.
- بنیان ثابت (اسلاتهای کپی کد): کپی کد · کپی کد · کپی کد (با کپی کد) · کپی کد · کپی کد · کپی کد · کپی کد · کپی کد · کپی کد · کپی کد (با کپی کد، کپی کد شامل کپی کد و کپی کد، کپی کد، کپی کد، کپی کد) · کپی کد · کپی کد (با کپی کد و کپی کد) · کپی کد · کپی کد.
- قابلتغییر: کپی کد روی پنل، توکنهای کپی کد و هویت بصری (حرکت) از طریق کپی کد در والد محرک.
همهٔ حالتها
| حالت | نشانه (data-attribute یا prop) | نمایش |
|---|---|---|
| بسته (پیشفرض) | پالت در DOM نمایش داده نمیشود | فقط محرک یا میانبر در دسترس است. |
| باز | کپی کد · کپی کد · کپی کد | پنل با محو و بزرگشدن ظاهر میشود؛ ورودی فوکوس میگیرد. |
| بستهشدن | کپی کد | پنل محو میشود؛ جستجو پاک میشود. |
| typing | کپی کد تا ۴۲۰ms پس از آخرین کلید | خط فوکوس و ورودی حرکت نرم تایپ را نشان میدهند. |
| filtering | تغییر کپی کد | نتایج با همان واژهها فیلتر و بر اساس نزدیکی به برچسب مرتب میشوند؛ واژههای تطبیق با کپی کد برجسته میشوند. |
| empty | کپی کد | پیام کپی کد همراه آیکون نمایش داده میشود؛ اعلان صفحهخوان هم همان پیام را میخواند. |
| آیتم focused (فوکوس مجازی) | کپی کد | پسزمینهٔ کپی کد، نوار نشانگر در لبه، آیکون رنگی و کپی کد نمایان. |
| آیتم hover | کپی کد | پسزمینهٔ نرم. |
| آیتم focus-visible | کپی کد | بدون کادر تیز؛ در کنتراست بالا کادر برمیگردد. |
| آیتم disabled | کپی کد (prop کپی کد) | کمرنگ و بدون پاسخ. |
| کنتراست بالا | کپی کد | کادر فوکوس روی آیتم فعال. |
| کاهش حرکت | کپی کد یا کپی کد | همهٔ انیمیشنها حذف میشوند. |
قرارداد پوشش (Overlay Contract)
- دام فوکوس: فوکوس درون پالت حبس میشود (FocusScope با contain)؛ با باز شدن به پالت میرود و با بسته شدن به محرک برمیگردد. فوکوس روی ورودی میماند و آیتم فعال با کپی کد مجازی خوانده میشود.
- Escape: اگر جستجو خالی نیست، ابتدا جستجو پاک میشود؛ در غیر این صورت پالت بسته میشود. این رفتار از کپی کد پیشفرض React Aria میآید و در کد صراحتاً نوشته نشده است.
- پسزمینه (backdrop): کلیک روی پرده پالت را میبندد. این رفتار همیشه فعال است و پراپی برای خاموش کردن آن در کپی کد تعریف نشده است.
- قفل اسکرول: اسکرول صفحهٔ زیرین قفل میشود (usePreventScroll)؛ فقط فهرست نتایج اسکرول میخورد و کپی کد دارد.
- کشیدن برای بستن: ندارد.
- تودرتو: پوشش تودرتو پشتیبانی میشود؛ فقط بالاترین پوشش تعاملی است و بقیه کپی کد میشوند.
تغییرات مجاز برای توسعهدهنده
- variant: یک ظاهر (کپی کد).
- size: یک اندازه (کپی کد؛ عرض کپی کد).
- هویت بصری (حرکت): کپی کد روی والد محرک. هر هویت یک حرکت دارد: کپی کد با کپی کد، کپی کد با کپی کد، کپی کد با کپی کد، کپی کد با کپی کد، کپی کد با کپی کد و کپی کد با کپی کد. تغییر در هویت فقط اسلاتهای مجاز را متحرک میکند.
- نقاط توسعه: کپی کد، کپی کد، کپی کد، کپی کد، کپی کد، کپی کد، کپی کد، کپی کد، کپی کد، کپی کد، کپی کد، کپی کد، کپی کد، کپی کد، توکنهای کپی کد، کپی کد، کپی کد، کپی کد، کپی کد و سایر کپی کد.
تغییرات ممنوع (بنیان ثابت)
- ترتیب و نام اسلاتهای کپی کد (همهٔ هویتها به آنها وابستهاند).
- هندسهٔ پایه: کپی کد و کپی کد پنل و ردیفهای آیتم.
- رفتار کیبورد: کپی کد، کپی کد، کپی کد، کپی کد و کپی کد؛ و فوکوس مجازی روی ورودی.
- ARIA: پنل نامدار با کپی کد، ناحیهٔ کپی کد برای اعلان تعداد، و کپی کد.
- کاهش حرکت: هویتها نباید آن را لغو کنند.
- هدف لمسی ۴۴px برای دکمهها و آیتمها.
RTL، کیبورد و صفحهخوان
- RTL: پیکره منطقی است؛ میانبر LTR و ایزوله است. ی/ک عربی و ارقام فارسی/عربی در جستجو یکی میشوند.
- کیبورد: کپی کد یا کپی کد باز و بسته میکند؛ تایپ فیلتر میکند؛ کپی کد و کپی کد بین نتایج حرکت میکنند و فوکوس روی ورودی میماند؛ کپی کد کنش را اجرا و پالت را میبندد؛ کپی کد ابتدا جستجو را پاک میکند و سپس میبندد.
- صفحهخوان: پنل کپی کد با نام کپی کد؛ نتایج کپی کد با منوی مجازی؛ ناحیهٔ کپی کد تعداد نتایج یا کپی کد را بعد از هر فیلتر اعلام میکند.
صدا، حرکت، چاپ و کاهش حرکت
- صدا: opt-in است. کپی کد، کپی کد و کپی کد همگی کپی کد هستند؛ کپی کد پس از اجرای کنش پخش میشود. مقصد: کپی کد روی همین نمونه، یا مقصد سراسری که با کپی کد ثبت شده است؛ بدون هیچکدام بیصداست. معادل بصری: بسته شدن پالت و اجرای کنش.
- حرکت: ورود پنل با کپی کد (کپی کد، کپی کد)؛ خط فوکوس زیر جستجو با کپی کد از مرکز باز میشود؛ ردیفها پلکانی با کپی کد و تأخیر کپی کد × کپی کد ظاهر میشوند. اسلاتهای متحرک هویت: کپی کد، کپی کد، کپی کد، کپی کد، کپی کد، کپی کد، کپی کد، کپی کد، کپی کد. حالتهای هویت: کپی کد، کپی کد، کپی کد.
- کاهش حرکت: با کپی کد یا کپی کد همهٔ انیمیشنها حذف میشوند.
- چاپ: پیشفرض کپی کد و در چاپ پنهان است. در کد کپی کد قاعدهٔ کپی کد بدون شرط کپی کد پالت را پنهان میکند؛ یعنی کپی کد عملاً اثری ندارد.
توکنها
- فایل توکنهای کامپوننتی: کپی کد (گروه overlays؛ این کامپوننت توکن کپی کد اختصاصی ندارد).
- توکنهای سطح کامپوننت مصرفی: کپی کد، کپی کد، کپی کد، کپی کد، کپی کد، کپی کد، کپی کد، کپی کد، کپی کد، کپی کد، کپی کد، کپی کد، کپی کد، کپی کد، کپی کد و سایر موارد در کپی کد.
- توکنهای معنایی مصرفی: کپی کد، کپی کد، کپی کد، کپی کد، کپی کد، کپی کد، کپی کد، کپی کد.
- فهرست کامل: کپی کد.
قرارداد ARCH
- آیکونهای جستجو، آیتمها و خطا فقط با کپی کد و نام معنایی (مثلاً کپی کد، کپی کد، کپی کد) تعیین میشوند؛ مسیر asset در کد نمیآید.
- تم فقط حرکت و توکنهای مجاز را تغییر میدهد؛ ساختار و ARIA ثابتاند.
- میانبر کپی کد معادل صفحهکلید است؛ دکمهٔ محرک و کنشها معادل اشارهگرند.
نکات
- برای ناوبری صرف بین صفحهها از CommandNavigation استفاده کنید.
- برای کنشهای یک ناحیه از ContextMenu استفاده کنید.
- برای انتخاب از چند گزینهٔ کم از Select استفاده کنید؛ پالت برای گزینههای کم مناسب نیست.
- برای فرمهای کامل از ResponsiveDialog یا Dialog استفاده کنید.