میان‌بر صفحه‌کلید (KeyboardShortcut)

رندر هوشمند و وابسته به پلتفرم کلیدهای میان‌بر — ⌘ در مک، Ctrl در ویندوز

معرفی

KeyboardShortcut یک رندرکنندهٔ کلید وابسته به پلتفرم است. یک آرایهٔ keys می‌گیرد و بر اساس سیستم‌عامل بازدیدکننده، Meta←⌘/Ctrl، Alt←⌥/Alt، Shift←⇧، Enter←↵، فلش‌ها و … را resolve می‌کند و سپس آن‌ها را قالب‌بندی می‌کند (⌘K، Ctrl Enter). برگرفته از KeyboardShortcut واقعی Studio، جایی که داخل کنترل‌های پرترافیک (دکمهٔ Run در ویرایشگر SQL، منوی دستور) می‌نشیند.

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

برای نمایش یک میان‌بر که باید با پلتفرم کاربر تطبیق پیدا کند (⌘ در مک، Ctrl در دیگر سیستم‌ها)
برای ترکیب چند کلید (Meta + K، Shift + S) به‌صورت یک برچسب قالب‌بندی‌شده
کنار اقدامات (دکمهٔ اجرا، آیتم منو، فیلد جستجو) برای آموزش میان‌بر

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

برای نمایش یک کلید ثابت و تک که نیازی به منطق پلتفرم ندارد — از Kbd استفاده کنید
برای ثبت واقعی میان‌بر (شنیدن کلیدها) — از useHotkeys/HotkeyProvider استفاده کنید؛ این کامپوننت فقط نمایشی است

باز کردن جستجو:Ctrl K

ارسال فرم:Ctrl ↵

ذخیره پیش‌نویس⇧S

تفاوت Kbd و KeyboardShortcut

هر دو کلید را نشان می‌دهند، اما نقش‌شان متفاوت است:

Kbd — عنصر پایهٔ «گنگ» <kbd>: یک کپِ کلید ثابت، بدون هیچ منطقی. وقتی می‌خواهید یک کلید ثابت را به‌صورت ایستا رندر کنید (مثل «Ctrl + S» بدون تطبیق پلتفرم) درست است. برای ترکیب چند کپ، آن‌ها را داخل KbdGroup بگذارید.
KeyboardShortcut — نسخهٔ هوشمند: یک آرایهٔ keys می‌گیرد، هر کلید را per-platform resolve می‌کند (⌘ در مقابل Ctrl) و ترکیب را قالب‌بندی می‌کند. برای میان‌برهای واقعی که باید با OS تطبیق پیدا کنند، این را انتخاب کنید — این کامپوننت جای Kbd را برای آن کار می‌گیرد.

قاعدهٔ سرانگشتی

کلید ثابت و بدون منطق پلتفرم → Kbd. میان‌بری که باید ⌘/Ctrl را per-platform حل کند یا چند کلید را ترکیب کند → KeyboardShortcut.

استفاده

import { KeyboardShortcut } from '@partodata/ui'

export default function SearchHint() {
  return (
    <div className="flex items-center gap-2">
      <span className="text-sm">باز کردن جستجو:</span>
      <KeyboardShortcut keys={['Meta', 'K']} />
    </div>
  )
}

روی مک، Meta به ⌘ و روی سایر سیستم‌ها به Ctrl تبدیل می‌شود. تشخیص پلتفرم پس از mount اجرا می‌شود (تا SSR و اولین رندر کلاینت هماهنگ بمانند و mismatch رخ ندهد) و به‌صورت پیش‌فرض برچسب‌های غیرمک را نشان می‌دهد.

حالت‌ها و انواع

واریانت pill (پیش‌فرض)

یک چیپ خط‌دار.

<KeyboardShortcut keys={['Meta', 'Enter']} />

واریانت inline

یک راهنمای درون‌خطی کم‌رنگ‌تر برای متن‌های جریان‌دار.

<KeyboardShortcut variant="inline" keys={['Shift', 'S']} />

کلیدهای خاص

Meta، Alt، Shift، Enter، Esc، Tab و فلش‌ها (ArrowUp/ArrowDown/ArrowLeft/ArrowRight) به نماد یا برچسب مناسب resolve می‌شوند. کلیدهای تک‌کاراکتری پشت هم فشرده می‌شوند (⌘K) و کلیدهای چندکاراکتری با فاصله جدا می‌شوند (Ctrl Enter).

<KeyboardShortcut keys={['Meta', 'ArrowUp']} />
<KeyboardShortcut keys={['Esc']} />

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

بکنید

برای میان‌برهای واقعی از KeyboardShortcut استفاده کنید تا ⌘/Ctrl per-platform درست نمایش داده شود - نام کلیدهای modifier را استاندارد بدهید (Meta, Alt, Shift) تا نماد درست resolve شود - برای متن‌های درون‌خطی از variant="inline" استفاده کنید تا میان‌بر شلوغ دیده نشود

نکنید

برای میان‌بر مک، دستی ⌘ را هاردکد نکنید؛ keys={['Meta', ...]} بدهید تا در ویندوز هم درست شود - این کامپوننت کلیدها را نمی‌شنود؛ برای ثبت واقعی میان‌بر از useHotkeys استفاده کنید - برای یک کپ ثابت و ساده از این استفاده نکنید؛ Kbd سبک‌تر و درست‌تر است

جدول ویژگی‌ها

KeyboardShortcut

Prop

Type

دسترسی‌پذیری

تشخیص پلتفرم پس از mount اجرا می‌شود تا SSR و اولین رندر کلاینت یکسان بمانند و hydration mismatch رخ ندهد
این کامپوننت صرفاً نمایشی است؛ برای عملکرد واقعی میان‌بر، رویداد کیبورد را جدا با useHotkeys ثبت کنید و مطمئن شوید همان اقدام از راه دیگری (دکمه/منو) هم در دسترس است
برچسب کلید به‌اندازهٔ کافی خوانا انتخاب شده (Esc به‌جای ⎋ و Tab به‌جای ⇥) تا برای همه قابل‌فهم باشد

کامپوننت‌های مرتبط

Kbd — برای یک کپِ کلید ثابت و بدون منطق پلتفرم، از Kbd (و برای گروه، KbdGroup) استفاده کنید
use-hotkeys — برای ثبت واقعی میان‌برها (شنیدن کلیدها)، از هوک useHotkeys استفاده کنید
HotkeyProvider — برای مدیریت متمرکز میان‌برها در سطح برنامه، از HotkeyProvider استفاده کنید
CommandPalette — پالت دستور معمولاً میان‌برها را با KeyboardShortcut کنار هر آیتم نشان می‌دهد