GamepadHapticActuator.reset() — Methode · JavaScript-Referenz

Signatur

GamepadHapticActuator.prototype.reset()

Beschreibung

Die Methode reset() der Schnittstelle GamepadHapticActuator bricht einen Vibrationseffekt ab, der mit playEffect() gestartet wurde. Den Aktor erreicht man in der Regel über gamepad.vibrationActuator, also über ein Gamepad-Objekt aus navigator.getGamepads().

Typische Einsatzfälle sind: Das Spiel wird pausiert, der Tab verliert den Fokus, der Spieler öffnet ein Menü oder ein langer Rumble-Effekt soll bei einem Ereignis wie „Treffer vorbei“ sofort aufhören. Ohne reset() läuft ein Effekt bis zum Ende der angegebenen duration weiter.

Wenn beim Aufruf noch ein playEffect()-Promise offen ist, wird dieses mit "preempted" erfüllt. Das Promise von reset() selbst wird mit "complete" erfüllt, sobald die Hardware gestoppt ist.

Rückgabewert

Typ

Promise<string>

Beschreibung

Ein Promise, das mit "complete" erfüllt wird, sobald die Vibration gestoppt ist. Ist das Dokument nicht aktiv oder nicht sichtbar, wird es mit einer InvalidStateError-DOMException abgelehnt.

Beispiele

Laufende Vibration abbrechen

const [pad] = navigator.getGamepads().filter(Boolean);

if (pad?.vibrationActuator) {
  const effekt = pad.vibrationActuator.playEffect('dual-rumble', {
    duration: 2000,
    strongMagnitude: 1.0,
    weakMagnitude: 0.5
  });
  effekt.then((ergebnis) => console.log('playEffect:', ergebnis));

  // Nach 300 ms abbrechen
  setTimeout(async () => {
    const ergebnis = await pad.vibrationActuator.reset();
    console.log('reset:', ergebnis);
  }, 300);
}

playEffect: preempted reset: complete

Alle Gamepads beim Pausieren oder Tab-Wechsel stoppen

const stoppeAlleVibrationen = async () => {
  const pads = navigator.getGamepads().filter(Boolean);
  await Promise.allSettled(
    pads
      .filter((pad) => pad.vibrationActuator)
      .map((pad) => pad.vibrationActuator.reset())
  );
};

// Vor dem Verstecken stoppen – danach wäre reset() ungültig
document.addEventListener('visibilitychange', () => {
  if (document.hidden) stoppeAlleVibrationen();
});

document.querySelector('#pause-button')
  ?.addEventListener('click', stoppeAlleVibrationen);

Sicherer Aufruf mit Feature-Erkennung und Fehlerbehandlung

const vibrationStoppen = async (pad) => {
  const aktor = pad?.vibrationActuator;
  if (typeof aktor?.reset !== 'function') {
    console.warn('Haptik-Reset wird nicht unterstützt');
    return false;
  }
  try {
    return (await aktor.reset()) === 'complete';
  } catch (err) {
    console.error('reset() fehlgeschlagen:', err.name);
    return false;
  }
};

window.addEventListener('gamepadconnected', async (e) => {
  console.log('Gestoppt:', await vibrationStoppen(e.gamepad));
});

Gestoppt: true

// Wichtig · Fallstricke

Browser-Kompatibilität: In Chromium-Browsern (Chrome, Edge, Opera) und in Safari ab 16.4 verfügbar. Firefox hat vibrationActuator und reset() standardmäßig nicht, deshalb immer per Feature-Erkennung prüfen.
Sichtbarkeit: Ist das Dokument nicht aktiv oder versteckt, wird das Promise mit InvalidStateError abgelehnt. Browser stoppen Vibrationen beim Verstecken des Tabs meist ohnehin selbst.
Veraltete Snapshots: In Chrome sind Gamepad-Objekte Momentaufnahmen. Für den Zugriff auf den Aktor am besten jedes Mal navigator.getGamepads() neu aufrufen.
Ein offenes playEffect()-Promise wird mit "preempted" erfüllt, nicht abgelehnt. Das ist wichtig, wenn Code auf das Ende eines Effekts wartet.
Die ältere, nicht standardisierte pulse()-Methode (Firefox/WebVR) wird von reset() nicht zuverlässig beeinflusst.
Einige Browser verlangen einen sicheren Kontext (HTTPS), und das Gamepad muss nach einer Nutzereingabe für die Seite sichtbar geworden sein.

Siehe auch

GamepadHapticActuator GamepadHapticActuator.playEffect() Gamepad.vibrationActuator Navigator.getGamepads() new XPathEvaluator()