new XRInputSourcesChangeEvent() — Methode · JavaScript-Referenz

Signatur

new XRInputSourcesChangeEvent(type, options)

Beschreibung

Der Konstruktor XRInputSourcesChangeEvent() erzeugt ein Ereignisobjekt vom Typ XRInputSourcesChangeEvent. Normalerweise legt der Browser solche Objekte selbst an und löst sie als inputsourceschange-Ereignis auf einer XRSession aus. Das passiert, wenn Controller eingeschaltet oder getrennt werden, wenn die Handerkennung startet oder wenn ein Controller in die andere Hand wechselt.

Selbst aufrufen muss man den Konstruktor nur selten. Nützlich ist er vor allem in Tests, in Emulatoren oder Polyfills und wenn man die eigene Controller-Verwaltung gezielt mit einem künstlichen Ereignis anstoßen will. Das Ereignis enthält zwei nur lesbare Arrays, added und removed, mit XRInputSource-Objekten sowie eine Referenz auf die betroffene session.

Das Options-Objekt muss eine gültige XRSession sowie die Arrays added und removed enthalten. XRInputSource-Objekte lassen sich nicht selbst erzeugen. Man bekommt sie nur über session.inputSources oder aus früheren Ereignissen. Deshalb setzt ein sinnvoller Konstruktor-Aufruf praktisch immer eine laufende WebXR-Sitzung voraus.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses. Bei WebXR ist das immer `"inputsourceschange"`. Groß- und Kleinschreibung werden unterschieden.
$options Pflicht	XRInputSourcesChangeEventInit		Objekt zur Initialisierung. Zusätzlich zu den Feldern von `EventInit` (`bubbles`, `cancelable`, `composed`) muss es folgende Felder enthalten: `session` (`XRSession`, Pflicht): die Sitzung, auf die sich das Ereignis bezieht. `added` (`XRInputSource[]`, Pflicht): die neu hinzugekommenen Eingabequellen, eventuell ein leeres Array. `removed` (`XRInputSource[]`, Pflicht): die entfernten Eingabequellen, eventuell ein leeres Array.

Rückgabewert

Typ

XRInputSourcesChangeEvent

Beschreibung

Ein neues XRInputSourcesChangeEvent-Objekt mit den Eigenschaften session, added und removed. Die beiden Arrays sind eingefroren und nur lesbar.

Beispiele

Auf echte Änderungen der Eingabegeräte reagieren

const session = await navigator.xr.requestSession('immersive-vr');

const controllers = new Map();

session.addEventListener('inputsourceschange', (event) => {
  for (const source of event.added) {
    controllers.set(source, { hand: source.handedness, profiles: source.profiles });
    console.log(`Neu: ${source.handedness} (${source.profiles[0] ?? 'unbekannt'})`);
  }
  for (const source of event.removed) {
    controllers.delete(source);
    console.log(`Entfernt: ${source.handedness}`);
  }
});

Neu: left (oculus-touch-v3) Neu: right (oculus-touch-v3)

Künstliches Ereignis erzeugen, um die aktuellen Geräte neu zu verarbeiten

const session = await navigator.xr.requestSession('immersive-vr');

session.addEventListener('inputsourceschange', (e) => {
  console.log('added:', e.added.length, 'removed:', e.removed.length);
});

// Zum Beispiel nach einem Neuaufbau der Szene alle vorhandenen Controller erneut anmelden
const syntheticEvent = new XRInputSourcesChangeEvent('inputsourceschange', {
  session,
  added: [...session.inputSources],
  removed: []
});

session.dispatchEvent(syntheticEvent);
console.log(syntheticEvent.isTrusted);

added: 2 removed: 0 false

Funktionsprüfung vor der Verwendung

const supportsXRInputEvents = () =>
  typeof window.XRInputSourcesChangeEvent === 'function' && 'xr' in navigator;

if (!supportsXRInputEvents()) {
  console.warn('WebXR-Eingabeereignisse werden hier nicht unterstützt.');
} else {
  const vrSupported = await navigator.xr.isSessionSupported('immersive-vr');
  console.log('immersive-vr verfügbar:', vrSupported);
}

immersive-vr verfügbar: true

// Wichtig · Fallstricke

Pflichtfelder: Fehlt session, added oder removed, wirft der Konstruktor einen TypeError. Ein Aufruf nur mit dem Typ-Namen, also new XRInputSourcesChangeEvent('inputsourceschange'), schlägt deshalb fehl.
Keine eigenen Eingabequellen: XRInputSource hat keinen öffentlichen Konstruktor. Die Arrays dürfen nur echte Objekte aus session.inputSources enthalten. Andere Werte führen zu einem TypeError.
Nicht vertrauenswürdig: Selbst ausgelöste Ereignisse haben isTrusted === false. An der tatsächlichen Liste session.inputSources ändern sie nichts.
Sichere Umgebung: WebXR funktioniert nur über HTTPS (oder localhost). In iframes muss die Permissions Policy xr-spatial-tracking erlaubt sein.
Browser-Unterstützung: Unterstützt in Chromium-Browsern (Chrome, Edge, Samsung Internet) und im Meta Quest Browser. Firefox Desktop und Safari auf macOS/iOS unterstützen WebXR nicht oder nur eingeschränkt, Safari auf visionOS teilweise. Deshalb immer vorher die Unterstützung prüfen, zum Beispiel mit 'xr' in navigator.
Referenzen nicht aufbewahren: Nach dem Ende der Sitzung (end-Ereignis) sollte man gespeicherte Verweise auf XRInputSource-Objekte löschen, damit kein Speicher verloren geht.

Siehe auch

XRInputSourcesChangeEvent XRInputSource XRSession.inputSources XRSession EventTarget.dispatchEvent() new ExtendableMessageEvent()