GamepadHapticActuator.effects — Eigenschaft · JavaScript-Referenz

Signatur

GamepadHapticActuator.effects

Beschreibung

Die schreibgeschützte Eigenschaft effects eines GamepadHapticActuator-Objekts enthält ein eingefrorenes Array von Zeichenketten. Jede davon ist ein Wert der Aufzählung GamepadHapticEffectType und steht für einen Effekt, den der Aktor tatsächlich abspielen kann. Laut Spezifikation gibt es derzeit diese Werte:

"dual-rumble" – klassische Vibration mit zwei Motoren (stark/schwach), wie bei Xbox- oder PlayStation-Controllern.
"trigger-rumble" – zusätzliche Vibration in den Schultertasten (Trigger), z. B. beim Xbox-One-Controller.

Den Aktor bekommst du normalerweise über gamepad.vibrationActuator eines von navigator.getGamepads() gelieferten Gamepad-Objekts. Bevor du playEffect() aufrufst, kannst du mit effects.includes(...) prüfen, ob der gewünschte Effekt unterstützt wird. So kannst du zum Beispiel auf "dual-rumble" zurückfallen, wenn der Controller keine Trigger-Vibration kann.

Die Eigenschaft hat keine Parameter. Sie beschreibt nur, was das Gerät kann. Ob ein Effekt wirklich spürbar ist, hängt außerdem von Treiber, Betriebssystem und Verbindungsart ab (USB oder Bluetooth).

Rückgabewert

Typ

ReadonlyArray<"dual-rumble" | "trigger-rumble">

Beschreibung

Ein eingefrorenes Array (FrozenArray) mit den unterstützten Effekttypen als Zeichenketten. Es kann leer sein, wenn der Aktor keinen der bekannten Effekte beherrscht.

Beispiele

Unterstützte Effekte beim Verbinden auslesen

window.addEventListener('gamepadconnected', (event) => {
  const { gamepad } = event;
  const actuator = gamepad.vibrationActuator;

  if (!actuator) {
    console.log(`${gamepad.id}: keine Vibration verfügbar`);
    return;
  }

  // effects kann in älteren Implementierungen fehlen
  const effects = actuator.effects ?? [];
  console.log(`${gamepad.id}: unterstützte Effekte:`, effects);
});

Xbox Wireless Controller (STANDARD GAMEPAD): unterstützte Effekte: ["dual-rumble", "trigger-rumble"]

Trigger-Vibration mit Rückfall auf dual-rumble

const rumble = async (gamepad) => {
  const actuator = gamepad?.vibrationActuator;
  if (!actuator) return 'nicht unterstützt';

  const effects = actuator.effects ?? [];

  if (effects.includes('trigger-rumble')) {
    return actuator.playEffect('trigger-rumble', {
      duration: 300,
      leftTrigger: 0.2,
      rightTrigger: 1.0
    });
  }

  if (effects.includes('dual-rumble')) {
    return actuator.playEffect('dual-rumble', {
      duration: 300,
      strongMagnitude: 0.8,
      weakMagnitude: 0.4
    });
  }

  return 'kein passender Effekt';
};

const [pad] = navigator.getGamepads().filter(Boolean);
console.log(await rumble(pad));

complete

Einstellungsmenü nur bei vorhandener Vibration zeigen

const hasHaptics = (gamepad) =>
  (gamepad?.vibrationActuator?.effects ?? []).length > 0;

const updateSettingsUi = () => {
  const pads = navigator.getGamepads().filter(Boolean);
  const anyHaptics = pads.some(hasHaptics);
  document.querySelector('#vibration-setting').hidden = !anyHaptics;
};

window.addEventListener('gamepadconnected', updateSettingsUi);
window.addEventListener('gamepaddisconnected', updateSettingsUi);

// Wichtig · Fallstricke

Experimentell: Die Unterstützung unterscheidet sich stark zwischen den Browsern. Chromium-Browser und Safari haben vibrationActuator mit playEffect(). Firefox kennt nur die ältere, nicht standardisierte Eigenschaft gamepad.hapticActuators mit pulse(). Die Eigenschaft effects selbst fehlt in manchen Versionen. Prüfe sie daher immer defensiv, z. B. mit actuator.effects ?? [].
Das Array ist eingefroren. push() und ähnliche Methoden werfen einen TypeError oder werden stillschweigend ignoriert.
Steht "trigger-rumble" in der Liste, heißt das nicht zwingend, dass die Vibration spürbar ist. Unter Windows funktioniert Trigger-Vibration zum Beispiel oft nur bei bestimmten Controllern und Verbindungsarten.
Die Gamepad-API ist nur in sicheren Kontexten (HTTPS) verfügbar. Außerdem kann sie per Permissions-Policy: gamepad gesperrt sein. Gamepads erscheinen erst, wenn der Nutzer eine Taste gedrückt hat.
Die veraltete Eigenschaft GamepadHapticActuator.type (Wert "vibration") ist durch effects ersetzt worden.

Siehe auch

GamepadHapticActuator GamepadHapticActuator.playEffect() GamepadHapticActuator.reset() Gamepad.vibrationActuator Navigator.getGamepads() GamepadHapticActuator.type