XRSession.enabledFeatures — Eigenschaft · JavaScript-Referenz

Signatur

XRSession.enabledFeatures

Beschreibung

Beim Start einer WebXR-Sitzung mit navigator.xr.requestSession() fordert man Funktionen über requiredFeatures und optionalFeatures an, zum Beispiel "local-floor", "hand-tracking", "hit-test", "anchors", "dom-overlay" oder "depth-sensing". Pflichtfunktionen müssen gewährt werden, sonst schlägt die Anfrage fehl. Optionale Funktionen dagegen kann der Browser ablehnen, ohne dass die Sitzung abbricht.

enabledFeatures zeigt, welche Funktionen am Ende tatsächlich gewährt wurden. Ohne diese Eigenschaft müsste man es indirekt prüfen, etwa mit einem try/catch um requestReferenceSpace() oder requestHitTestSource(). Mit ihr kann die Anwendung direkt nach dem Start den passenden Weg wählen: zum Beispiel Controller statt Hand-Tracking oder einen "local"- statt eines "local-floor"-Referenzraums.

Das Array ist während der ganzen Sitzung gleich, denn Funktionen werden nur beim Sitzungsstart vergeben. Es enthält auch Funktionen, die der Browser je nach Sitzungsmodus automatisch aktiviert, etwa "viewer" und "local" bei immersive-vr.

Rückgabewert

Typ

ReadonlyArray<string>

Beschreibung

Ein eingefrorenes Array aus Zeichenketten mit den Namen der gewährten Funktionen (z. B. ["viewer", "local", "local-floor", "hand-tracking"]). Es enthält Pflichtfunktionen, gewährte optionale Funktionen und je nach Modus automatisch aktivierte Funktionen.

Beispiele

Gewährte Funktionen nach dem Sitzungsstart ausgeben

const startXR = async () => {
  const session = await navigator.xr.requestSession('immersive-vr', {
    requiredFeatures: ['local-floor'],
    optionalFeatures: ['hand-tracking', 'layers']
  });

  console.log('Aktiviert:', session.enabledFeatures);
  return session;
};

// Muss durch eine Benutzeraktion ausgelöst werden
document.querySelector('#vr-button').addEventListener('click', startXR);

Aktiviert: ["viewer", "local", "local-floor", "hand-tracking"]

Ersatzweg: Hand-Tracking oder Controller

const setupInput = (session) => {
  const features = session.enabledFeatures ?? [];

  if (features.includes('hand-tracking')) {
    console.log('Hand-Tracking aktiv – Gesten-Steuerung wird genutzt');
  } else {
    console.log('Kein Hand-Tracking – Controller-Steuerung wird genutzt');
  }
};

const session = await navigator.xr.requestSession('immersive-vr', {
  optionalFeatures: ['hand-tracking']
});
setupInput(session);

Hand-Tracking aktiv – Gesten-Steuerung wird genutzt

Passenden Referenzraum wählen

const getReferenceSpace = async (session) => {
  const features = session.enabledFeatures ?? [];
  const type = features.includes('bounded-floor') ? 'bounded-floor'
    : features.includes('local-floor') ? 'local-floor'
    : 'local';

  console.log(`Verwende Referenzraum: ${type}`);
  return session.requestReferenceSpace(type);
};

const session = await navigator.xr.requestSession('immersive-vr', {
  optionalFeatures: ['bounded-floor', 'local-floor']
});
const refSpace = await getReferenceSpace(session);

Verwende Referenzraum: local-floor

AR-Hit-Test nur bei Freigabe einrichten

const session = await navigator.xr.requestSession('immersive-ar', {
  optionalFeatures: ['hit-test', 'dom-overlay'],
  domOverlay: { root: document.body }
});

if (session.enabledFeatures?.includes('hit-test')) {
  const viewerSpace = await session.requestReferenceSpace('viewer');
  const hitTestSource = await session.requestHitTestSource({ space: viewerSpace });
  console.log('Hit-Test bereit', hitTestSource);
} else {
  console.warn('Hit-Test nicht verfügbar – Platzierung per Tippen deaktiviert');
}

Hit-Test bereit XRHitTestSource {}

// Wichtig · Fallstricke

Experimentell und wenig verbreitet: enabledFeatures ist bisher nur in Chromium-Browsern verfügbar (Chrome/Edge ab Version 121, Chrome für Android, Meta Quest Browser). In älteren Browsern ist die Eigenschaft undefined. Deshalb absichern, z. B. mit session.enabledFeatures ?? [] oder ?.includes().
Schreibgeschützt und fest: Zuweisungen haben keine Wirkung (im Strict Mode werfen sie einen TypeError). Das Array ist eingefroren, und während der Sitzung kommen keine Funktionen hinzu.
Automatisch aktivierte Funktionen: Das Array kann mehr enthalten als angefordert, etwa "viewer" und "local" bei immersiven Sitzungen. Nicht davon ausgehen, dass es nur die eigenen Angaben widerspiegelt.
Gewährt heißt nicht vollständig nutzbar: Auch eine gewährte Funktion wie "depth-sensing" kann noch weitere Konfiguration verlangen oder zur Laufzeit keine Daten liefern.
Datenschutz: Funktionen wie hand-tracking oder camera-access erfordern oft eine Zustimmung des Nutzers. Fehlt eine Funktion, hat der Nutzer sie vielleicht abgelehnt. Die Anwendung sollte dann ohne diese Funktion weiter nutzbar sein.
WebXR läuft nur in einem sicheren Kontext (HTTPS), und requestSession() für immersive Modi braucht eine Benutzeraktion.

Siehe auch

XRSession XRSystem.requestSession() XRSession.requestReferenceSpace() XRSession.requestHitTestSource() XRSystem.isSessionSupported() XRSession.inputSources Presentation.defaultRequest