XRSession.domOverlayState — Eigenschaft · JavaScript-Referenz

Signatur

XRSession.domOverlayState

Beschreibung

Mit XRSession.domOverlayState prüfst du, ob in einer AR-Sitzung ein DOM-Overlay tatsächlich aktiv ist. So ein Overlay legt normale HTML-Elemente wie Buttons, Menüs oder Statusanzeigen über die AR-Szene. Das Feature wird beim Start der Sitzung über navigator.xr.requestSession("immersive-ar", { optionalFeatures: ["dom-overlay"], domOverlay: { root } }) angefordert.

Die Eigenschaft liefert ein Objekt mit dem Feld type. Es beschreibt, wie das Overlay dargestellt wird:

"screen": Das Overlay liegt als 2D-Ebene über dem ganzen Bildschirm. Das ist typisch für Smartphones mit Handheld-AR.
"floating": Das Overlay schwebt als 2D-Fläche im Raum. Dieser Wert ist für Headsets gedacht.
"head-locked": Das Overlay ist fest an die Kopfbewegung gebunden.

Wurde dom-overlay nur als optionales Feature angefordert und vom Gerät nicht gewährt, ist der Wert null (oder die Eigenschaft fehlt ganz). Prüfe sie deshalb nach dem Sitzungsstart immer, bevor du deine Oberfläche auf das Overlay ausrichtest. Dann kannst du bei Bedarf auf eine Bedienung umschalten, die nur mit WebGL gezeichnet ist.

Rückgabewert

Typ

XRDOMOverlayState | null

Beschreibung

Ein Objekt mit der Eigenschaft type ("screen", "floating" oder "head-locked"). Wenn kein DOM-Overlay aktiv ist, lautet der Wert null; ohne Unterstützung für das Modul ist er undefined.

Beispiele

AR-Sitzung mit DOM-Overlay starten und Overlay-Typ prüfen

const overlayRoot = document.getElementById('ar-overlay');

const startAR = async () => {
  if (!(await navigator.xr?.isSessionSupported('immersive-ar'))) {
    console.warn('immersive-ar wird nicht unterstützt');
    return;
  }
  const session = await navigator.xr.requestSession('immersive-ar', {
    optionalFeatures: ['dom-overlay'],
    domOverlay: { root: overlayRoot }
  });

  const state = session.domOverlayState;
  console.log(state ? `Overlay aktiv: ${state.type}` : 'Kein DOM-Overlay verfügbar');
};

// requestSession braucht eine Benutzeraktion
document.getElementById('start-ar').addEventListener('click', startAR);

Overlay aktiv: screen

Bedienung mit WebGL als Ausweichlösung, wenn kein Overlay aktiv ist

const setupUI = (session) => {
  const hud = document.getElementById('ar-overlay');
  if (session.domOverlayState) {
    // HTML-Oberfläche anzeigen
    hud.hidden = false;
  } else {
    // Kein Overlay: Buttons im 3D-Raum zeichnen
    hud.hidden = true;
    enableWebGLButtons(session);
  }
};

const enableWebGLButtons = (session) => {
  session.addEventListener('select', () => console.log('3D-Button ausgewählt'));
};

Layout an den Overlay-Typ anpassen

const applyOverlayLayout = (session) => {
  const type = session.domOverlayState?.type;
  const root = document.getElementById('ar-overlay');
  switch (type) {
    case 'screen':
      root.classList.add('fullscreen-hud');
      break;
    case 'floating':
    case 'head-locked':
      root.classList.add('compact-panel');
      break;
    default:
      console.log('Kein DOM-Overlay');
  }
  return type ?? null;
};

// Wichtig · Fallstricke

Browserunterstützung: Die Eigenschaft ist experimentell und praktisch nur in Chromium-Browsern unter Android verfügbar, etwa in Chrome oder Samsung Internet mit ARCore. Firefox und Safari unterstützen sie nicht. Frage die Eigenschaft deshalb immer mit optionaler Verkettung ab (session.domOverlayState?.type).
Die Eigenschaft existiert nur bei immersive-ar-Sitzungen. Bei immersive-vr oder inline ist sie null bzw. undefined.
Ohne die Option domOverlay: { root } in requestSession() wird kein Overlay erzeugt. Das gilt auch dann, wenn "dom-overlay" in den Features steht. Als root muss ein Element im Dokument angegeben werden.
WebXR braucht einen sicheren Kontext (HTTPS) und eine Benutzeraktion zum Starten der Sitzung. In iframes ist zusätzlich die Berechtigungsrichtlinie xr-spatial-tracking nötig.
Eingaben auf das Overlay können zusätzlich XR-select-Ereignisse auslösen. Mit dem Ereignis beforexrselect auf dem Overlay-Element und preventDefault() verhinderst du doppelte Aktionen.
Solange die Sitzung läuft, verhält sich das Overlay-Element ähnlich wie ein Element im Vollbildmodus. Die CSS-Pseudoklasse :xr-overlay erlaubt dafür eigene Stile.

Siehe auch

XRSession XRSystem.requestSession() XRSystem.isSessionSupported() XRSession.end() IntersectionObserverEntry.target