اختصارات لوحة المفاتيح باستخدام 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. يفتح المفتاح ? شاشة مساعدة تضم الروابط الأربعة، مجمّعة تحت «التنقل»، ويفتح الاختصار 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");

تُقرأ المعالجات من مرجع عند وصول مفتاح، لذا لا يستخدم الإغلاق الجديد عند كل عرض قيمًا قديمة أبدًا.

#شاشة المساعدة واللوحة

يفتح المكوّن <KeyHelp> عند الضغط على ? ويسرد كل ربط نشط ذي تسمية حسب المجموعة. تغيّر الخاصيتان keys و title مفتاح الفتح والعنوان.

يفتح المكوّن <CommandPalette> عند الضغط على Ctrl+K أو Ctrl+P. يجري مطابقة تقريبية ضمن commands وكل ربط ذي تسمية، ويبرز الأحرف المطابقة. يُغلق قبل تنفيذ الأمر، لذا يمكن للأمر فتح نافذة مشروطة خاصة به.

تنسّق الدالة formatKeys ربطًا للعرض. يعيد الاستدعاء formatKeys("ctrl+shift+p") القيمة ⌃⇧P في macOS والقيمة ctrl+shift+P في الأنظمة الأخرى، ويعرض المكوّن <Kbd> مفتاحًا واحدًا بالتنسيق نفسه.

تتوفر useKeymap و <KeyHelp> و <KeyHints> و <StatusBar> و <CommandPalette> في ⁦Text.js 1.0⁩. يوجد المرجع في لوحة المفاتيح.