KeyboardEvent.repeat — Eigenschaft · JavaScript-Referenz

Signatur

KeyboardEvent.repeat

Beschreibung

Die schreibgeschützte Eigenschaft repeat der Schnittstelle KeyboardEvent zeigt an, ob ein Ereignis durch die automatische Tastenwiederholung des Betriebssystems ausgelöst wurde. Hält man eine Taste gedrückt, feuert der Browser zuerst ein normales keydown (mit repeat === false) und nach einer kurzen Verzögerung weitere keydown-Ereignisse mit repeat === true.

Typische Anwendungsfälle sind:

Tastenkürzel, die nur einmal pro Tastendruck ausgelöst werden sollen (z. B. Strg+S zum Speichern).
Spiele und interaktive Anwendungen, bei denen „gedrückt/losgelassen“ als Zustand erfasst wird und Wiederholungen nur stören.
Vermeidung teurer Aktionen wie Netzwerkanfragen oder Animationsstarts, die sonst dutzendfach pro Sekunde ausgelöst würden.

Die Eigenschaft ist in erster Linie bei keydown relevant. Bei keyup ist sie immer false, da das Loslassen nicht wiederholt wird. Das veraltete keypress-Ereignis wird ebenfalls wiederholt, sollte aber nicht mehr verwendet werden.

Beispiele

Wiederholungen erkennen und protokollieren

document.addEventListener('keydown', (event) => {
  console.log(`${event.key} – repeat: ${event.repeat}`);
});

// Taste „a“ kurz gedrückt halten

a – repeat: false a – repeat: true a – repeat: true a – repeat: true

Tastenkürzel nur einmal pro Tastendruck auslösen

const speichern = () => console.log('Dokument gespeichert');

document.addEventListener('keydown', (event) => {
  if ((event.ctrlKey || event.metaKey) && event.key === 's') {
    event.preventDefault();      // Browser-Dialog „Seite speichern“ unterdrücken
    if (event.repeat) return;    // gedrückt halten löst nicht mehrfach aus
    speichern();
  }
});

Dokument gespeichert

Tastenzustand für ein Spiel verwalten

const gedrueckt = new Set();

window.addEventListener('keydown', (event) => {
  if (event.repeat) return; // Nur den ersten Druck registrieren
  gedrueckt.add(event.code);
  console.log('Start:', event.code);
});

window.addEventListener('keyup', (event) => {
  gedrueckt.delete(event.code);
  console.log('Stopp:', event.code);
});

const spielSchleife = () => {
  if (gedrueckt.has('ArrowRight')) {
    // Spielfigur gleichmäßig pro Frame bewegen – unabhängig von der OS-Wiederholrate
  }
  requestAnimationFrame(spielSchleife);
};
requestAnimationFrame(spielSchleife);

Start: ArrowRight Stopp: ArrowRight

Synthetisches Ereignis mit repeat erzeugen

const evt = new KeyboardEvent('keydown', { key: 'Enter', repeat: true });
console.log(evt.repeat);

// Nachträgliches Setzen hat keine Wirkung (schreibgeschützt)
evt.repeat = false;
console.log(evt.repeat);

true true

// Wichtig · Fallstricke

Schreibgeschützt: Der Wert lässt sich nur über das Initialisierungsobjekt des Konstruktors new KeyboardEvent(type, { repeat: true }) festlegen; eine Zuweisung wird stillschweigend ignoriert (im Strict Mode kein Fehler, da es sich um einen Getter auf dem Prototyp handelt).
Wiederholrate ist systemabhängig: Verzögerung und Frequenz der Wiederholung bestimmt das Betriebssystem bzw. der Benutzer. Für gleichmäßige Bewegungen in Spielen nicht auf wiederholte keydown-Ereignisse verlassen, sondern den Zustand zwischen keydown und keyup auswerten und per requestAnimationFrame verarbeiten.
Linux/X11 und ältere Browser: Unter manchen Umgebungen wurden historisch bei Wiederholung zusätzlich keyup-Ereignisse erzeugt oder repeat nicht korrekt gesetzt. Moderne Browser verhalten sich einheitlich, bei sehr alten Versionen (z. B. Internet Explorer) wird repeat nicht unterstützt.
IME-Eingaben: Während einer Komposition (event.isComposing === true) kann das Verhalten abweichen; solche Ereignisse sollten bei Tastenkürzeln meist ignoriert werden.
Auf virtuellen Tastaturen mobiler Geräte gibt es häufig keine automatische Wiederholung, bzw. es werden gar keine verlässlichen keydown-Ereignisse geliefert.

Siehe auch

KeyboardEvent.keyIdentifier KeyboardEvent.code KeyboardEvent.key KeyboardEvent.altKey KeyboardEvent.ctrlKey