میان‌برهای صفحه‌کلید با useKeymap

تا پیش از این، برنامه‌های Text.js کلیدها را در هوک useInput مدیریت می‌کردند و بار دوم آن‌ها را دستی در پابرگ <KeyHint> فهرست می‌کردند. هوک useKeymap هر دو را با یک اعلان جایگزین می‌کند.

import { CommandPalette, KeyHelp, KeyHints, StatusBar, Text, useKeymap } from "@textjs/react";export default function Sessions() {  useKeymap(    {      "j, down": { label: "Next", run: next, hint: true },      "k, up": { label: "Previous", run: previous },      "g g": { label: "Go to top", run: top },      "ctrl+s": { label: "Save", run: save, hint: true },    },    { group: "Navigation" },  );  return (    <>      <StatusBar right={<Text color="subtle">main</Text>}>        <KeyHints />      </StatusBar>      <CommandPalette commands={commands} />      <KeyHelp />    </>  );}

فشردن j تابع next را اجرا می‌کند. در macOS، کامپوننت <KeyHints> عبارت‌های j/↓ Next و ⌃S Save را در پابرگ نشان می‌دهد، چون این اتصال‌ها گزینهٔ hint را تنظیم کرده‌اند. کلید ? صفحهٔ راهنمایی با هر چهار اتصال در گروه Navigation باز می‌کند و میان‌بر Ctrl+K پالتی را باز می‌کند که می‌تواند آن‌ها را جست‌وجو کند.

#نحو کلیدها

اتصال یک تابع رسیدگی است، یا شیئی با ویژگی‌های label، group، hint، command، disabled و noRepeat. تنظیم command: false اتصال برچسب‌دار را از پالت کنار می‌گذارد. اتصال‌های بدون برچسب کار می‌کنند، اما در صفحهٔ راهنما و پالت نمایش داده نمی‌شوند.

#مسیریابی

هر نقشهٔ کلیدها یک تابع رسیدگی useInput ثبت می‌کند، پس قواعد فعلی ورودی اعمال می‌شوند. کامپوننت <Input> دارای تمرکز ابتدا کلیدها را پردازش می‌کند، چون ویرایشگرها با اولویت 10 و نقشه‌های کلیدها با اولویت 0 به رویدادها گوش می‌دهند. کلیدی که تطبیق پیدا کند، انتشار رویداد را متوقف می‌کند. کامپوننت <Modal> باز، اتصال‌های بیرون از خود را غیرفعال می‌کند، مگر اینکه نقشهٔ کلیدها مقدار global: true را ارسال کند.

دنباله‌ها در همان تابع رسیدگی تطبیق داده می‌شوند. کلیدی که دنباله‌ای را آغاز می‌کند در حالت انتظار نگه داشته می‌شود و انتشار رویداد را متوقف می‌کند، و اگر کلید بعدی پس از گذشت بیش از sequenceTimeout (به‌طور پیش‌فرض 1,000 ms) برسد، دنباله بازنشانی می‌شود:

if (p.events.length > 0 && now - p.at > sequenceTimeout) p.events = [];

#یک رجیستری برای هر ریشه

اتصال‌های برچسب‌دار در رجیستری متعلق به ریشهٔ کنسول منتشر می‌شوند. کامپوننت‌های <KeyHelp>، <KeyHints> و <CommandPalette> از آن می‌خوانند و کامپوننت‌های خودتان هم می‌توانند از طریق useKeymapBindings() همین کار را انجام دهند. وقتی یک مودال باز است، رجیستری فقط اتصال‌های داخل آن را برمی‌گرداند، بنابراین صفحهٔ راهنما کلیدهایی را فهرست می‌کند که در همان لحظه کار می‌کنند.

نقشه‌های کلیدها معمولاً به‌صورت درون‌خطی نوشته می‌شوند که در هر رندر شیء جدیدی ایجاد می‌کند. برای پایین نگه داشتن هزینهٔ این کار، نقشهٔ کلیدها برچسب‌هایش را فقط زمانی دوباره منتشر می‌کند که شکل قابل‌نمایش آن‌ها تغییر کند:

// Publish labels only when the visible shape changes (inline keymap objects are fine).const signature = compiled  .map((c) => `${c.keys}\u0000${c.binding.label ?? ""}\u0000${c.binding.group ?? ""}\u0000${c.binding.hint ? 1 : 0}${c.binding.command === false ? 0 : 1}\u0000${c.binding.disabled ? 1 : 0}`)  .join("\u0001");

هنگام رسیدن رویداد کلید، توابع رسیدگی از یک ref خوانده می‌شوند، بنابراین closure جدید در هر رندر هرگز قدیمی نیست.

#صفحهٔ راهنما و پالت

کامپوننت <KeyHelp> با کلید ? باز می‌شود و تمام اتصال‌های برچسب‌دار فعال را بر اساس گروه فهرست می‌کند. ویژگی‌های keys و title کلید فعال‌سازی و عنوان را تغییر می‌دهند.

کامپوننت <CommandPalette> با میان‌بر Ctrl+K یا Ctrl+P باز می‌شود. این کامپوننت در میان commands شما و تمام اتصال‌های برچسب‌دار تطبیق تقریبی انجام می‌دهد و حروف تطبیق‌یافته را برجسته می‌کند. پیش از اجرای فرمان بسته می‌شود، بنابراین هر فرمان می‌تواند مودال خودش را باز کند.

تابع formatKeys یک اتصال را برای نمایش رندر می‌کند. فراخوانی formatKeys("ctrl+shift+p") در macOS مقدار ⌃⇧P و در سایر محیط‌ها مقدار ctrl+shift+P را برمی‌گرداند و کامپوننت <Kbd> یک کلید تکی را با همان قالب‌بندی رندر می‌کند.

هوک useKeymap و کامپوننت‌های <KeyHelp>، <KeyHints>، <StatusBar> و <CommandPalette> در ⁦Text.js 1.0⁩ ارائه می‌شوند. مرجع در بخش صفحه‌کلید است.