new XRReferenceSpaceEvent() — Methode · JavaScript-Referenz

Signatur

new XRReferenceSpaceEvent(type, eventInitDict)

Beschreibung

Der Konstruktor XRReferenceSpaceEvent() erzeugt ein Ereignisobjekt vom Typ XRReferenceSpaceEvent. Solche Ereignisse löst die WebXR Device API aus, wenn sich der Zustand eines XRReferenceSpace ändert. Der wichtigste Fall ist das Ereignis reset: Es tritt auf, wenn der Ursprung des Referenzraums plötzlich verschoben wird. Das passiert zum Beispiel, wenn jemand auf der Brille die Ansicht neu zentriert oder das Tracking verloren geht und wiederhergestellt wird.

Normalerweise erzeugt der Browser diese Ereignisse selbst. Den Konstruktor ruft man in der Praxis vor allem in Tests, Polyfills oder Emulatoren auf. Dort will man einen Reset nachstellen und prüfen, ob die Anwendung richtig reagiert, etwa ob sie die Kamera oder verankerte Objekte neu ausrichtet.

Das Ereignis hat zwei eigene Eigenschaften: referenceSpace ist der betroffene Referenzraum und immer erforderlich. transform ist ein optionales XRRigidTransform. Es beschreibt, wie der alte Ursprung im neuen Koordinatensystem liegt. Damit kann man gespeicherte Positionen in das neue System umrechnen.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses. Laut Spezifikation ist derzeit nur `"reset"` vorgesehen.
$eventInitDict Pflicht	XRReferenceSpaceEventInit		Objekt mit den Initialwerten. Es erbt von `EventInit`, also sind `bubbles`, `cancelable` und `composed` möglich. Zusätzlich gibt es: `referenceSpace` (`XRReferenceSpace`, Pflicht): der Referenzraum, auf den sich das Ereignis bezieht. `transform` (`XRRigidTransform \| null`, optional, Standard `null`): Transformation vom alten zum neuen Ursprung.

Rückgabewert

Typ

XRReferenceSpaceEvent

Beschreibung

Ein neues XRReferenceSpaceEvent-Objekt mit den angegebenen Werten. Man kann es mit dispatchEvent() an einem XRReferenceSpace auslösen.

Beispiele

Reset-Ereignis erzeugen und auslösen (z. B. im Test)

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

refSpace.addEventListener('reset', (event) => {
  console.log('Reset empfangen:', event.type, event.referenceSpace === refSpace);
});

// Simulierter Reset, z. B. in einem automatisierten Test
const resetEvent = new XRReferenceSpaceEvent('reset', {
  referenceSpace: refSpace
});
refSpace.dispatchEvent(resetEvent);

Reset empfangen: reset true

Reset mit Transformation nachstellen

const session = await navigator.xr.requestSession('immersive-vr');
const refSpace = await session.requestReferenceSpace('local-floor');

// Alter Ursprung liegt 1 m vor dem neuen und ist 90° um die Y-Achse gedreht
const transform = new XRRigidTransform(
  { x: 0, y: 0, z: -1 },
  { x: 0, y: Math.SQRT1_2, z: 0, w: Math.SQRT1_2 }
);

const event = new XRReferenceSpaceEvent('reset', {
  referenceSpace: refSpace,
  transform
});

console.log(event.transform.position.z);
refSpace.dispatchEvent(event);

-1

Auf echte Resets reagieren (onreset-Property)

const session = await navigator.xr.requestSession('immersive-ar');
let refSpace = await session.requestReferenceSpace('local');

refSpace.onreset = (event) => {
  if (event.transform) {
    // Gespeicherte Positionen in das neue Koordinatensystem umrechnen
    console.log('Offset-Matrix:', event.transform.matrix);
  } else {
    console.log('Reset ohne Transformation – Szene neu ausrichten');
  }
};

Reset ohne Transformation – Szene neu ausrichten

// Wichtig · Fallstricke

Browser-Kompatibilität: WebXR und damit XRReferenceSpaceEvent gibt es vor allem in Chromium-Browsern (Chrome, Edge, Samsung Internet) und im Meta Quest Browser. Firefox und Safari unterstützen WebXR standardmäßig nicht oder nur eingeschränkt, Safari auf visionOS teilweise. Deshalb vorher prüfen: 'XRReferenceSpaceEvent' in window.
Sicherer Kontext: WebXR funktioniert nur über HTTPS oder localhost. Eine immersive Sitzung braucht außerdem eine Nutzeraktion, zum Beispiel einen Klick.
Ohne referenceSpace wirft der Konstruktor einen TypeError.
Selbst erzeugte Ereignisse haben isTrusted === false. Sie verändern den Referenzraum nicht wirklich, sondern rufen nur die registrierten Listener auf.
Bei manchen Resets ist transform null, etwa wenn das Gerät den Versatz nicht kennt. Die Anwendung muss diesen Fall selbst behandeln.
Bei Referenzräumen vom Typ viewer tritt reset nie auf.

Siehe auch

new CharacterBoundsUpdateEvent() new BufferedChangeEvent() new MediaEncryptedEvent() new MediaKeyMessageEvent() new PageRevealEvent()