XRInputSourceArray.length — Eigenschaft · JavaScript-Referenz

Signatur

XRInputSourceArray.length

Beschreibung

Die Eigenschaft length eines XRInputSourceArray gibt an, wie viele XRInputSource-Objekte die Liste gerade enthält. Ein solches Array bekommt man in der Regel über XRSession.inputSources. Es enthält alle Eingabegeräte, die gerade mit der XR-Sitzung verbunden sind, zum Beispiel Handcontroller, erfasste Hände, Blicksteuerung oder Bildschirmberührungen bei AR auf dem Smartphone.

XRInputSourceArray ist kein echtes Array, sondern ein Array-ähnliches Objekt. Mit length und Indexzugriff (inputSources[i]) lässt es sich in einer klassischen for-Schleife durchlaufen. Zusätzlich stehen forEach(), entries(), keys(), values() und der Iterator für for...of zur Verfügung.

Der Wert ist live: Wenn Controller verbunden oder getrennt werden, ändert er sich. Er kann auch in eine Richtung wechseln, wenn der Nutzer zwischen Controllern und Hand-Tracking umschaltet. Deshalb sollte man length in jedem Frame neu lesen oder auf das Ereignis inputsourceschange reagieren, statt den Wert einmalig zwischenzuspeichern.

Rückgabewert

Typ

number

Beschreibung

Eine nicht-negative Ganzzahl mit der Anzahl der aktuell in der Liste enthaltenen XRInputSource-Objekte. Ist 0, wenn kein Eingabegerät verbunden ist.

Beispiele

Anzahl verbundener Controller beim Sitzungsstart ausgeben

const startXR = async () => {
  if (!navigator.xr || !(await navigator.xr.isSessionSupported('immersive-vr'))) {
    console.log('Immersives VR wird nicht unterstützt.');
    return;
  }
  const session = await navigator.xr.requestSession('immersive-vr');
  console.log(`Eingabequellen: ${session.inputSources.length}`);
};

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

Eingabequellen: 2

Eingabequellen im Render-Loop per Index durchlaufen

const onXRFrame = (time, frame) => {
  const session = frame.session;
  const refSpace = session.__refSpace; // vorher per requestReferenceSpace gesetzt
  const sources = session.inputSources;

  for (let i = 0; i < sources.length; i++) {
    const source = sources[i];
    const pose = frame.getPose(source.targetRaySpace, refSpace);
    if (pose) {
      const { x, y, z } = pose.transform.position;
      console.log(`${source.handedness}: ${x.toFixed(2)}, ${y.toFixed(2)}, ${z.toFixed(2)}`);
    }
  }
  session.requestAnimationFrame(onXRFrame);
};

left: -0.21, 1.10, -0.35 right: 0.24, 1.12, -0.33

Auf wechselnde Anzahl reagieren (inputsourceschange)

const watchInputs = (session) => {
  session.addEventListener('inputsourceschange', (event) => {
    const count = event.session.inputSources.length;
    console.log(`Hinzugefügt: ${event.added.length}, entfernt: ${event.removed.length}, aktuell: ${count}`);
    document.querySelector('#hint').hidden = count > 0;
  });
};

Hinzugefügt: 1, entfernt: 0, aktuell: 1

// Wichtig · Fallstricke

Schreibgeschützt: Wenn man length einen Wert zuweist, passiert nichts. Im Strict Mode wird ein TypeError ausgelöst. Die Liste lässt sich damit weder kürzen noch leeren.
Kein echtes Array: Methoden wie map(), filter() oder find() gibt es nicht. Falls nötig, vorher mit Array.from(session.inputSources) oder [...session.inputSources] umwandeln.
Live-Wert: length kann sich zwischen zwei Frames ändern. Man sollte die Länge nicht dauerhaft zwischenspeichern und keine Indizes über Frames hinweg als stabile Kennung benutzen. Besser ist es, die XRInputSource-Objekte selbst als Schlüssel zu verwenden, zum Beispiel in einer Map.
Leere Liste ist normal: Direkt nach requestSession() kann length noch 0 sein, weil sich Controller erst verbinden. Daher auf inputsourceschange warten.
Kompatibilität: Die WebXR Device API gibt es nur in sicheren Kontexten (HTTPS). Unterstützt wird sie vor allem von Chromium-basierten Browsern und dem Meta Quest Browser. Firefox und Safari auf dem Desktop unterstützen sie nicht, Safari auf visionOS nur eingeschränkt. Vorher immer navigator.xr prüfen.

Siehe auch

XRInputSourceArray XRInputSource XRSession.inputSources XRInputSourceArray.prototype.forEach() XRFrame.prototype.getPose() OfflineAudioContext.length