קיצורי מקשים עם 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") מחזירה ⌃⇧P ב-macOS ו-ctrl+shift+P במערכות אחרות, והרכיב <Kbd> מרנדר מקש יחיד באותו עיצוב.

הוק useKeymap והרכיבים <KeyHelp>, <KeyHints>, <StatusBar> ו-<CommandPalette> כלולים ב-⁦Text.js 1.0⁩. תיעוד הממשק נמצא בעמוד מקלדת.