Window: vrdisplaydisconnect — Ereignis · JavaScript-Referenz

Signatur

window.addEventListener("vrdisplaydisconnect", handler)

Beschreibung

Das Ereignis vrdisplaydisconnect gehört zur inzwischen veralteten WebVR API. Der Browser löst es am window-Objekt aus, sobald ein kompatibles VR-Headset (ein VRDisplay) vom Rechner getrennt wird, etwa weil jemand das Kabel abzieht oder das Gerät ausschaltet.

Das Ereignisobjekt ist ein VRDisplayEvent. Über dessen Eigenschaft display erfährst du, welches Gerät getrennt wurde. Die Eigenschaft reason kann zusätzlich einen Grund liefern, ist aber meist leer. Du kannst den Handler per addEventListener("vrdisplaydisconnect", …) oder über die Eigenschaft window.onvrdisplaydisconnect registrieren.

Typischerweise nutzt man das Ereignis, um eine laufende VR-Darstellung sauber zu beenden, die Render-Schleife anzuhalten (VRDisplay.cancelAnimationFrame()), die Oberfläche auf eine normale 2D-Ansicht zurückzustellen und einen Hinweis anzuzeigen. Das Gegenstück ist vrdisplayconnect.

Für neue Projekte solltest du stattdessen die WebXR Device API verwenden (navigator.xr, XRSession mit dem Ereignis end sowie devicechange an navigator.xr).

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname, hier immer `"vrdisplaydisconnect"`.
$handler Pflicht	(event: VRDisplayEvent) => void		Callback, der ein `VRDisplayEvent` erhält. Wichtig sind die Eigenschaften `event.display` (das getrennte `VRDisplay`) und `event.reason` (optionaler Grund, meist `undefined`).
$options	boolean \| AddEventListenerOptions	false	Die üblichen Optionen von `addEventListener`, z. B. `{ once: true }` oder `{ signal }`.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Der Handler bekommt ein VRDisplayEvent.

Beispiele

Trennung per addEventListener erkennen

window.addEventListener('vrdisplaydisconnect', (event) => {
  const { display } = event;
  console.log(`VR-Display getrennt: ${display.displayName} (ID ${display.displayId})`);
});

VR-Display getrennt: Oculus Rift CV1 (ID 1)

Über die on-Property: VR-Modus sauber beenden

let vrDisplay = null;
let frameHandle = 0;

window.onvrdisplaydisconnect = (event) => {
  if (event.display !== vrDisplay) return;

  // Render-Schleife stoppen und zur 2D-Ansicht zurückkehren
  vrDisplay.cancelAnimationFrame(frameHandle);
  vrDisplay = null;
  document.body.classList.remove('vr-aktiv');
  document.querySelector('#hinweis').textContent =
    'Das VR-Headset wurde getrennt. Die Ansicht läuft jetzt im Browserfenster.';
};

Feature-Erkennung mit Umstieg auf WebXR

const controller = new AbortController();

if ('onvrdisplaydisconnect' in window) {
  // Veraltete WebVR API
  window.addEventListener('vrdisplaydisconnect', (e) => {
    console.log('WebVR: Gerät getrennt', e.display?.displayName);
  }, { signal: controller.signal });
} else if (navigator.xr) {
  // Moderner Weg: WebXR
  navigator.xr.addEventListener('devicechange', async () => {
    const verfuegbar = await navigator.xr.isSessionSupported('immersive-vr');
    console.log('WebXR: immersive-vr verfügbar?', verfuegbar);
  }, { signal: controller.signal });
} else {
  console.log('Keine VR-Unterstützung in diesem Browser.');
}

// Später alle Listener auf einmal entfernen
// controller.abort();

Keine VR-Unterstützung in diesem Browser.

Listener wieder entfernen

const beiTrennung = (event) => {
  console.log('Getrennt:', event.display.displayName);
};

window.addEventListener('vrdisplaydisconnect', beiTrennung);

// z. B. beim Verlassen der VR-Szene
window.removeEventListener('vrdisplaydisconnect', beiTrennung);
// bzw. bei der on-Property:
window.onvrdisplaydisconnect = null;

// Wichtig · Fallstricke

Veraltet: WebVR wurde nie standardisiert und ist durch die WebXR Device API ersetzt. Chrome hatte WebVR nur hinter einem Flag bzw. in Origin Trials, Firefox hat die Unterstützung entfernt, Safari hat sie nie angeboten. In aktuellen Browsern wird das Ereignis praktisch nie ausgelöst.
Prüfe die Unterstützung immer vorher, z. B. mit 'onvrdisplaydisconnect' in window oder 'getVRDisplays' in navigator, und plane einen Umstieg auf WebXR ein.
Das Ereignis wird nur für Geräte ausgelöst, die die Seite vorher über navigator.getVRDisplays() kennengelernt hat. Vergleiche event.display mit deinem aktiven Display, falls mehrere Geräte angeschlossen sind.
Stoppe nach der Trennung die Render-Schleife mit VRDisplay.cancelAnimationFrame() und gib Ressourcen frei. Sonst laufen Callbacks weiter, ohne dass etwas angezeigt wird.
WebVR setzte in manchen Browsern einen sicheren Kontext (HTTPS) voraus. WebXR verlangt ihn immer.

Siehe auch

Window: vrdisplayconnect Window: vrdisplayactivate Window: vrdisplaydeactivate VRDisplayEvent VRDisplay Navigator.getVRDisplays() XRSystem: devicechange XRSession