VRDisplayEvent — Schnittstelle · JavaScript-Referenz

Signatur

interface VRDisplayEvent extends Event

Beschreibung

Das Interface VRDisplayEvent gehört zur WebVR API. Es ist das Ereignisobjekt aller WebVR-Ereignisse, die auf dem window-Objekt ausgelöst werden. Dazu gehören vrdisplayconnect, vrdisplaydisconnect, vrdisplayactivate, vrdisplaydeactivate, vrdisplayblur, vrdisplayfocus und vrdisplaypresentchange. Das Interface erbt von Event.

Zu den geerbten Eigenschaften kommen zwei eigene, schreibgeschützte hinzu:

display: das VRDisplay, auf das sich das Ereignis bezieht.
reason: ein lesbarer Grund für das Ereignis, als Zeichenkette oder null. Mögliche Werte sind "mount" (Headset wurde aufgesetzt), "unmount" (Headset wurde abgenommen), "navigation" (Seite wurde aus einer laufenden VR-Präsentation heraus aufgerufen) und "requested" (das Gerät fordert eine Präsentation an).

Mit diesem Objekt reagiert man auf Hardware-Ereignisse: Man baut die Oberfläche auf, wenn ein Headset angeschlossen wird, startet die VR-Präsentation, wenn der Nutzer das Headset aufsetzt, oder pausiert das Rendering, wenn das Display den Fokus verliert.

Wichtig: WebVR ist veraltet und wurde durch die WebXR Device API ersetzt. Für neue Projekte sollten Sie XRSession und XRSessionEvent verwenden.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses, z. B. `"vrdisplayconnect"` (Parameter des Konstruktors `new VRDisplayEvent(type, init)`).
$init Pflicht	{ display: VRDisplay, reason?: string }		Initialisierungsobjekt. `display` ist das betroffene `VRDisplay`. `reason` ist optional und kann `"mount"`, `"unmount"`, `"navigation"` oder `"requested"` sein. Dazu kommen die üblichen `EventInit`-Felder wie `bubbles` und `cancelable`.

Rückgabewert

Typ

VRDisplayEvent

Beschreibung

Ein neues Ereignisobjekt mit den schreibgeschützten Eigenschaften display (VRDisplay) und reason (string | null).

Beispiele

Angeschlossenes Headset erkennen (addEventListener)

// Nur ausführen, wenn der Browser WebVR unterstützt
if ('getVRDisplays' in navigator) {
  window.addEventListener('vrdisplayconnect', (event) => {
    const { display, reason } = event;
    console.log(`Verbunden: ${display.displayName} (Grund: ${reason ?? 'keiner'})`);
  });

  window.addEventListener('vrdisplaydisconnect', (event) => {
    console.log(`Getrennt: ${event.display.displayName}`);
  });
} else {
  console.log('WebVR wird nicht unterstützt – bitte WebXR verwenden.');
}

Verbunden: Oculus Rift CV1 (Grund: keiner)

Präsentation beim Aufsetzen des Headsets starten

const canvas = document.querySelector('#vr-canvas');

const onActivate = async (event) => {
  // reason === 'mount': Nutzer hat das Headset aufgesetzt
  if (event.reason === 'mount' || event.reason === 'requested') {
    try {
      await event.display.requestPresent([{ source: canvas }]);
      console.log('VR-Präsentation gestartet');
    } catch (err) {
      console.error('Präsentation fehlgeschlagen:', err);
    }
  }
};

window.addEventListener('vrdisplayactivate', onActivate);

// Beim Abnehmen des Headsets die Präsentation beenden
window.addEventListener('vrdisplaydeactivate', (event) => {
  if (event.display.isPresenting) event.display.exitPresent();
});

VR-Präsentation gestartet

On-Property verwenden und Listener wieder entfernen

const onPresentChange = (event) => {
  const status = event.display.isPresenting ? 'aktiv' : 'beendet';
  console.log(`Präsentation ${status}`);
};

// Variante 1: on-Property
window.onvrdisplaypresentchange = onPresentChange;

// Variante 2: addEventListener und später wieder entfernen
window.addEventListener('vrdisplayblur', () => console.log('Fokus verloren'));
window.removeEventListener('vrdisplaypresentchange', onPresentChange);
window.onvrdisplaypresentchange = null;

Präsentation aktiv

Ereignis manuell erzeugen (z. B. für Tests)

navigator.getVRDisplays().then(([display]) => {
  if (!display) return;
  const evt = new VRDisplayEvent('vrdisplayconnect', { display, reason: 'requested' });
  console.log(evt.type, evt.reason, evt.display === display);
});

vrdisplayconnect requested true

// Wichtig · Fallstricke

Veraltet und nicht standardisiert: WebVR 1.1 war nie ein offizieller Standard. Nur ältere Versionen von Firefox (Windows/macOS), Chrome hinter einem Flag, Samsung Internet und Oculus Browser haben die API unterstützt. Aktuelle Browser haben sie entfernt. Nutzen Sie stattdessen die WebXR Device API mit navigator.xr, XRSession und dem Ereignis XRSessionEvent.

Prüfen Sie vor der Nutzung immer, ob die API vorhanden ist, z. B. mit 'getVRDisplays' in navigator oder typeof VRDisplayEvent !== 'undefined'. Sonst entsteht ein ReferenceError.
reason ist oft null. Verlassen Sie sich nicht darauf, dass die Eigenschaft gesetzt ist.
requestPresent() braucht in der Regel eine Nutzeraktion. Innerhalb von vrdisplayactivate ist ein Aufruf ausdrücklich erlaubt, in anderen Ereignissen kann er abgelehnt werden.
Für WebVR ist ein sicherer Kontext (HTTPS) nötig. Außerdem kann eine Permissions Policy (vr) die API in iframes sperren.
Als Übergangslösung für alten WebVR-Code gibt es das WebXR Polyfill. Es stellt WebXR auf Geräten bereit, die nur WebVR können.

Siehe auch

VRDisplay Navigator.getVRDisplays() VRDisplay.requestPresent() XRSessionEvent Event