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

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

معرفی

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

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

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

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

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

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

ارسال فرم:Ctrl ↵

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

یک نمایش برای میان‌بر

KeyboardShortcut تنها نمایش میان‌بر در سیستم طراحی است:

میان‌بر واقعی ← keys={['Meta', 'K']}؛ هر کلید برای سیستم‌عامل کاربر حل می‌شود (⌘ در مقابل Ctrl).
یک کلید ثابت ← <KeyboardShortcut>Esc</KeyboardShortcut>؛ همان‌طور که نوشته شده کشیده می‌شود.
درون منو ← keys را به DropdownMenuShortcut، CommandShortcut یا ContextMenuShortcut بدهید؛ آن‌ها KeyboardShortcut variant="inline" را رندر می‌کنند.

عنصر رندرشده <kbd> است.

استفاده

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 استفاده کنید

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

KeyboardShortcut

Prop

Type

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

تشخیص پلتفرم پس از mount اجرا می‌شود تا SSR و اولین رندر کلاینت یکسان بمانند و hydration mismatch رخ ندهد
این کامپوننت صرفاً نمایشی است؛ برای عملکرد واقعی میان‌بر، رویداد کیبورد را جدا با useHotkeys ثبت کنید و مطمئن شوید همان اقدام از راه دیگری (دکمه/منو) هم در دسترس است
برچسب کلید به‌اندازهٔ کافی خوانا انتخاب شده (Esc به‌جای ⎋ و Tab به‌جای ⇥) تا برای همه قابل‌فهم باشد
عنصر ریشه همیشه dir="ltr" می‌گیرد. نمادهای ⌘ ⇧ ⌥ ↵ و پیکان‌ها از نظر یونیکد «خنثی» (bidi class ON) هستند و در یک صفحهٔ RTL بدون این جداسازی، ترتیب نمایش برعکس می‌شود («⌘K» به‌شکل «K⌘» و «Ctrl ↵» به‌شکل «↵ Ctrl» رسم می‌شد). با dir="ltr" محتوای میان‌بر پاراگراف bidi مستقل خودش را می‌سازد و همیشه چپ‌به‌راست خوانده می‌شود

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

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