XRSession.interactionMode — Eigenschaft · JavaScript-Referenz

Signatur

XRSession.interactionMode

Beschreibung

Die schreibgeschützte Eigenschaft interactionMode des XRSession-Interfaces gibt an, in welchem Raum die Anwendung ihre interaktive Bedienoberfläche nach Einschätzung des Browsers am besten darstellt. Sie gehört zum WebXR Augmented Reality Module und ist vor allem bei immersive-ar-Sitzungen interessant.

Es gibt zwei mögliche Werte:

"screen-space": Die Oberfläche soll direkt auf dem Bildschirm liegen, also als 2D-Overlay. Typisch für handgehaltene Geräte wie Smartphones mit AR, bei denen man per Touch bedient. Oft kombiniert man das mit dem DOM Overlay-Feature.
"world-space": Die Oberfläche soll als 3D-Objekt in der Szene stehen, erreichbar über Eingabequellen wie Controller oder Hände. Typisch für Headsets.

Die Eigenschaft ist nützlich, wenn eine Anwendung auf verschiedenen Gerätetypen laufen soll: Man fragt den Wert einmal nach dem Start der Sitzung ab und wählt dann die passende Art der Oberfläche. Der Wert bleibt während der Sitzung gleich.

Rückgabewert

Typ

"screen-space" | "world-space"

Beschreibung

Ein String aus der Aufzählung XRInteractionMode. Er beschreibt den empfohlenen Raum für interaktive Bedienelemente.

Beispiele

Interaktionsmodus nach Sitzungsstart auslesen

const startAR = async () => {
  if (!navigator.xr || !(await navigator.xr.isSessionSupported('immersive-ar'))) {
    console.log('AR wird nicht unterstützt');
    return;
  }
  const session = await navigator.xr.requestSession('immersive-ar');
  console.log('Interaktionsmodus:', session.interactionMode);
};

document.querySelector('#ar-button').addEventListener('click', startAR);

Interaktionsmodus: screen-space

Oberfläche passend zum Gerät wählen (DOM Overlay oder 3D-Panel)

const overlayRoot = document.querySelector('#overlay');

const startSession = async () => {
  const session = await navigator.xr.requestSession('immersive-ar', {
    optionalFeatures: ['dom-overlay'],
    domOverlay: { root: overlayRoot }
  });

  switch (session.interactionMode) {
    case 'screen-space':
      // Smartphone: HTML-Overlay mit Touch-Buttons anzeigen
      overlayRoot.hidden = false;
      console.log('2D-Overlay aktiv');
      break;
    case 'world-space':
      // Headset: Menü als 3D-Objekt in der Szene platzieren
      overlayRoot.hidden = true;
      console.log('3D-Menü im Raum aktiv');
      break;
    default:
      // Eigenschaft nicht unterstützt (undefined)
      console.log('Unbekannter Modus, Standard-UI verwenden');
  }
  return session;
};

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

2D-Overlay aktiv

Funktionsprüfung mit Rückfallwert

const getInteractionMode = (session) =>
  'interactionMode' in session ? session.interactionMode : 'world-space';

navigator.xr?.requestSession('immersive-ar').then((session) => {
  const mode = getInteractionMode(session);
  document.body.dataset.xrMode = mode;
  console.log(`UI-Modus: ${mode}`);
});

UI-Modus: world-space

// Wichtig · Fallstricke

Experimentell: Die Eigenschaft gibt es derzeit nur in Chromium-Browsern mit WebXR-AR-Unterstützung (z. B. Chrome für Android). Firefox und Safari unterstützen sie nicht. Prüfe deshalb mit 'interactionMode' in session und plane einen Rückfallwert ein.
Schreibgeschützt: Wenn du der Eigenschaft etwas zuweist, passiert nichts (im Strict Mode gibt es einen TypeError). Welcher Modus gilt, entscheidet allein der Browser.
Bei immersive-vr- oder inline-Sitzungen ist der Wert meist "world-space" oder nicht sinnvoll. Wirklich aussagekräftig ist er vor allem bei AR.
WebXR funktioniert nur in einem sicheren Kontext (HTTPS). Außerdem braucht requestSession() für immersive Sitzungen eine Benutzeraktion, zum Beispiel einen Klick.
Der Wert "screen-space" bedeutet nicht automatisch, dass DOM Overlay verfügbar ist. Prüfe das separat über session.domOverlayState.

Siehe auch

XRSession XRSystem.requestSession() XRSession.domOverlayState XRSession.environmentBlendMode XRInputSource IntersectionObserverEntry.intersectionRect PerformanceSoftNavigation.interactionId