Element: beforexrselect — Ereignis · JavaScript-Referenz

Signatur

element.addEventListener("beforexrselect", handler)

Beschreibung

Das Ereignis beforexrselect gehört zum WebXR DOM Overlays Module. Läuft eine immersive AR-Sitzung mit der Option domOverlay, liegt ein normales HTML-Element (z. B. ein Menü oder ein Button) über der XR-Szene. Tippt oder zielt der Nutzer auf dieses Overlay, würden normalerweise zwei Dinge passieren: Das DOM erhält Klick- bzw. Pointer-Ereignisse und die XRSession erhält selectstart/select/selectend. In der Folge könnte etwa ein Tipp auf „Menü schließen“ gleichzeitig ein virtuelles Objekt in der Szene platzieren.

Genau das verhindert beforexrselect. Das Ereignis wird an dem Overlay-Element ausgelöst, das von der XR-Eingabe getroffen wird. Es steigt auf (bubbles) und ist abbrechbar (cancelable). Ruft man event.preventDefault() auf, unterdrückt der Browser die XR-Auswahlereignisse für diese Eingabe. Die DOM-Ereignisse wie click oder pointerdown kommen trotzdem an.

Einen Handler registriert man mit addEventListener("beforexrselect", …) oder über die Eigenschaft onbeforexrselect. Weil das Ereignis aufsteigt, reicht ein einziger Listener auf dem Container des Overlays. Das Ereignisobjekt ist laut MDN ein XRSessionEvent und liefert über event.session die aktive Sitzung.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"beforexrselect"`.
$handler Pflicht	(event: XRSessionEvent) => void		Callback, der das Ereignis erhält. Mit `event.preventDefault()` werden die zugehörigen XR-Auswahlereignisse unterdrückt.
$options	boolean \| AddEventListenerOptions	false	Übliche Listener-Optionen wie `capture`, `once` oder `signal`. Nicht `passive: true` setzen, sonst hat `preventDefault()` keine Wirkung.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Wirksam ist allein der Aufruf von preventDefault() im Handler.

Beispiele

AR-Sitzung mit DOM-Overlay starten und XR-Auswahl über dem Menü unterdrücken

const overlay = document.getElementById('ar-overlay');
const startBtn = document.getElementById('start-ar');

// Tipps auf das Overlay sollen keine XR-Auswahl auslösen
overlay.addEventListener('beforexrselect', (event) => {
  event.preventDefault();
});

startBtn.addEventListener('click', async () => {
  if (!(await navigator.xr?.isSessionSupported('immersive-ar'))) {
    console.log('immersive-ar wird nicht unterstützt');
    return;
  }
  const session = await navigator.xr.requestSession('immersive-ar', {
    optionalFeatures: ['dom-overlay'],
    domOverlay: { root: overlay }
  });

  session.addEventListener('select', () => {
    console.log('Objekt in der Szene platziert');
  });

  console.log('Overlay-Typ:', session.domOverlayState?.type);
});

Overlay-Typ: screen // Tippen auf das Overlay: kein 'select'-Log // Tippen daneben: Objekt in der Szene platziert

Nur bestimmte Bedienelemente abschirmen (Bubbling nutzen)

const overlay = document.getElementById('ar-overlay');

overlay.onbeforexrselect = (event) => {
  // Nur interaktive Elemente blockieren; freie Flächen des Overlays
  // lassen die XR-Auswahl weiterhin durch
  if (event.target.closest('button, input, [data-blocks-xr]')) {
    event.preventDefault();
    console.log('XR-Auswahl blockiert für:', event.target.id || event.target.tagName);
  }
};

XR-Auswahl blockiert für: btn-close

Listener beim Sitzungsende entfernen

const overlay = document.getElementById('ar-overlay');

const blockXrSelect = (event) => event.preventDefault();
overlay.addEventListener('beforexrselect', blockXrSelect);

const session = await navigator.xr.requestSession('immersive-ar', {
  optionalFeatures: ['dom-overlay'],
  domOverlay: { root: overlay }
});

session.addEventListener('end', () => {
  overlay.removeEventListener('beforexrselect', blockXrSelect);
  // alternativ bei Nutzung der Property: overlay.onbeforexrselect = null;
  console.log('Sitzung beendet, Listener entfernt');
}, { once: true });

Sitzung beendet, Listener entfernt

// Wichtig · Fallstricke

Experimentell und kaum verbreitet: Das Ereignis gibt es praktisch nur in Chromium-Browsern mit WebXR-DOM-Overlay-Unterstützung, vor allem in Chrome für Android mit ARCore. Firefox und Safari unterstützen es nicht. Vorab mit 'onbeforexrselect' in HTMLElement.prototype prüfen, ob es verfügbar ist.
Ausgelöst wird es nur in einer aktiven XR-Sitzung mit domOverlay. Das Feature 'dom-overlay' muss in optionalFeatures oder requiredFeatures angefordert werden.
WebXR braucht einen sicheren Kontext (HTTPS) und eine Nutzeraktion (z. B. einen Klick), um die Sitzung zu starten.
preventDefault() unterdrückt nur die XR-Ereignisse selectstart, select und selectend. DOM-Ereignisse wie click und pointerdown kommen weiterhin an. Auch die Squeeze-Ereignisse (squeeze*) sind davon nicht betroffen.
Das Ereignis steigt auf. Wird es in einem inneren Element mit stopPropagation() angehalten, erreicht es einen Listener auf dem Container nicht mehr. Die Unterdrückung hängt aber allein von preventDefault() ab.
Mit passive: true registrierte Listener können das Ereignis nicht abbrechen.

Siehe auch

XRSession XRSession.domOverlayState XRSessionEvent Event.preventDefault() Element: beforeinput