Navigator.xr — Eigenschaft · JavaScript-Referenz

Signatur

get Navigator.xr

Beschreibung

Über navigator.xr greifen Sie auf die WebXR Device API zu. Das zurückgegebene XRSystem-Objekt ist pro Dokument ein einziges Objekt (Singleton). Damit prüfen Sie, ob ein Sitzungsmodus unterstützt wird (isSessionSupported()), und fordern immersive VR- oder AR-Sitzungen oder Inline-Sitzungen an (requestSession()).

Die Eigenschaft gibt es nur in sicheren Kontexten (HTTPS oder localhost). Unterstützt ein Browser WebXR nicht, ist navigator.xr undefined. Prüfen Sie das daher immer zuerst, zum Beispiel mit 'xr' in navigator, bevor Sie einen „VR starten“- oder „AR starten“-Button anzeigen.

Das XRSystem erbt von EventTarget und löst das Ereignis devicechange aus, wenn XR-Geräte angeschlossen oder getrennt werden. So kann Ihre Oberfläche reagieren, wenn sich die Verfügbarkeit ändert.

Rückgabewert

Typ

XRSystem | undefined

Beschreibung

Das XRSystem-Objekt des aktuellen Dokuments oder undefined, wenn der Browser WebXR nicht unterstützt oder die Seite nicht in einem sicheren Kontext läuft.

Beispiele

WebXR-Unterstützung erkennen und VR-Button einblenden

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

const initXR = async () => {
  if (!('xr' in navigator)) {
    console.log('WebXR wird nicht unterstützt');
    return;
  }
  const supported = await navigator.xr.isSessionSupported('immersive-vr');
  vrButton.hidden = !supported;
  console.log('immersive-vr unterstützt:', supported);
};

initXR();

immersive-vr unterstützt: true

Immersive VR-Sitzung per Klick starten

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

vrButton.addEventListener('click', async () => {
  try {
    // requestSession muss durch eine Benutzeraktion ausgelöst werden
    const session = await navigator.xr.requestSession('immersive-vr', {
      optionalFeatures: ['local-floor', 'hand-tracking']
    });
    console.log('Sitzung gestartet:', session.environmentBlendMode);

    session.addEventListener('end', () => {
      console.log('VR-Sitzung beendet');
    });
  } catch (err) {
    console.error('Sitzung konnte nicht gestartet werden:', err.name);
  }
});

Sitzung gestartet: opaque

Auf angeschlossene oder getrennte Geräte reagieren (devicechange)

const arButton = document.querySelector('#enter-ar');

const updateAR = async () => {
  arButton.hidden = !(await navigator.xr.isSessionSupported('immersive-ar'));
};

if (navigator.xr) {
  updateAR();
  navigator.xr.addEventListener('devicechange', updateAR);
  // alternativ: navigator.xr.ondevicechange = updateAR;
}

// Wichtig · Fallstricke

Nur in sicheren Kontexten: Über HTTP (außer localhost) ist navigator.xr undefined.
Browser-Unterstützung: Chromium-basierte Browser (Chrome, Edge, Samsung Internet) und der Meta Quest Browser unterstützen die API. Firefox bietet WebXR auf dem Desktop nicht an. Safari unterstützt es nur unter visionOS. Für eine Vorschau ohne Brille hilft die Erweiterung „WebXR API Emulator“.
Berechtigungsrichtlinie (Permissions Policy): In <iframe>-Elementen brauchen Sie allow="xr-spatial-tracking", sonst schlagen Sitzungsanfragen mit SecurityError fehl.
Benutzeraktion nötig: requestSession() für immersive Modi funktioniert nur als Reaktion auf eine Benutzeraktion, etwa einen Klick. Sonst wird das Promise mit SecurityError abgelehnt.
Pro Dokument kann nur eine immersive Sitzung gleichzeitig aktiv sein. Ein zweiter Versuch führt zu InvalidStateError.
Ein true von isSessionSupported() garantiert nicht, dass die Sitzung auch startet. Nutzer können ablehnen, oder das Gerät ist belegt. Fangen Sie Fehler deshalb immer ab.
Die ältere WebVR-API (navigator.getVRDisplays()) ist veraltet und durch WebXR ersetzt.

Siehe auch

XRSystem XRSystem.isSessionSupported() XRSystem.requestSession() XRSession Navigator NavigationTransition.from