new XRSessionEvent() — Methode · JavaScript-Referenz

Signatur

new XRSessionEvent(type, eventInitDict)

Beschreibung

Der Konstruktor XRSessionEvent() der WebXR Device API erstellt ein Ereignisobjekt vom Typ XRSessionEvent. Solche Ereignisse zeigen Zustandsänderungen einer XRSession an. Die schreibgeschützte Eigenschaft session verweist dabei auf die betroffene Sitzung.

Normalerweise erzeugt der Browser diese Ereignisse selbst, etwa end, wenn eine Sitzung beendet wird, oder visibilitychange, wenn sich die Sichtbarkeit der XR-Inhalte ändert (visible, visible-blurred, hidden). Den Konstruktor ruft man selbst vor allem in drei Fällen auf:

in Unit-Tests und Mocks, um Sitzungsereignisse nachzustellen,
für eigene Ereignisse im Anwendungscode, die an ein EventTarget weitergegeben werden,
für Polyfills und Emulatoren der WebXR-API.

Beachte: Ein selbst erzeugtes und mit dispatchEvent() ausgelöstes Ereignis ändert den tatsächlichen Zustand der Sitzung nicht. Ein künstliches end-Ereignis beendet die Sitzung also nicht. Dafür ist XRSession.end() zuständig.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses, Groß-/Kleinschreibung zählt. Der Browser selbst verwendet `"end"` und `"visibilitychange"`.
$eventInitDict Pflicht	XRSessionEventInit		Konfigurationsobjekt. Pflichtfeld ist `session` (die zugehörige `XRSession`). Zusätzlich sind die Felder aus `EventInit` erlaubt: `bubbles`, `cancelable` und `composed` (jeweils Standardwert `false`).

Rückgabewert

Typ

XRSessionEvent

Beschreibung

Ein neues XRSessionEvent-Objekt. Seine Eigenschaft session verweist auf die übergebene XRSession.

Beispiele

Ereignis erzeugen und Eigenschaften prüfen

const startXR = async () => {
  if (!navigator.xr || !(await navigator.xr.isSessionSupported('immersive-vr'))) {
    console.log('WebXR (immersive-vr) nicht verfügbar');
    return;
  }
  // Sitzung muss durch eine Nutzeraktion (z. B. Klick) gestartet werden
  const session = await navigator.xr.requestSession('immersive-vr');

  const event = new XRSessionEvent('visibilitychange', { session });
  console.log(event.type);                // Ereignisname
  console.log(event.session === session); // Verweis auf die Sitzung
  console.log(event instanceof Event);

  await session.end();
};

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

visibilitychange true true

Sitzungsende im Test simulieren

// Handler, der beim Sitzungsende aufräumt
const onSessionEnded = (event) => {
  console.log('Sitzung beendet, räume auf …', event.session.visibilityState);
};

const testEndHandler = (session) => {
  session.addEventListener('end', onSessionEnded, { once: true });

  // Künstliches end-Ereignis: ruft nur den Handler auf, beendet die Sitzung aber NICHT
  const fakeEnd = new XRSessionEvent('end', { session });
  session.dispatchEvent(fakeEnd);
};

document.querySelector('#test').addEventListener('click', async () => {
  const session = await navigator.xr.requestSession('inline');
  testEndHandler(session);
});

Sitzung beendet, räume auf … visible

Eigenes Anwendungsereignis über einen EventTarget-Bus weiterreichen

const xrBus = new EventTarget();

xrBus.addEventListener('xr-ready', (e) => {
  console.log('XR bereit, Modus:', e.session.environmentBlendMode ?? 'unbekannt');
});

const initXR = async () => {
  const session = await navigator.xr.requestSession('inline');
  xrBus.dispatchEvent(new XRSessionEvent('xr-ready', { session }));
};

document.querySelector('#start').addEventListener('click', initXR);

XR bereit, Modus: opaque

// Wichtig · Fallstricke

Pflichtfeld session: Fehlt es im Initialisierungsobjekt oder ist es keine echte XRSession, wird ein TypeError ausgelöst. Plain-Objekte als Ersatz funktionieren nicht. In Tests braucht man dafür eine echte Sitzung, etwa 'inline', oder einen Emulator.
Keine Zustandsänderung: Mit dispatchEvent() ausgelöste Ereignisse haben isTrusted === false und ändern den Zustand der Sitzung nicht. Ein künstliches end beendet die Sitzung nicht, ein künstliches visibilitychange ändert session.visibilityState nicht.
Sicherer Kontext: WebXR ist nur über HTTPS oder localhost verfügbar. Immersive Sitzungen erfordern eine Nutzeraktion und können über die Permissions-Policy xr-spatial-tracking gesperrt sein, zum Beispiel in iframes.
Kompatibilität: Die API ist experimentell und wird nur in Chromium-basierten Browsern (Chrome, Edge, Samsung Internet, Meta Quest Browser) unterstützt. Firefox und Safari auf dem Desktop bieten keinen Support. Prüfe die Verfügbarkeit vorher mit 'XRSessionEvent' in window.

Siehe auch

XRSessionEvent XRSessionEvent.session XRSession XRSession.end() XRSystem.requestSession() EventTarget.dispatchEvent()