XRInputSourceArray — Schnittstelle · JavaScript-Referenz

Signatur

interface XRInputSourceArray

Beschreibung

XRInputSourceArray ist eine schreibgeschützte, dynamische Liste von XRInputSource-Objekten, also Controllern, getrackten Händen, Blickrichtung oder Bildschirmberührungen. Man erhält sie über XRSession.inputSources. Die Liste wird „live“ gepflegt: Verbindet oder trennt der Nutzer einen Controller, ändert sich der Inhalt, ohne dass man die Eigenschaft neu abfragen muss.

Die Schnittstelle ist kein echtes Array, verhält sich aber ähnlich. Sie bietet length, einen Indexzugriff (inputSources[0]), ist iterierbar (for...of, Spread-Syntax) und hat die Methoden entries(), keys(), values() und forEach(). Methoden wie map() oder filter() fehlen. Für diese wandelt man die Liste zuerst mit Array.from() oder [...inputSources] um.

Meistens liest man die Liste in jedem Frame innerhalb der Render-Schleife (requestAnimationFrame) aus und fragt dort für jede Eingabequelle über XRFrame.getPose() die Pose von targetRaySpace oder gripSpace ab. Änderungen an der Liste meldet zusätzlich das Event inputsourceschange der XRSession. Darüber kann man Controller-Modelle gezielt laden oder entfernen.

Parameter

Name	Typ	Beschreibung
$length	number	Schreibgeschützte Eigenschaft: aktuelle Anzahl der verbundenen Eingabequellen.
$[index]	number	Indexzugriff auf eine einzelne `XRInputSource`. Ist der Index ungültig, erhält man `undefined`.
$entries() / keys() / values()	function	Geben Iteratoren über die Paare aus Index und Eingabequelle, über die Indizes bzw. über die Eingabequellen zurück.
$forEach(callback[, thisArg])	function	Ruft `callback(source, index, array)` für jede Eingabequelle auf.

Rückgabewert

Typ

XRInputSourceArray

Beschreibung

Wird von XRSession.inputSources zurückgegeben. Es gibt keinen öffentlichen Konstruktor.

Beispiele

Liste aus der Sitzung holen und durchlaufen

const session = await navigator.xr.requestSession('immersive-vr');
const sources = session.inputSources; // XRInputSourceArray

console.log(`Verbundene Eingabequellen: ${sources.length}`);
for (const source of sources) {
  console.log(source.handedness, source.targetRayMode, source.profiles);
}

Verbundene Eingabequellen: 2 left tracked-pointer ["oculus-touch-v3", ...] right tracked-pointer ["oculus-touch-v3", ...]

Controller-Posen in jedem Frame auslesen

const onFrame = (time, frame) => {
  const session = frame.session;
  session.requestAnimationFrame(onFrame);

  for (const source of session.inputSources) {
    const space = source.gripSpace ?? source.targetRaySpace;
    const pose = frame.getPose(space, refSpace);
    if (pose) {
      const { x, y, z } = pose.transform.position;
      console.log(`${source.handedness}: ${x.toFixed(2)}, ${y.toFixed(2)}, ${z.toFixed(2)}`);
    }
  }
};

const refSpace = await session.requestReferenceSpace('local-floor');
session.requestAnimationFrame(onFrame);

right: 0.21, 1.05, -0.34

Array-Methoden über Array.from nutzen

// XRInputSourceArray hat kein filter() – daher erst umwandeln
const hands = Array.from(session.inputSources)
  .filter((source) => source.hand !== null && source.hand !== undefined);

console.log(`Getrackte Hände: ${hands.length}`);

// forEach steht direkt zur Verfügung
session.inputSources.forEach((source, i) => {
  console.log(i, source.profiles[0]);
});

Getrackte Hände: 2 0 generic-hand 1 generic-hand

Auf Änderungen der Liste reagieren

session.addEventListener('inputsourceschange', (event) => {
  event.added.forEach((s) => console.log('Neu:', s.handedness));
  event.removed.forEach((s) => console.log('Entfernt:', s.handedness));
  console.log('Jetzt aktiv:', session.inputSources.length);
});

Neu: left Jetzt aktiv: 2

// Wichtig · Fallstricke

Kein echtes Array: map(), filter(), find() und includes() fehlen. Nutzen Sie Array.from() oder die Spread-Syntax. Array.isArray(session.inputSources) liefert false.
Dynamisch: Die Liste kann sich zwischen zwei Frames ändern. Speichern Sie deshalb keine Indizes dauerhaft. Merken Sie sich stattdessen das XRInputSource-Objekt selbst oder dessen handedness.
Ist die Sitzung beendet, sind die Eingabequellen ungültig. Posen erhält man nur innerhalb eines gültigen XRFrame-Callbacks.
gripSpace ist bei Blick- oder Bildschirmeingaben (gaze, screen) undefined. Weichen Sie dann auf targetRaySpace aus.
Kompatibilität: WebXR steht nur in einem sicheren Kontext (HTTPS) zur Verfügung. Unterstützt wird es vor allem von Chromium-Browsern und dem Meta Quest Browser. Firefox und Safari auf dem Desktop unterstützen WebXR nicht. Prüfen Sie die Unterstützung vorab mit navigator.xr?.isSessionSupported().
Datenschutz: Handtracking liefert erst Daten, wenn es als Sitzungsfeature ('hand-tracking') angefordert und vom Nutzer genehmigt wurde.

Siehe auch

XRInputSource XRSession XRSession.inputSources XRFrame.getPose() XRInputSourcesChangeEvent