useHotkeys

ثبت میان‌برهای صفحه‌کلید با پشتیبانی cross-platform از کلید mod (Cmd/Ctrl) و مدیریت scope

معرفی

هوک useHotkeys یک میان‌بر صفحه‌کلید را ثبت می‌کند و هنگام unmount به‌صورت خودکار حذفش می‌کند. گرامر combo از mod پشتیبانی می‌کند (روی macOS تبدیل به ⌘ و در سایر سیستم‌ها Ctrl می‌شود)، و به‌صورت هوشمند وقتی کاربر در حال تایپ در input است، میان‌برهای بدون modifier را نادیده می‌گیرد.

چه زمانی استفاده کنیم

ثبت میان‌برهای سراسری در App Shell (مثلاً Ctrl+K برای CommandPalette)
میان‌برهای محلی برای عملیات صفحه (مثل Escape برای بستن پنل، / برای focus در جستجو)
میان‌بر وظایف مشخص: Mod+S برای ذخیره، Mod+Shift+P برای پالت فرمان‌ها

چه زمانی استفاده نکنیم

برای event های فرم یا primitive های Radix که خودشان keyboard handling دارند
برای استفاده‌ی همزمان با Inputها بدون modifier — به‌صورت پیش‌فرض رد می‌شود (برای تجربه‌ی تایپ)

استفاده

پایه

import { useHotkeys } from '@parto-system-design/ui'

function AppShell() {
  const [paletteOpen, setPaletteOpen] = React.useState(false)

  useHotkeys('mod+k', () => setPaletteOpen((v) => !v))

  return <CommandPalette open={paletteOpen} onOpenChange={setPaletteOpen} items={items} />
}

چند combo هم‌زمان

// Escape یا Mod+W هر دو پنل را می‌بندند
useHotkeys(['escape', 'mod+w'], close, { enabled: open })

محدود به شرط

با enabled می‌توانید میان‌بر را فقط در برخی شرایط زنده نگه دارید:

useHotkeys('enter', submitForm, { enabled: isFormValid })

هدف اختصاصی (ref)

const panelRef = React.useRef<HTMLDivElement>(null)
useHotkeys('escape', closePanel, { target: panelRef })
// فقط وقتی focus داخل panelRef باشد فعال است (چون keydown bubble می‌شود)

گرامر combo

<part>[+<part>]*

بخش	توضیح
`mod`	`⌘` روی macOS، `Ctrl` در بقیه — پیشنهاد رسمی
`ctrl`	`Ctrl` صریح (بدون fallback روی Mac)
`cmd`	`⌘` (روی Mac) / `Win` (در بقیه)
`shift`	Shift
`alt`	Alt / Option
`meta`	Meta (تقریباً معادل cmd)
کلید	`k`، `enter`، `escape`، `space`، فلش‌ها، ...

مثال‌ها:

'mod+k' — ⌘K روی macOS، Ctrl+K در بقیه
'mod+shift+p' — میان‌بر سه‌کلیده
'escape' — فقط Escape
'ctrl+k' — Ctrl صریح (روی Mac ⌘ کار نمی‌کند)

پارامترها

`combo: HotkeyCombo`

یک رشته یا آرایه‌ای از رشته‌ها. آرایه به‌صورت OR تفسیر می‌شود.

`handler: (event: KeyboardEvent) => void`

callback که با تطابق فراخوانی می‌شود. event.preventDefault() پیش‌فرض اعمال می‌شود.

`options?: UseHotkeysOptions`

پراپ	نوع	پیش‌فرض	توضیح
`preventDefault`	`boolean`	`true`	فراخوانی `event.preventDefault()` هنگام تطابق
`ignoreWhenTyping`	`boolean`	`true`	نادیده گرفتن combo هنگام focus در input/textarea بدون modifier
`enabled`	`boolean`	`true`	فعال/غیرفعال کردن listener
`target`	`RefObject<HTMLElement> \| HTMLElement \| Document`	`document`	هدف listener. ref برای scope کردن میان‌بر به یک ناحیه‌ی خاص

ابزار کمکی: `formatHotkey`

برای نمایش combo در UI، از formatHotkey استفاده کنید — روی macOS سمبل‌های ⌘⇧⌥ تولید می‌کند، در ویندوز/لینوکس متن Ctrl+Shift+Alt.

import { formatHotkey } from '@parto-system-design/ui'

formatHotkey('mod+shift+p') // '⌘⇧P' (Mac) یا 'Ctrl+Shift+P' (بقیه)

راهنمای استفاده

میان‌بر سراسری را در یک نقطه متمرکز (App Shell) ثبت کنید — نه درون کامپوننت‌های صفحه که ممکن است چند بار mount/unmount شوند
وقتی Input دارید و می‌خواهید Enter را کنترل کنید، از onKeyDown خود input استفاده کنید، نه useHotkeys — چون ignoreWhenTyping فعال است
برای میان‌برهای متضاد بین صفحات (مثلاً / در یک صفحه focus می‌کند و در صفحه‌ی دیگر کنشی دیگر انجام می‌دهد)، از enabled برای context-scoping استفاده کنید