KeyboardLayoutMap.size — Eigenschaft · JavaScript-Referenz

Signatur

KeyboardLayoutMap.size

Beschreibung

Eine KeyboardLayoutMap bekommt man über navigator.keyboard.getLayoutMap(). Sie ordnet physische Tastencodes wie "KeyQ" oder "Semicolon" dem Zeichen zu, das die Taste im aktuell eingestellten Tastaturlayout erzeugt, z. B. "q" auf QWERTZ oder "a" auf AZERTY. Die Eigenschaft size gibt die Anzahl dieser Zuordnungen als Ganzzahl zurück.

Die Map ist eine schreibgeschützte, Map-ähnliche Struktur (maplike). Deshalb verhält sich size genauso wie Map.prototype.size: Die Eigenschaft ist ein Getter und keine Methode, und sie lässt sich nicht überschreiben. Einträge hinzufügen oder löschen kann man auch nicht, weil die Map keine set()- und keine delete()-Methode hat.

size ist in der Praxis nützlich, um vor dem Weiterverarbeiten zu prüfen, ob überhaupt Layout-Daten da sind. Außerdem hilft die Eigenschaft beim Debuggen und beim Anzeigen von Statistiken, etwa wenn man in den Einstellungen eines Spiels oder Editors Tastenbelegungen darstellt.

Rückgabewert

Typ

number

Beschreibung

Nicht-negative Ganzzahl mit der Anzahl der Einträge in der KeyboardLayoutMap. Die genaue Zahl hängt von Browser, Betriebssystem und Layout ab (typischerweise um die 48 druckbare Tasten).

Beispiele

Anzahl der Layout-Einträge ausgeben

const zeigeLayoutGroesse = async () => {
  if (!('keyboard' in navigator) || !navigator.keyboard.getLayoutMap) {
    console.warn('Keyboard Map API wird nicht unterstützt.');
    return;
  }
  const layoutMap = await navigator.keyboard.getLayoutMap();
  console.log(`Das Layout enthält ${layoutMap.size} Tasten-Zuordnungen.`);
};

zeigeLayoutGroesse();

Das Layout enthält 48 Tasten-Zuordnungen.

Leere Map abfangen, bevor Tastenhinweise angezeigt werden

const tastenHinweis = async (codes) => {
  const layoutMap = await navigator.keyboard.getLayoutMap();
  if (layoutMap.size === 0) {
    // Rückfall auf die Tastencodes selbst
    return codes.map((code) => code.replace(/^Key/, ''));
  }
  return codes.map((code) => layoutMap.get(code) ?? code);
};

tastenHinweis(['KeyW', 'KeyA', 'KeyS', 'KeyD']).then((tasten) =>
  console.log(`Bewegung: ${tasten.join(' / ').toUpperCase()}`)
);

Bewegung: W / A / S / D (auf AZERTY: Z / Q / S / D)

size mit dem Durchlaufen der Einträge vergleichen

const layoutMap = await navigator.keyboard.getLayoutMap();

const eintraege = [...layoutMap.entries()];
console.log(eintraege.length === layoutMap.size); // true

// size ist schreibgeschützt
layoutMap.size = 0;
console.log(layoutMap.size > 0); // true, Zuweisung wird ignoriert

true true

// Wichtig · Fallstricke

Browser-Unterstützung: Die Keyboard Map API ist experimentell und steht nur in Chromium-Browsern (Chrome, Edge, Opera) zur Verfügung. Firefox und Safari unterstützen sie nicht. Vor der Nutzung sollte man daher per Feature-Erkennung prüfen, ob navigator.keyboard?.getLayoutMap existiert.
Sicherer Kontext: Die API funktioniert nur über HTTPS bzw. auf localhost. In iframes kann eine Berechtigungsrichtlinie (keyboard-map) den Zugriff sperren. Dann wird das Promise von getLayoutMap() abgelehnt (SecurityError).
Getter, keine Methode: Richtig ist layoutMap.size. Der Aufruf layoutMap.size() wirft einen TypeError. Eine Zuweisung an size wird ignoriert, im Strict Mode führt sie zu einem TypeError.
Momentaufnahme: Die Map gibt das Layout zum Zeitpunkt des Aufrufs wieder. Wechselt der Nutzer das Layout, ändern sich size und der Inhalt nicht automatisch. Um aktuelle Werte zu bekommen, muss man getLayoutMap() erneut aufrufen, etwa beim Ereignis layoutchange, falls der Browser es unterstützt, oder bei Fokuswechseln.
Die Anzahl der Einträge ist nicht genormt. Man sollte deshalb keinen festen Wert erwarten.

Siehe auch

KeyboardEvent.location MediaKeyStatusMap.size KeyboardEvent.code Metadata.size KeyboardEvent.altKey