Navigator.getVRDisplays() — Methode · JavaScript-Referenz

Signatur

Navigator.prototype.getVRDisplays()

Beschreibung

Die Methode navigator.getVRDisplays() war der Einstiegspunkt der experimentellen WebVR-API. Mit ihr fragt man ab, welche VR-Headsets (z. B. Oculus Rift, HTC Vive, Google Cardboard oder Daydream) verfügbar sind. Das Promise wird mit einem Array von VRDisplay-Objekten erfüllt. Jedes davon steht für ein Gerät, das man für eine VR-Darstellung nutzen kann, etwa über VRDisplay.requestPresent() und VRDisplay.getFrameData().

Ist kein Gerät angeschlossen, wird das Promise mit einem leeren Array erfüllt. Es wird also nicht abgelehnt. Deshalb sollte man immer die Länge des Arrays prüfen, bevor man auf displays[0] zugreift.

Wichtig: WebVR gilt als veraltet und wurde nie ein offizieller Standard. Die meisten Browser haben die API entfernt oder nie ausgeliefert. In neuen Projekten verwendet man stattdessen die WebXR Device API mit navigator.xr.isSessionSupported() und navigator.xr.requestSession(). Diese Referenz ist vor allem für die Pflege von altem Code und für Migrationen gedacht.

Rückgabewert

Typ

Promise<VRDisplay[]>

Beschreibung

Ein Promise, das mit einem Array von VRDisplay-Objekten erfüllt wird. Das Array ist leer, wenn kein VR-Gerät gefunden wurde.

Beispiele

Verfügbare VR-Displays auflisten (mit Funktionsprüfung)

const listVRDisplays = async () => {
  if (!('getVRDisplays' in navigator)) {
    console.log('WebVR wird von diesem Browser nicht unterstützt.');
    return [];
  }
  const displays = await navigator.getVRDisplays();
  if (displays.length === 0) {
    console.log('Kein VR-Headset angeschlossen.');
  }
  displays.forEach((d) => console.log(`${d.displayId}: ${d.displayName}`));
  return displays;
};

listVRDisplays();

WebVR wird von diesem Browser nicht unterstützt. // oder in einem alten Browser mit WebVR, z. B.: // 1: Oculus Rift CV1

Erstes Display für die Darstellung auf einem Canvas nutzen

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

button.addEventListener('click', async () => {
  const [vrDisplay] = await navigator.getVRDisplays();
  if (!vrDisplay) {
    console.warn('Kein VR-Display gefunden.');
    return;
  }
  if (vrDisplay.capabilities.canPresent) {
    // requestPresent muss durch eine Nutzeraktion ausgelöst werden
    await vrDisplay.requestPresent([{ source: canvas }]);
    console.log(`Darstellung läuft auf: ${vrDisplay.displayName}`);
  }
});

Darstellung läuft auf: HTC Vive MV

Migration: zuerst WebXR, WebVR nur als Rückfalloption

const detectImmersiveSupport = async () => {
  if (navigator.xr) {
    const ok = await navigator.xr.isSessionSupported('immersive-vr');
    return ok ? 'webxr' : 'none';
  }
  if (navigator.getVRDisplays) {
    const displays = await navigator.getVRDisplays();
    return displays.length > 0 ? 'webvr' : 'none';
  }
  return 'none';
};

detectImmersiveSupport().then((mode) => console.log('VR-Modus:', mode));

VR-Modus: webxr

// Wichtig · Fallstricke

Veraltet und nicht standardisiert: WebVR gab es nur in älteren Firefox-Versionen, in Edge (Legacy), im Samsung Internet Browser und in Chrome hinter einem Flag bzw. per Origin Trial. In aktuellen Browsern fehlt navigator.getVRDisplays meistens ganz. Rufe die Methode nie ohne vorherige Funktionsprüfung auf, sonst gibt es einen TypeError.
Nachfolger: Verwende die WebXR Device API (navigator.xr). Für den Übergang gibt es das Polyfill webxr-polyfill, das WebXR auf WebVR-Geräten nachbildet.
Sicherer Kontext: Neuere Implementierungen verlangten HTTPS. Außerdem kann eine Permissions Policy (vr bzw. xr-spatial-tracking) den Zugriff in iframes blockieren.
Leeres Array statt Fehler: Fehlt ein Gerät, wird das Promise trotzdem erfüllt. Prüfe also displays.length.
Nutzeraktion erforderlich: Die Methode selbst braucht keine Nutzeraktion. Das anschließende requestPresent() muss aber durch eine Nutzeraktion wie einen Klick ausgelöst werden.
Datenschutz: Die Liste der Geräte kann zum Fingerprinting beitragen. Browser haben den Zugriff deshalb zum Teil eingeschränkt.

Siehe auch

VRDisplay Navigator.xr Navigator Navigator.getAutoplayPolicy() Navigator.getGamepads()