Window: vrdisplayactivate — Ereignis · JavaScript-Referenz

Signatur

window.addEventListener("vrdisplayactivate", handler)

Beschreibung

Das Ereignis vrdisplayactivate gehört zur veralteten WebVR API und wird am Window-Objekt ausgelöst, sobald ein angeschlossenes VR-Display (ein VRDisplay) präsentiert werden kann. Typische Auslöser sind: Das Head-Mounted Display (HMD) wird bewegt und wacht dadurch aus dem Standby auf, oder ein Näherungssensor erkennt, dass der Nutzer das Headset aufgesetzt hat.

Das Ereignis ist ein VRDisplayEvent. Die Eigenschaft display verweist auf das betroffene VRDisplay, reason gibt den Grund an (z. B. "mounted", "navigation", "requested"). Registrieren lässt sich der Handler per window.addEventListener("vrdisplayactivate", handler) oder über die Eigenschaft window.onvrdisplayactivate.

Der Hauptnutzen: Innerhalb des Handlers gilt die Aktivierung als Nutzergeste. Deshalb darf dort VRDisplay.requestPresent() aufgerufen werden, um automatisch in den VR-Modus zu wechseln, sobald der Nutzer das Headset aufsetzt. Das Gegenstück ist vrdisplaydeactivate, das beim Absetzen bzw. Wechsel in den Standby feuert.

Für neue Projekte sollte stattdessen die WebXR Device API (navigator.xr, XRSession) verwendet werden.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"vrdisplayactivate"`.
$handler Pflicht	(event: VRDisplayEvent) => void		Callback, der ein `VRDisplayEvent` mit den Eigenschaften `display` (`VRDisplay`) und `reason` (`string`) erhält.
$options	boolean\|AddEventListenerOptions	false	Optionale Listener-Optionen wie `once`, `passive` oder `signal`.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Der Handler erhält ein VRDisplayEvent.

Beispiele

Automatisch präsentieren, wenn das Headset aufgesetzt wird

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

const onActivate = async (event) => {
  const { display, reason } = event;
  console.log(`Display "${display.displayName}" aktiviert (Grund: ${reason})`);
  try {
    // Innerhalb des Handlers als Nutzergeste erlaubt
    await display.requestPresent([{ source: canvas }]);
    console.log('VR-Präsentation gestartet');
  } catch (err) {
    console.error('Präsentation fehlgeschlagen:', err);
  }
};

if ('getVRDisplays' in navigator) {
  window.addEventListener('vrdisplayactivate', onActivate);
} else {
  console.warn('WebVR wird nicht unterstützt – bitte WebXR verwenden.');
}

Display "Oculus Rift CV1" aktiviert (Grund: mounted) VR-Präsentation gestartet

Über die on-Property und Gegenstück vrdisplaydeactivate

window.onvrdisplayactivate = (event) => {
  console.log('Headset bereit:', event.display.displayName);
};

window.onvrdisplaydeactivate = async (event) => {
  console.log('Headset abgesetzt – beende Präsentation');
  if (event.display.isPresenting) {
    await event.display.exitPresent();
  }
};

Headset bereit: HTC Vive Headset abgesetzt – beende Präsentation

Listener wieder entfernen

const handleActivate = (event) => {
  console.log('Aktiviert:', event.reason);
};

window.addEventListener('vrdisplayactivate', handleActivate);

// Später, z. B. beim Verlassen der VR-Ansicht
window.removeEventListener('vrdisplayactivate', handleActivate);
// bzw. bei on-Property:
window.onvrdisplayactivate = null;

Feature-Erkennung mit WebXR-Fallback

const initVR = async () => {
  if (navigator.xr && await navigator.xr.isSessionSupported('immersive-vr')) {
    console.log('WebXR verfügbar – moderne API nutzen');
    return;
  }
  if ('onvrdisplayactivate' in window) {
    window.addEventListener('vrdisplayactivate', (e) => {
      console.log('Legacy-WebVR aktiviert:', e.display.displayName);
    }, { once: true });
    return;
  }
  console.log('Kein VR verfügbar');
};

initVR();

WebXR verfügbar – moderne API nutzen

// Wichtig · Fallstricke

Veraltet und nicht standardisiert: WebVR wurde nie Standard und ist durch die WebXR Device API abgelöst. In aktuellen Chrome-, Edge- und Firefox-Versionen ist WebVR entfernt oder standardmäßig deaktiviert; Safari hat es nie unterstützt.
Ob und wann das Ereignis feuert, hängt stark von Hardware und Treiber ab (z. B. Näherungssensor im HMD). Nicht jedes Gerät meldet reason: "mounted".
requestPresent() funktioniert nur innerhalb des Handlers (bzw. einer anderen Nutzergeste) zuverlässig – ein verzögerter Aufruf nach setTimeout kann abgelehnt werden.
Feuert nur in einem sicheren Kontext (HTTPS) und ggf. nicht in iframes ohne entsprechende Berechtigung (allow="vr").
Immer per Feature-Erkennung ('onvrdisplayactivate' in window oder navigator.getVRDisplays) absichern.

Siehe auch

Window: vrdisplaydeactivate Window: vrdisplayconnect Window: vrdisplaydisconnect Window: vrdisplaypresentchange VRDisplayEvent VRDisplay.requestPresent() XRSystem EventTarget.addEventListener()