XRSessionEvent.session — Eigenschaft · JavaScript-Referenz

Signatur

get XRSessionEvent.session

Beschreibung

Die Eigenschaft session eines XRSessionEvent verweist auf das XRSession-Objekt, dessen Zustand sich geändert hat. Solche Ereignisse löst die WebXR Device API vor allem in zwei Situationen aus: beim Beenden einer Sitzung (end) und bei einer Änderung der Sichtbarkeit (visibilitychange), etwa wenn der Nutzer ein System-Menü im Headset öffnet.

Nützlich ist die Eigenschaft vor allem dann, wenn ein einziger Handler für mehrere Sitzungen zuständig ist – zum Beispiel wenn eine Anwendung nacheinander eine immersive-vr- und eine inline-Sitzung verwaltet. Über event.session findet man heraus, welche Sitzung betroffen ist, ohne auf äußere Variablen oder event.target angewiesen zu sein.

Typische Anwendungsfälle sind das Aufräumen nach Sitzungsende (Event-Listener entfernen, WebGL-Ressourcen freigeben, UI zurücksetzen) sowie das Pausieren oder Fortsetzen von Spiellogik abhängig von event.session.visibilityState.

Rückgabewert

Typ

XRSession

Beschreibung

Das XRSession-Objekt, auf das sich das Ereignis bezieht. Der Wert wird beim Erzeugen des Ereignisses über das Init-Dictionary ({ session }) festgelegt und kann danach nicht verändert werden.

Beispiele

Aufräumen beim Beenden einer immersiven Sitzung

const startVR = async () => {
  if (!navigator.xr || !(await navigator.xr.isSessionSupported('immersive-vr'))) {
    console.log('immersive-vr wird nicht unterstützt');
    return;
  }
  const session = await navigator.xr.requestSession('immersive-vr');

  session.addEventListener('end', (event) => {
    // event.session ist dieselbe Sitzung, die beendet wurde
    console.log('Sitzung beendet:', event.session === session);
    console.log('Modus war:', event.session.environmentBlendMode ?? 'unbekannt');
    document.querySelector('#enter-vr').disabled = false;
  });
};

document.querySelector('#enter-vr').addEventListener('click', startVR);

Sitzung beendet: true Modus war: opaque

Ein gemeinsamer Handler für mehrere Sitzungen

const activeSessions = new Set();

const onVisibilityChange = (event) => {
  const { session } = event;
  const paused = session.visibilityState !== 'visible';
  console.log(`Sitzung ${[...activeSessions].indexOf(session)}: ${session.visibilityState}`);
  if (paused) {
    // z. B. Physik oder Audio anhalten
  }
};

const onEnd = (event) => {
  event.session.removeEventListener('visibilitychange', onVisibilityChange);
  activeSessions.delete(event.session);
  console.log('Verbleibende Sitzungen:', activeSessions.size);
};

const track = (session) => {
  activeSessions.add(session);
  session.addEventListener('visibilitychange', onVisibilityChange);
  session.addEventListener('end', onEnd, { once: true });
};

navigator.xr?.requestSession('inline').then(track);

Sitzung 0: visible-blurred Verbleibende Sitzungen: 0

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

const simulateEnd = async () => {
  const session = await navigator.xr.requestSession('inline');
  const event = new XRSessionEvent('end', { session });

  console.log(event.type);                 // 'end'
  console.log(event.session === session);  // true

  // Schreibgeschützt: Zuweisung wird ignoriert (im strict mode TypeError)
  try {
    event.session = null;
  } catch (err) {
    console.log(err.name);
  }
  console.log(event.session === session);
};

simulateEnd();

end true TypeError true

// Wichtig · Fallstricke

Schreibgeschützt: session hat nur einen Getter. Eine Zuweisung wird ignoriert, in Modulen und im strict mode wirft sie einen TypeError.
Nach end nicht mehr benutzbar: Die Sitzung aus event.session ist nach dem end-Ereignis beendet. Aufrufe wie requestAnimationFrame() oder requestReferenceSpace() bringen dann nichts mehr bzw. werden abgelehnt. Die Sitzung taugt nur noch zum Vergleichen und Aufräumen.
Pflichtangabe beim Konstruktor: new XRSessionEvent(type, init) verlangt init.session. Fehlt die Angabe, wird ein TypeError geworfen.
Browser-Unterstützung: Die API gibt es nur in Browsern mit WebXR (Chromium-basiert, Meta Quest Browser, Samsung Internet). Außerdem ist ein sicherer Kontext (HTTPS) nötig. Vor der Nutzung sollte man navigator.xr und isSessionSupported() prüfen. Firefox und Safari auf dem Desktop unterstützen WebXR nicht standardmäßig.
Meist ist event.session identisch mit event.target. Die Eigenschaft ist aber besser typisiert und auch bei weitergereichten oder manuell erzeugten Ereignissen eindeutig.

Siehe auch

XRSessionEvent XRSession XRSession.visibilityState XRSystem.requestSession() IntersectionObserverEntry.rootBounds