DeviceOrientationEvent.beta — Eigenschaft · JavaScript-Referenz

Signatur

DeviceOrientationEvent.beta

Beschreibung

Die schreibgeschützte Eigenschaft beta eines DeviceOrientationEvent gibt an, wie weit das Gerät um seine X-Achse gedreht ist. Die X-Achse verläuft bei einem Smartphone im Hochformat von links nach rechts. Der Wert liegt im Bereich [-180, 180) Grad. 0 heißt: Das Gerät liegt flach mit dem Bildschirm nach oben. Positive Werte bedeuten, dass die Oberkante zum Nutzer hin angehoben wird. Bei 90 steht das Gerät senkrecht, bei ±180 liegt es mit dem Bildschirm nach unten.

Zusammen mit alpha (Drehung um die Z-Achse, wie bei einem Kompass) und gamma (seitliche Neigung um die Y-Achse) beschreibt beta die vollständige räumliche Lage des Geräts. Typische Einsatzgebiete sind Neigungssteuerung in Spielen, Parallax-Effekte, Wasserwaagen-Apps und AR- oder Panorama-Ansichten.

Den Wert liest du im Handler des Events deviceorientation auf window aus. Kann das Gerät die Ausrichtung nicht bestimmen (zum Beispiel ein Desktop ohne Sensor), ist beta null. Das musst du immer abfragen.

Rückgabewert

Typ

number | null

Beschreibung

Neigung um die X-Achse in Grad im Bereich -180 bis 180 (180 selbst ausgeschlossen). null, wenn kein Sensorwert verfügbar ist.

Beispiele

Neigung nach vorn/hinten anzeigen

const anzeige = document.querySelector('#beta');

const onOrientation = (event) => {
  if (event.beta === null) {
    anzeige.textContent = 'Kein Lagesensor verfügbar';
    return;
  }
  anzeige.textContent = `Neigung vorn/hinten: ${event.beta.toFixed(1)}°`;
};

window.addEventListener('deviceorientation', onOrientation);

Neigung vorn/hinten: 42.7°

Berechtigung auf iOS 13+ anfordern

const startButton = document.querySelector('#start');

const handler = (e) => console.log('beta:', e.beta);

startButton.addEventListener('click', async () => {
  // iOS Safari verlangt eine Nutzeraktion und explizite Zustimmung
  if (typeof DeviceOrientationEvent.requestPermission === 'function') {
    const status = await DeviceOrientationEvent.requestPermission();
    if (status !== 'granted') {
      console.warn('Zugriff auf Lagesensor verweigert');
      return;
    }
  }
  window.addEventListener('deviceorientation', handler);
});

beta: 12.34

Kugel per Neigung steuern (Wasserwaage/Spiel)

const ball = document.querySelector('#ball');
const MAX = 45; // Neigung auf ±45° begrenzen

const clamp = (v, min, max) => Math.min(Math.max(v, min), max);

window.ondeviceorientation = ({ beta, gamma }) => {
  if (beta === null || gamma === null) return;
  const y = clamp(beta, -MAX, MAX) / MAX;   // -1 … 1
  const x = clamp(gamma, -MAX, MAX) / MAX;  // -1 … 1
  ball.style.transform = `translate(${x * 100}px, ${y * 100}px)`;
};

// Aufräumen, z. B. beim Verlassen der Ansicht
const stop = () => { window.ondeviceorientation = null; };

// Wichtig · Fallstricke

Nur in sicherem Kontext: Das Event wird ausschließlich über HTTPS (oder localhost) ausgelöst. In iframes braucht es außerdem die Permissions-Policy accelerometer/gyroscope.
iOS Safari 13+: Du musst DeviceOrientationEvent.requestPermission() aus einer Nutzeraktion heraus aufrufen, sonst kommen keine Events an.
null prüfen: Desktop-Browser feuern das Event teils einmalig mit null-Werten, oder sie feuern es gar nicht.
Kardanische Blockade (Gimbal Lock): Steht das Gerät nahe ±90° senkrecht, werden alpha und gamma instabil und springen. Für präzise 3D-Anwendungen sind Quaternionen über die Generic Sensor API (AbsoluteOrientationSensor) besser geeignet.
Bildschirmdrehung: Die Werte beziehen sich auf das Gerätekoordinatensystem, nicht auf die aktuelle Bildschirmausrichtung. Im Querformat musst du die Achsen anhand von screen.orientation.angle umrechnen.
Performance: Das Event feuert sehr häufig (oft mit 60 Hz). Aufwändige DOM-Updates solltest du per requestAnimationFrame drosseln.
Datenschutz: Sensordaten lassen sich für Fingerprinting nutzen. Manche Browser runden die Werte deshalb oder schränken sie ein.

Siehe auch

DeviceMotionEventRotationRate.alpha DeviceOrientationEvent.alpha DeviceOrientationEvent.gamma DeviceOrientationEvent.absolute CompositionEvent.data