Window: gamepadconnected — Ereignis · JavaScript-Referenz

Signatur

window.addEventListener("gamepadconnected", handler)

Beschreibung

Das Ereignis gamepadconnected gehört zur Gamepad API und wird am Window-Objekt ausgelöst, sobald ein Controller für die Seite verfügbar wird. Das Ereignisobjekt ist ein GamepadEvent. Seine Eigenschaft gamepad verweist auf das verbundene Gamepad-Objekt mit index, id, mapping, buttons und axes.

Aus Datenschutzgründen (Schutz vor Fingerprinting) geben Browser ein Gamepad erst frei, wenn der Nutzer auf der Seite damit interagiert, also eine Taste drückt oder einen Stick bewegt. Ein bereits angeschlossener Controller löst das Ereignis daher oft erst nach dieser ersten Eingabe aus und nicht schon beim Laden der Seite.

Registrieren kannst du den Handler mit window.addEventListener("gamepadconnected", handler) oder über die Eigenschaft window.ongamepadconnected. Typischerweise startest du im Handler eine Abfrageschleife mit requestAnimationFrame(), die den Zustand regelmäßig über navigator.getGamepads() ausliest. Die Gamepad API meldet Tastendrücke nämlich nicht als eigene Ereignisse.

Das Gegenstück ist gamepaddisconnected. Es wird ausgelöst, wenn der Controller getrennt wird, und eignet sich zum Aufräumen, zum Beispiel um die Abfrageschleife zu beenden oder das Spiel zu pausieren.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"gamepadconnected"`.
$handler Pflicht	(event: GamepadEvent) => void		Callback, der ein `GamepadEvent` erhält. Über `event.gamepad` greifst du auf das verbundene `Gamepad` zu.
$options	boolean \| AddEventListenerOptions	false	Optionale Listener-Optionen wie `once`, `signal` oder `capture`.

Rückgabewert

Typ

void

Beschreibung

addEventListener() gibt nichts zurück. Der Handler erhält ein GamepadEvent mit der Eigenschaft gamepad (Typ Gamepad).

Beispiele

Verbundenes Gamepad protokollieren

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 beim Trennen beenden

let rafId = null;

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

window.addEventListener("gamepadconnected", () => {
  if (rafId === null) rafId = requestAnimationFrame(poll);
});

window.addEventListener("gamepaddisconnected", (event) => {
  console.log(`Gamepad ${event.gamepad.index} getrennt`);
  const stillConnected = navigator.getGamepads().some(Boolean);
  if (!stillConnected) {
    cancelAnimationFrame(rafId);
    rafId = null;
  }
});

Pad 0: A gedrückt Linker Stick: 0.87, -0.12

on-Property nutzen und Listener wieder entfernen

// Variante 1: Event-Handler-Eigenschaft
window.ongamepadconnected = (e) => {
  document.title = `🎮 ${e.gamepad.id}`;
};

// Variante 2: Listener, der sich per AbortController entfernen lässt
const controller = new AbortController();
const onConnect = (e) => console.log("Verbunden:", e.gamepad.index);
window.addEventListener("gamepadconnected", onConnect, { signal: controller.signal });

// Später, z. B. beim Verlassen des Spielmenüs:
controller.abort(); // entspricht removeEventListener("gamepadconnected", onConnect)
window.ongamepadconnected = null;

Verbunden: 0

Bereits verbundene Gamepads beim Laden prüfen

const initPad = (pad) => console.log(`Bereit: ${pad.id}`);

// Falls die Nutzerin schon vor dem Registrieren des Listeners interagiert hat
navigator.getGamepads().filter(Boolean).forEach(initPad);

window.addEventListener("gamepadconnected", (e) => initPad(e.gamepad));

Bereit: Wireless Controller (STANDARD GAMEPAD Vendor: 054c Product: 09cc)

// Wichtig · Fallstricke

Erste Eingabe nötig: Browser melden ein Gamepad oft erst nach einem Tastendruck oder einer Stickbewegung. Deshalb auf der Seite einen Hinweis wie „Drücke eine Taste auf dem Controller“ anzeigen.
Momentaufnahmen in Chrome: In Chromium-Browsern ist event.gamepad bzw. das Ergebnis von navigator.getGamepads() eine Momentaufnahme. Hol dir in jedem Frame ein frisches Objekt über navigator.getGamepads()[index], statt eine alte Referenz zu speichern.
Sichere Kontexte und Berechtigungen: In aktuellen Browsern ist die Gamepad API nur in sicheren Kontexten (HTTPS) verfügbar. In iframes kann sie über die Permissions Policy gamepad gesperrt sein.
Nur Zustand, keine Tastenereignisse: Einzelne Tastendrücke erzeugen keine Ereignisse. Du musst den Zustand abfragen, am besten mit requestAnimationFrame().
Uneinheitliche Belegung: Die Anordnung von Tasten und Achsen ist nur bei mapping === \"standard\" einheitlich. Andere Controller können abweichende Indizes haben.
Das Ereignis lässt sich nicht abbrechen und steigt nicht auf (kein Bubbling). Nur window empfängt es.

Siehe auch

Gamepad IDBTransaction: error Window: gamepaddisconnected Window: vrdisplayconnect Window: vrdisplaydisconnect