XRSystem: devicechange — Ereignis · JavaScript-Referenz

Signatur

navigator.xr.addEventListener("devicechange", handler)

Beschreibung

Das Ereignis devicechange wird auf dem XRSystem-Objekt (navigator.xr) ausgelöst, sobald sich die Verfügbarkeit immersiver XR-Geräte ändert. Das kann passieren, wenn ein VR-Headset oder eine AR-Brille angeschlossen oder getrennt wird oder wenn der Nutzer den XR-Dienst seines Betriebssystems startet bzw. beendet.

Das Ereignis ist ein ganz normales Event ohne zusätzliche Eigenschaften. Es verrät also nicht, welches Gerät hinzugekommen oder verschwunden ist. Im Handler fragst du deshalb mit navigator.xr.isSessionSupported() erneut ab, welche Sitzungsmodi ("immersive-vr", "immersive-ar") gerade verfügbar sind, und passt die Oberfläche an – etwa indem du einen „VR starten“-Button ein- oder ausblendest.

Du kannst den Handler per addEventListener("devicechange", handler) registrieren oder über die Eigenschaft navigator.xr.ondevicechange setzen. Das Ereignis ist nicht abbrechbar und steigt nicht auf (kein Bubbling).

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"devicechange"`.
$handler Pflicht	(event: Event) => void		Callback, der bei einer Änderung der Geräteverfügbarkeit aufgerufen wird. Er bekommt ein einfaches `Event`-Objekt.
$options	boolean \| AddEventListenerOptions	false	Übliche Optionen von `addEventListener`, z. B. `{ once: true }` oder `{ signal }`.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Der Handler erhält ein Event mit type === "devicechange" und target === navigator.xr.

Beispiele

VR-Button je nach Geräteverfügbarkeit ein- und ausblenden

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

const updateVrButton = async () => {
  const supported = await navigator.xr.isSessionSupported('immersive-vr');
  vrButton.hidden = !supported;
  console.log(`immersive-vr verfügbar: ${supported}`);
};

if ('xr' in navigator) {
  updateVrButton(); // Anfangszustand
  navigator.xr.addEventListener('devicechange', updateVrButton);
} else {
  vrButton.hidden = true;
}

immersive-vr verfügbar: false // nach dem Anschließen des Headsets: immersive-vr verfügbar: true

Handler über die Eigenschaft ondevicechange setzen und entfernen

if (navigator.xr) {
  navigator.xr.ondevicechange = async (event) => {
    const [vr, ar] = await Promise.all([
      navigator.xr.isSessionSupported('immersive-vr'),
      navigator.xr.isSessionSupported('immersive-ar'),
    ]);
    console.log(event.type, { vr, ar });
  };

  // Später, z. B. beim Verlassen der Ansicht:
  // navigator.xr.ondevicechange = null;
}

devicechange { vr: true, ar: false }

Listener mit AbortController sauber abmelden

const controller = new AbortController();

const onDeviceChange = async () => {
  const ok = await navigator.xr.isSessionSupported('immersive-vr');
  document.body.classList.toggle('xr-ready', ok);
};

navigator.xr?.addEventListener('devicechange', onDeviceChange, {
  signal: controller.signal,
});

// Komponente wird zerstört → Listener entfernen
const destroy = () => controller.abort();
// Alternativ: navigator.xr.removeEventListener('devicechange', onDeviceChange);

// Wichtig · Fallstricke

Kein Detail zum Gerät: Das Ereignis sagt nicht, welches Gerät sich geändert hat. Frag den Zustand immer mit isSessionSupported() neu ab.
Nicht bei jedem Einstecken garantiert: Browser und Betriebssystem (z. B. OpenXR-Runtime, SteamVR) entscheiden, wann sie eine Änderung melden. Viele Implementierungen erkennen ein Gerät erst, wenn dessen Runtime läuft. Werte deshalb beim Laden der Seite zusätzlich einmal den Anfangszustand aus.
Sicherer Kontext: navigator.xr gibt es nur über HTTPS (oder localhost). Per Permissions-Policy xr-spatial-tracking kann es außerdem in iframes gesperrt sein.
Kompatibilität: Wird von Chromium-basierten Browsern und dem Meta Quest Browser unterstützt, nicht aber von Firefox und Safari auf dem Desktop. Prüfe immer mit 'xr' in navigator, ob die API vorhanden ist.
Datenschutz: Die Geräteverfügbarkeit taugt als Merkmal für Fingerprinting. Browser können Ereignisse deshalb verzögern oder an Nutzerberechtigungen koppeln.

Siehe auch

XRSystem XRSystem.isSessionSupported() XRSystem.requestSession() XRSession EventTarget.addEventListener() Element: pointercancel HTMLSlotElement: slotchange