DeviceOrientationEvent.alpha — Eigenschaft · JavaScript-Referenz

Signatur

DeviceOrientationEvent.alpha

Beschreibung

Die schreibgeschützte Eigenschaft alpha eines DeviceOrientationEvent gibt an, wie weit das Gerät um seine Z-Achse gedreht ist. Die Z-Achse steht senkrecht auf dem Bildschirm. Liegt das Gerät flach auf dem Tisch und drehen Sie es wie einen Drehteller, ändert sich alpha. Der Wert liegt in Grad im Bereich 0 (einschließlich) bis 360 (ausschließlich).

Wie der Wert zu deuten ist, hängt von event.absolute ab. Ist die Eigenschaft true, bezieht sich alpha auf das Erdkoordinatensystem, und 0 entspricht dann in etwa der Ausrichtung des Geräteoberrands nach Norden. Bei false ist der Bezugspunkt beliebig, meist die Ausrichtung beim Start der Messung. Die Werte eignen sich dann nur für relative Drehungen. Für echte Kompass-Anwendungen gibt es das Ereignis deviceorientationabsolute (Chromium) oder unter iOS/Safari die Eigenschaft webkitCompassHeading.

Typische Einsatzgebiete sind Kompass-Anzeigen, AR- und 360°-Ansichten, Spiele mit Bewegungssteuerung und Parallax-Effekte. alpha wird fast immer zusammen mit beta (Neigung um die X-Achse) und gamma (Neigung um die Y-Achse) ausgewertet.

Rückgabewert

Typ

number | null

Beschreibung

Drehwinkel um die Z-Achse in Grad, von 0 bis unter 360. null, wenn das Gerät keine Orientierungsdaten liefern kann (z. B. Desktop ohne Sensor).

Beispiele

alpha per addEventListener auslesen

const handleOrientation = (event) => {
  const { alpha, absolute } = event;
  if (alpha === null) {
    console.log('Keine Orientierungsdaten verfügbar');
    return;
  }
  console.log(`Drehung um Z: ${alpha.toFixed(1)}° (absolut: ${absolute})`);
};

window.addEventListener('deviceorientation', handleOrientation);

// Später wieder abmelden, z. B. beim Verlassen der Ansicht
// window.removeEventListener('deviceorientation', handleOrientation);

Drehung um Z: 127.4° (absolut: false)

Berechtigung unter iOS 13+ anfordern (per Klick)

const button = document.querySelector('#start-sensor');

button.addEventListener('click', async () => {
  // iOS verlangt eine ausdrückliche Erlaubnis nach einer Nutzeraktion
  if (typeof DeviceOrientationEvent?.requestPermission === 'function') {
    const state = await DeviceOrientationEvent.requestPermission();
    if (state !== 'granted') {
      console.log('Zugriff verweigert');
      return;
    }
  }
  window.ondeviceorientation = (event) => {
    console.log('alpha:', event.alpha);
  };
});

alpha: 42.87

Einfache Kompassnadel mit absoluter Ausrichtung

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

const updateCompass = (event) => {
  // Safari (iOS): webkitCompassHeading ist bereits im Uhrzeigersinn ab Norden
  let heading;
  if (typeof event.webkitCompassHeading === 'number') {
    heading = event.webkitCompassHeading;
  } else if (event.absolute && event.alpha !== null) {
    // alpha dreht gegen den Uhrzeigersinn -> für Kompassrichtung umrechnen
    heading = (360 - event.alpha) % 360;
  } else {
    return;
  }
  needle.style.transform = `rotate(${-heading}deg)`;
  needle.title = `${Math.round(heading)}°`;
};

// Chromium liefert absolute Werte über ein eigenes Ereignis
const eventName = 'ondeviceorientationabsolute' in window
  ? 'deviceorientationabsolute'
  : 'deviceorientation';

window.addEventListener(eventName, updateCompass);

// Wichtig · Fallstricke

Sicherer Kontext nötig: Das Ereignis wird nur über HTTPS (oder localhost) ausgelöst. In iframes kann es zusätzlich über die Permissions-Policy accelerometer/gyroscope/magnetometer eingeschränkt sein.
iOS 13+: Vor dem Zugriff muss DeviceOrientationEvent.requestPermission() aufgerufen werden, und zwar innerhalb einer Nutzeraktion (z. B. eines Klicks). Ohne diese Erlaubnis kommen keine Ereignisse an.
null prüfen: Auf Desktop-Rechnern ohne Sensor wird das Ereignis teilweise trotzdem einmal ausgelöst, mit alpha === null.
Relativ oder absolut: Ist absolute gleich false, entspricht alpha = 0 nicht der Nordrichtung. alpha wächst gegen den Uhrzeigersinn, eine Kompassrichtung erhalten Sie mit 360 - alpha.
Übergang bei 0/360: Beim Glätten oder Animieren den Sprung von 359° auf 0° berücksichtigen, sonst dreht sich die Anzeige einmal ganz herum.
Gimbal Lock: Steht beta nahe ±90°, werden alpha und gamma instabil. Für 3D-Anwendungen sind Quaternionen (z. B. AbsoluteOrientationSensor) robuster.
Leistung und Datenschutz: Das Ereignis feuert sehr häufig, deshalb aufwendige Arbeit drosseln oder mit requestAnimationFrame bündeln. Sensordaten eignen sich für Fingerprinting, daher Listener entfernen, wenn sie nicht mehr gebraucht werden.

Siehe auch

DeviceOrientationEvent.beta DeviceOrientationEvent.gamma DeviceOrientationEvent.absolute DeviceMotionEvent.interval DeviceMotionEventRotationRate.alpha