Tastenkürzel mit useKeymap

Bisher verarbeitete eine Text.js-App Tasten in useInput und listete sie ein zweites Mal von Hand in einer Fußzeile mit <KeyHint> auf. useKeymap ersetzt beides durch eine Deklaration.

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 />    </>  );}

Ein Druck auf j führt next aus. Unter macOS zeigt <KeyHints> in der Fußzeile j/↓ Next und ⌃S Save an, weil diese Tastenbelegungen hint setzen. ? öffnet eine Hilfeansicht mit allen vier Belegungen, gruppiert unter Navigation, und Ctrl+K öffnet eine Palette, die sie durchsuchen kann.

#Tastensyntax

Eine Tastenbelegung ist ein Handler oder ein Objekt mit label, group, hint, command, disabled und noRepeat. command: false hält eine beschriftete Tastenbelegung aus der Palette heraus. Unbeschriftete Tastenbelegungen funktionieren, erscheinen aber weder in der Hilfeansicht noch in der Palette.

#Routing

Jede Keymap registriert einen useInput-Handler, daher gelten die bestehenden Eingaberegeln. Ein fokussiertes <Input> verarbeitet Tasten zuerst, weil Editoren mit Priorität 10 und Keymaps mit Priorität 0 lauschen. Eine übereinstimmende Taste stoppt die Weiterleitung. Ein geöffnetes <Modal> deaktiviert Tastenbelegungen außerhalb davon, sofern die Keymap nicht global: true übergibt.

Sequenzen werden innerhalb dieses Handlers abgeglichen. Eine Taste, die eine Sequenz beginnt, bleibt ausstehend und stoppt die Weiterleitung, und die Sequenz wird zurückgesetzt, wenn die nächste Taste erst nach mehr als sequenceTimeout (standardmäßig 1000 ms) eintrifft:

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

#Eine Registry pro Root

Beschriftete Tastenbelegungen werden in einer Registry veröffentlicht, die zum Konsolen-Root gehört. <KeyHelp>, <KeyHints> und <CommandPalette> lesen daraus, und deine eigenen Komponenten können das über useKeymapBindings() ebenfalls. Solange ein Modal geöffnet ist, gibt die Registry nur die Tastenbelegungen innerhalb des Modals zurück, sodass die Hilfeansicht die aktuell nutzbaren Tasten auflistet.

Keymaps werden meist inline geschrieben, wodurch bei jedem Rendern ein neues Objekt entsteht. Um den Aufwand gering zu halten, veröffentlicht eine Keymap ihre Beschriftungen nur dann erneut, wenn sich deren sichtbare Form ändert:

// 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");

Handler werden beim Eintreffen einer Taste aus einer Ref gelesen, sodass eine neue Closure bei jedem Rendern nie veraltet ist.

#Die Hilfeansicht und die Palette

<KeyHelp> öffnet sich mit ? und listet alle aktiven beschrifteten Tastenbelegungen nach Gruppe auf. keys und title ändern den Auslöser und die Überschrift.

<CommandPalette> öffnet sich mit Ctrl+K oder Ctrl+P. Sie durchsucht deine commands und alle beschrifteten Tastenbelegungen per unscharfer Suche und hebt die übereinstimmenden Buchstaben hervor. Sie schließt sich, bevor sie einen Befehl ausführt, sodass ein Befehl ein eigenes Modal öffnen kann.

formatKeys bereitet eine Tastenbelegung für die Anzeige auf. formatKeys("ctrl+shift+p") gibt unter macOS ⌃⇧P und auf anderen Systemen ctrl+shift+P zurück, und <Kbd> stellt eine einzelne Taste mit derselben Formatierung dar.

useKeymap, <KeyHelp>, <KeyHints>, <StatusBar> und <CommandPalette> sind in Text.js 1.0 enthalten. Die Referenz findest du unter Tastatur.