GamepadEvent — Schnittstelle · JavaScript-Referenz

Signatur

interface GamepadEvent extends Event

Beschreibung

Das Interface GamepadEvent gehört zur Gamepad API. Der Browser erzeugt es, wenn ein Gamepad verbunden (gamepadconnected) oder getrennt (gamepaddisconnected) wird. Beide Ereignisse werden auf window ausgelöst. Über die schreibgeschützte Eigenschaft gamepad kommt man an das zugehörige Gamepad-Objekt mit id, index, buttons, axes und mapping.

Typischerweise nutzt man das Ereignis, um in einer Spiele- oder Steuerungsanwendung eine Abfrageschleife (requestAnimationFrame) zu starten, sobald ein Controller da ist, und sie zu stoppen oder eine Pause-Anzeige einzublenden, wenn er getrennt wird. Die Tasten- und Achsenwerte selbst werden nicht über Ereignisse gemeldet. Man muss sie regelmäßig über navigator.getGamepads() abfragen.

Aus Datenschutzgründen melden die meisten Browser ein Gamepad erst, wenn der Nutzer auf der Seite eine Taste gedrückt oder einen Stick bewegt hat. Ein schon angeschlossener Controller löst gamepadconnected also nicht sofort beim Laden der Seite aus.

Mit dem Konstruktor new GamepadEvent(type, options) kann man das Ereignis auch selbst erzeugen, etwa für Tests. Dafür braucht man aber ein echtes Gamepad-Objekt.

Parameter

Name	Typ	Beschreibung
$type Pflicht	string	Konstruktor-Parameter: Name des Ereignisses, normalerweise `"gamepadconnected"` oder `"gamepaddisconnected"`.
$options Pflicht	object	Konstruktor-Parameter: Objekt mit den Feldern aus `EventInit` (`bubbles`, `cancelable`, `composed`) und dem Pflichtfeld `gamepad` (ein `Gamepad`-Objekt).
$gamepad	Gamepad	Instanz-Eigenschaft (nur lesbar): das Gamepad, das verbunden oder getrennt wurde.

Rückgabewert

Typ

GamepadEvent

Beschreibung

Der Konstruktor gibt ein neues GamepadEvent zurück. In Ereignis-Handlern bekommt man das Objekt als Argument übergeben.

Beispiele

Verbundenes Gamepad erkennen (addEventListener)

window.addEventListener('gamepadconnected', (event) => {
  const { index, id, buttons, axes, mapping } = event.gamepad;
  console.log(`Gamepad #${index} verbunden: ${id}`);
  console.log(`${buttons.length} Tasten, ${axes.length} Achsen, Mapping: ${mapping || 'unbekannt'}`);
});

Gamepad #0 verbunden: Xbox 360 Controller (XInput STANDARD GAMEPAD) 17 Tasten, 4 Achsen, Mapping: standard

Abfrageschleife starten und stoppen

const activePads = new Set();
let rafId = null;

const poll = () => {
  for (const pad of navigator.getGamepads()) {
    if (!pad || !activePads.has(pad.index)) continue;
    if (pad.buttons[0]?.pressed) console.log(`Pad ${pad.index}: Taste A gedrückt`);
    const [x, y] = pad.axes;
    if (Math.abs(x) > 0.2 || Math.abs(y) > 0.2) {
      console.log(`Pad ${pad.index}: Stick ${x.toFixed(2)} / ${y.toFixed(2)}`);
    }
  }
  rafId = requestAnimationFrame(poll);
};

window.addEventListener('gamepadconnected', (e) => {
  activePads.add(e.gamepad.index);
  if (rafId === null) rafId = requestAnimationFrame(poll);
});

window.addEventListener('gamepaddisconnected', (e) => {
  activePads.delete(e.gamepad.index);
  console.log(`Gamepad ${e.gamepad.id} getrennt – Spiel pausiert`);
  if (activePads.size === 0) {
    cancelAnimationFrame(rafId);
    rafId = null;
  }
});

Pad 0: Taste A gedrückt Pad 0: Stick 0.85 / -0.10 Gamepad Xbox 360 Controller (XInput STANDARD GAMEPAD) getrennt – Spiel pausiert

On-Property nutzen und Listener wieder entfernen

// Variante über das on-Property
window.ongamepadconnected = (e) => {
  console.log('Verbunden:', e instanceof GamepadEvent, e.gamepad.id);
};

// Variante mit entfernbarem Listener
const onDisconnect = (e) => console.log('Getrennt:', e.gamepad.index);
window.addEventListener('gamepaddisconnected', onDisconnect);

// Beim Verlassen der Spielansicht aufräumen
const cleanup = () => {
  window.ongamepadconnected = null;
  window.removeEventListener('gamepaddisconnected', onDisconnect);
};

Verbunden: true Xbox 360 Controller (XInput STANDARD GAMEPAD)

// Wichtig · Fallstricke

Kein Ereignis für Tasten: GamepadEvent gibt es nur für Verbinden und Trennen. Tasten und Achsen muss man über navigator.getGamepads() abfragen. In Chrome ist event.gamepad außerdem nur eine Momentaufnahme, also immer frische Objekte aus getGamepads() lesen.
Nutzeraktion nötig: Browser melden Gamepads erst nach einer Eingabe am Controller. Ist beim Laden schon einer angeschlossen, zusätzlich navigator.getGamepads() prüfen.
Sicherer Kontext: Die Gamepad API funktioniert in aktuellen Browsern nur über HTTPS (bzw. localhost). In iframes kann sie durch die Permissions Policy gamepad gesperrt sein.
Fingerprinting: gamepad.id enthält Angaben zu Hersteller und Gerät. Diese Angaben nicht unnötig speichern oder weitergeben.
Kompatibilität: Wird von Chrome, Edge, Firefox und Safari unterstützt. Die Belegung der Tasten ist nur bei mapping === "standard" einheitlich.

Siehe auch

Gamepad Navigator.getGamepads() GamepadButton Event CommandEvent