ناوبری فرمانی — CommandNavigation

پالت جستجوی صفحه‌ها برای رفتن سریع به مقصدها، با کلیدهای Mod+Kکپی کد و تایپ فیلتر. این کامپوننت یک لایهٔ نازک روی CommandMenu است: ظاهر، فوکوس و کیبورد آن را به ارث می‌برد و فقط مقصد را به‌جای اجرای کنش، به onNavigateکپی کد می‌دهد. مکمل ناوبری اصلی است، نه جایگزین آن؛ کاربر باید بتواند بدون پالت هم به صفحه‌ها برسد.

وضعیت: beta · لایه: ۳ (@tokapps/tukکپی کد) · کد: packages/tuk/src/navigation/command-navigation/کپی کد

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

نمونهٔ زنده

کد قابل کپی

پالت پایه با محرک دکمه

import { Icon } from '@tokapps/icons';import { Button, CommandNavigation } from '@tokapps/tuk';const sampleDestinations = [  { id: 'home', label: 'خانه', href: '/', group: 'صفحه‌ها', icon: <Icon name="home" size="sm" /> },  { id: 'forum', label: 'انجمن ایده‌ها', href: '/forum', group: 'صفحه‌ها', icon: <Icon name="product.ideation" size="sm" />, keywords: ['ایده', 'idea'] },  { id: 'settings', label: 'تنظیمات حساب', href: '/settings', group: 'حساب', description: 'پروفایل و اعلان‌ها', icon: <Icon name="settings" size="sm" /> },];<CommandNavigation  items={sampleDestinations}  onNavigate={() => undefined}  trigger={<Button variant="secondary">رفتن به… (⌘K)</Button>}/>

اتصال به روتر و برچسب سفارشی

import { useRouter } from 'next/navigation';import { CommandNavigation } from '@tokapps/tuk';const destinations = [  { id: 'home', label: 'خانه', href: '/', group: 'صفحه‌ها' },  { id: 'settings', label: 'تنظیمات حساب', href: '/settings', group: 'حساب', description: 'پروفایل و اعلان‌ها' },];export function PanelSearch() {  const router = useRouter();  return (    <CommandNavigation      items={destinations}      onNavigate={(href) => router.push(href)}      label="جستجوی صفحه‌های پنل"      placeholder="نام صفحه را بنویسید…"      hotkey="Mod+J"    />  );}

حالت کنترل‌شده و بدون میان‌بر

import { useState } from 'react';import { CommandNavigation } from '@tokapps/tuk';export function ControlledPalette() {  const [open, setOpen] = useState(false);  return (    <CommandNavigation      items={[]}      open={open}      onOpenChange={setOpen}      hotkey={false}      emptyLabel="هیچ صفحه‌ای با این عنوان نیست"      onNavigate={(href) => window.location.assign(href)}    />  );}

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

حذف hrefکپی کد از آیتم مجاز نیست؛ هر مقصد باید مسیر داشته باشد. پراپ renderLinkکپی کد و asکپی کد در این کامپوننت تعریف نشده‌اند؛ انتقال فقط از طریق onNavigateکپی کد انجام می‌شود.

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

همهٔ حالت‌ها

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

• مقصدها: itemsکپی کد با groupکپی کد، descriptionکپی کد، keywordsکپی کد، iconکپی کد.
• کنترل باز بودن: openکپی کد و onOpenChangeکپی کد، یا defaultOpenکپی کد.
• محرک: triggerکپی کد (هر ReactElementکپی کد).
• میان‌بر: hotkeyکپی کد (رشته) یا falseکپی کد.
• برچسب‌ها: labelکپی کد، placeholderکپی کد، emptyLabelکپی کد (همه قابل ترجمه).
• مسیر: onNavigateکپی کد برای روتر خود.
• جهت: dirکپی کد.
• کلاس: classNameکپی کد روی ریشه.
• صدا: onSoundکپی کد برای مقصد رویدادهای صوتی این نمونه.
• توکن سطح کامپوننت: --tds-nav-item-*کپی کد، --tds-nav-active-*کپی کد، --tds-nav-transitionکپی کد.

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

