new GamepadEvent() — Methode · JavaScript-Referenz

Signatur

new GamepadEvent(type, options)

Beschreibung

Mit new GamepadEvent() legst du selbst ein Ereignisobjekt an, wie es der Browser sonst bei gamepadconnected und gamepaddisconnected auslöst. Über die Eigenschaft gamepad hat das Ereignis Zugriff auf das zugehörige Gamepad-Objekt, also auf Index, ID, Tasten und Achsen.

Normalerweise brauchst du den Konstruktor nicht, denn der Browser erzeugt diese Ereignisse selbst, sobald ein Controller angeschlossen oder getrennt wird. Praktisch ist er vor allem für Unit-Tests, für Simulationen (etwa eine Demo ohne echte Hardware) und für das Weiterleiten von Gamepad-Zuständen an eigene Komponenten per dispatchEvent().

Wichtig: Das Wörterbuch options braucht die Eigenschaft gamepad, und ihr Wert muss ein echtes Gamepad-Objekt sein. Solche Objekte bekommst du nur über navigator.getGamepads() oder aus einem vorhandenen Ereignis. Ein einfaches Objektliteral führt zu einem TypeError. Selbst ausgelöste Ereignisse haben isTrusted === false.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses, üblicherweise `"gamepadconnected"` oder `"gamepaddisconnected"`. Wird beachtet, ob Groß- oder Kleinbuchstaben verwendet werden.
$options Pflicht	GamepadEventInit		Wörterbuch mit Einstellungen. Zusätzlich zu den `EventInit`-Feldern `bubbles`, `cancelable` und `composed` (alle standardmäßig `false`) ist hier `gamepad` Pflicht: ein `Gamepad`-Objekt, das dem Ereignis zugeordnet wird.

Rückgabewert

Typ

GamepadEvent

Beschreibung

Ein neues GamepadEvent-Objekt. Seine schreibgeschützte Eigenschaft gamepad verweist auf das übergebene Gamepad.

Beispiele

GamepadEvent aus einem angeschlossenen Controller erzeugen

// Voraussetzung: Mindestens ein Controller ist verbunden, und auf der Seite wurde schon eine Taste gedrückt
const [pad] = navigator.getGamepads().filter(Boolean);

if (pad) {
  const event = new GamepadEvent('gamepadconnected', { gamepad: pad });
  console.log(event.type, event.gamepad.index, event.gamepad.id);
} else {
  console.log('Kein Gamepad gefunden');
}

gamepadconnected 0 Xbox Wireless Controller (STANDARD GAMEPAD Vendor: 045e Product: 02fd)

Ereignis erneut auslösen, um die eigene Logik zu testen

const handleConnect = (e) => {
  console.log(`Controller ${e.gamepad.index} bereit: ${e.gamepad.buttons.length} Tasten`);
};

window.addEventListener('gamepadconnected', handleConnect);

// Beim echten Ereignis den Controller merken und später erneut auslösen
window.addEventListener('gamepadconnected', (e) => {
  if (!e.isTrusted) return; // Endlosschleife vermeiden
  setTimeout(() => {
    const fake = new GamepadEvent('gamepadconnected', { gamepad: e.gamepad });
    window.dispatchEvent(fake);
    console.log('isTrusted:', fake.isTrusted);
  }, 1000);
}, { once: true });

Controller 0 bereit: 17 Tasten Controller 0 bereit: 17 Tasten isTrusted: false

Fehler bei ungültigem gamepad-Wert abfangen

try {
  // Ein Objektliteral ist kein echtes Gamepad
  new GamepadEvent('gamepadconnected', { gamepad: { index: 0, id: 'Fake' } });
} catch (err) {
  console.log(err.name);
}

TypeError

// Wichtig · Fallstricke

Echtes Gamepad nötig: options.gamepad muss ein Gamepad-Objekt sein, das vom Browser kommt. Ohne diesen Wert oder mit einem Objektliteral werfen Browser einen TypeError. Echte Mocks sind daher nur mit Test-Frameworks oder Polyfills möglich, zum Beispiel mit einer eigenen Event-Unterklasse.
Sichere Umgebung: Die Gamepad-API gibt es in aktuellen Browsern nur in sicheren Kontexten (HTTPS). Außerdem kann eine Berechtigungsrichtlinie (Permissions-Policy: gamepad) sie sperren.
Schutz vor Fingerprinting: navigator.getGamepads() liefert erst Controller, nachdem der Nutzer auf dem Gerät eine Taste gedrückt oder eine Achse bewegt hat. Vorher enthält das Array nur null-Einträge.
isTrusted: Ereignisse, die du selbst erzeugst, haben isTrusted === false. Sie schalten also keine Funktionen frei, die eine Nutzeraktion voraussetzen.
Momentaufnahme: In Chrome ist das Gamepad-Objekt nur eine Momentaufnahme. Aktuelle Tastenzustände erhältst du nur, wenn du navigator.getGamepads() in jedem Frame neu aufrufst, etwa in einer requestAnimationFrame-Schleife.

Siehe auch

Gamepad new CommandEvent() new PageSwapEvent() new DragEvent() new FetchEvent()