Window: deviceorientationabsolute — Ereignis · JavaScript-Referenz

Signatur

window.addEventListener("deviceorientationabsolute", handler)

Beschreibung

Das Ereignis deviceorientationabsolute liefert wie deviceorientation ein DeviceOrientationEvent mit den Winkeln alpha, beta und gamma. Der Unterschied: Die Werte beziehen sich immer auf das Erdkoordinatensystem, also auf den Norden und die Schwerkraft. event.absolute ist deshalb stets true. Beim normalen deviceorientation kann das Bezugssystem dagegen beliebig sein, zum Beispiel die Ausrichtung beim Laden der Seite.

Einsatzgebiete sind vor allem Kompass-Anwendungen, AR-Überlagerungen, Karten, die sich mit der Blickrichtung drehen, und Navigationshilfen. Zu diesen Werten gehören:

alpha (0–360°): Drehung um die z-Achse. Bei 0 zeigt die Oberkante des Geräts nach Norden; der Wert steigt gegen den Uhrzeigersinn.
beta (−180–180°): Neigung nach vorne oder hinten (x-Achse).
gamma (−90–90°): Neigung nach links oder rechts (y-Achse).

Man registriert das Ereignis mit window.addEventListener("deviceorientationabsolute", handler) oder über die Eigenschaft window.ondeviceorientationabsolute. Das Ereignis steigt nicht auf (bubbelt nicht) und lässt sich nicht abbrechen. Wenn das Gerät keinen Magnetometer hat, wird es nie ausgelöst oder liefert null-Werte.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"deviceorientationabsolute"`.
$handler Pflicht	(event: DeviceOrientationEvent) => void		Callback-Funktion. Erhält ein `DeviceOrientationEvent` mit `alpha`, `beta`, `gamma` (jeweils `number \| null`) und `absolute` (`true`).
$options	boolean \| AddEventListenerOptions	false	Optionen wie `{ once: true }`, `{ passive: true }` oder `{ signal }` zum Entfernen über einen `AbortController`.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Der Handler erhält ein DeviceOrientationEvent.

Beispiele

Einfacher Kompass mit addEventListener

const needle = document.querySelector('#nadel');

const onOrientation = (event) => {
  if (event.alpha === null) return; // kein Magnetometer
  // alpha steigt gegen den Uhrzeigersinn -> in Kompassrichtung umrechnen
  const heading = (360 - event.alpha) % 360;
  needle.style.transform = `rotate(${-heading}deg)`;
  console.log(`Richtung: ${Math.round(heading)}°`);
};

if ('ondeviceorientationabsolute' in window) {
  window.addEventListener('deviceorientationabsolute', onOrientation);
} else {
  console.warn('deviceorientationabsolute wird nicht unterstützt');
}

Richtung: 87°

Über die on-Property registrieren und mit removeEventListener wieder abmelden

// Variante 1: on-Property (überschreibt einen vorherigen Handler)
window.ondeviceorientationabsolute = (e) => {
  console.log(e.absolute, e.alpha?.toFixed(1));
};
// Abmelden:
window.ondeviceorientationabsolute = null;

// Variante 2: Sensor nur 10 Sekunden lang auswerten
const log = (e) => console.log('alpha:', e.alpha?.toFixed(1));
window.addEventListener('deviceorientationabsolute', log);
setTimeout(() => {
  window.removeEventListener('deviceorientationabsolute', log);
  console.log('Sensor-Auswertung beendet');
}, 10_000);

true 123.4 alpha: 123.4 ... Sensor-Auswertung beendet

Browserübergreifender Kompass mit Fallback für iOS/Safari

const showHeading = (deg) => {
  document.querySelector('#anzeige').textContent = `${Math.round(deg)}°`;
};

const startCompass = async () => {
  // iOS 13+: Berechtigung muss per Nutzeraktion angefragt werden
  if (typeof DeviceOrientationEvent?.requestPermission === 'function') {
    const state = await DeviceOrientationEvent.requestPermission();
    if (state !== 'granted') return;
  }

  if ('ondeviceorientationabsolute' in window) {
    // Chromium: absolute Werte
    window.addEventListener('deviceorientationabsolute', (e) => {
      if (e.alpha !== null) showHeading((360 - e.alpha) % 360);
    });
  } else {
    // Safari: webkitCompassHeading ist bereits die Kompassrichtung
    window.addEventListener('deviceorientation', (e) => {
      if (typeof e.webkitCompassHeading === 'number') {
        showHeading(e.webkitCompassHeading);
      } else if (e.absolute && e.alpha !== null) {
        showHeading((360 - e.alpha) % 360);
      }
    });
  }
};

document.querySelector('#start').addEventListener('click', startCompass);

// Wichtig · Fallstricke

Browser-Kompatibilität: Nur Chromium-Browser unterstützen das Ereignis (Chrome/Edge/Opera, vor allem auf Android). Firefox und Safari kennen es nicht. Safari liefert stattdessen webkitCompassHeading im deviceorientation-Ereignis. Prüfe die Unterstützung vor der Nutzung, zum Beispiel mit 'ondeviceorientationabsolute' in window.
Sicherer Kontext: Das Ereignis wird nur über HTTPS (oder localhost) ausgelöst. In iframes muss die Permissions-Policy die Sensoren freigeben (accelerometer, gyroscope, magnetometer).
Richtung von alpha: alpha steigt gegen den Uhrzeigersinn. Die übliche Kompassrichtung (im Uhrzeigersinn) ist 360 - alpha. Die Werte gelten für die natürliche Ausrichtung des Geräts. Bei Querformat musst du screen.orientation.angle einrechnen.
Magnetische Störungen: Metall, Magnete oder ein schlecht kalibrierter Sensor verfälschen den Wert. Er bezieht sich auf den magnetischen Norden, nicht auf den geografischen.
Leistung: Das Ereignis wird sehr oft ausgelöst (bis zu ca. 60 Hz). Aufwändige DOM-Änderungen solltest du mit requestAnimationFrame bündeln und den Listener entfernen, wenn du ihn nicht mehr brauchst. Das spart Akku.
Datenschutz: Sensordaten können für Fingerprinting missbraucht werden. Manche Browser runden die Werte deshalb oder sperren sie im Hintergrund.

Siehe auch

MIDIPort: statechange Window: deviceorientation Window: orientationchange Window: devicemotion Window: beforeinstallprompt