• تبدیل پالت به ناوبری بدون مقصد یا بدون hrefکپی کد.
• بازنویسی ساختار CommandMenu (data-scope="navigation"کپی کد باید حفظ شود).
• حبس فوکوس در پالت و بازگشت فوکوس به محرک؛ این رفتار از CommandMenu می‌آید.
• حذف پیام حالت خالی یا role="status"کپی کد آن.
• رنگ خام یا گرادیان در کد رابط.
• استفاده از این کامپوننت برای کنش‌های غیرناوبری؛ برای آن‌ها CommandMenu را به کار ببرید.

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

• RTL: مثل CommandMenu؛ یکسان‌سازی ی/ک و ارقام؛ میان‌بر همچنان به‌صورت LTR (Mod+K) خوانده می‌شود.
• Mod+K (Ctrl+K در ویندوز): باز یا بستن پالت.
• تایپ: فیلتر فهرست.
• ArrowDown / ArrowUp: نتیجهٔ بعدی یا قبلی.
• Enter: رفتن به صفحه انتخاب‌شده (onNavigateکپی کد).
• Escape: پاک کردن ورودی، سپس بستن پالت.
• صفحه‌خوان: پنل نام‌دار (labelکپی کد)، نتایج به‌صورت منو و ناحیهٔ وضعیت برای تعداد نتایج؛ حالت خالی با role="status"کپی کد.
• فوکوس: روی ورودی؛ حبس درون پالت؛ بازگشت به محرک هنگام بسته شدن.

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

• صدا: opt-in. رویدادهای openکپی کد و selectکپی کد با صدای tapکپی کد از CommandMenu گزارش می‌شوند و به onSoundکپی کد می‌رسند. پراپ soundکپی کد در کد این کامپوننت تعریف نشده است؛ مقصد سراسری صدا در کد این فایل تعریف نشده است. بدون onSoundکپی کد این نمونه بی‌صداست.
• معادل بصری: بسته شدن پالت و تغییر صفحه.
• حرکت: semantic motion با نام overlay.enterکپی کد روی opacityکپی کد و scaleکپی کد. در prefers-reduced-motionکپی کد و data-reduced-motion="true"کپی کد بدون انیمیشن است.
• چاپ: پیش‌فرض در چاپ پنهان است؛ CSS فعلی display: noneکپی کد را بدون توجه به پراپ printکپی کد اعمال می‌کند.

توکن‌ها

معنایی مصرفی: --tds-fg-defaultکپی کد، --tds-fg-mutedکپی کد، --tds-fg-subtleکپی کد، --tds-focus-ringکپی کد، --tds-surface-hoverکپی کد، --tds-surface-pressedکپی کد.

سطح کامپوننت: --tds-nav-active-bgکپی کد، --tds-nav-active-fgکپی کد، --tds-nav-badge-sizeکپی کد، --tds-nav-item-font-sizeکپی کد، --tds-nav-item-font-weightکپی کد، --tds-nav-item-gapکپی کد، --tds-nav-item-heightکپی کد، --tds-nav-item-padding-inlineکپی کد، --tds-nav-item-radiusکپی کد، --tds-nav-transitionکپی کد.

مسیر تعریف: packages/tokens/src/component/navigation.cssکپی کد؛ فهرست مصرف در CommandNavigation.tokens.tsکپی کد. ظاهر پالت از CommandMenu می‌آید.

قرارداد ARCH

• آیکون‌ها فقط با <Icon name>کپی کد و نام معنایی (مثل homeکپی کد، settingsکپی کد) داده می‌شوند؛ بدون مسیر asset.
• تم فقط حرکت و توکن را تغییر می‌دهد؛ ساختار پالت و رفتار کیبورد ثابت‌اند.
• این کامپوننت gesture ندارد؛ کنترل کامل با صفحه‌کلید ممکن است.
• ناوبری agnostic است؛ مقصد را به onNavigateکپی کد می‌دهد و خودش به روتر وابسته نیست.

نکات

• برای ناوبری اصلی همیشه‌آشکار از ناوبری بالا یا پنل کناری استفاده کنید.
• این کامپوننت تنها راه رسیدن به صفحه‌ها نیست؛ برای کاربران موبایل، داک شیشه‌ای ثابت پایین صفحه (در همه صفحه‌ها حاضر است، Dock) مقصدهای اصلی را فراهم می‌کند.
• برای اجرای کنش‌ها (نه رفتن به صفحه) از CommandMenu استفاده کنید.
• برای سایت‌های کوچک با چند صفحه، این پالت لازم نیست.