DeviceOrientationEvent — Schnittstelle · JavaScript-Referenz

Signatur

interface DeviceOrientationEvent extends Event

Beschreibung

Das Interface DeviceOrientationEvent gehört zur Spezifikation Device Orientation Events. Darüber erfährt eine Webseite, wie das Gerät im Raum ausgerichtet ist. Die Werte stammen aus Sensoren wie Gyroskop, Beschleunigungsmesser und Magnetometer. Der Browser löst das Event deviceorientation auf window aus, sobald sich die Ausrichtung spürbar ändert.

Die Ausrichtung wird durch drei Winkel in Grad beschrieben:

alpha: Drehung um die z-Achse (Kompassrichtung), 0 bis 360.
beta: Neigung nach vorn oder hinten um die x-Achse, −180 bis 180.
gamma: Neigung nach links oder rechts um die y-Achse, −90 bis 90.

Die Eigenschaft absolute gibt an, ob sich die Werte auf das Koordinatensystem der Erde beziehen (magnetischer Norden, Schwerkraft) oder auf einen beliebigen Bezugsrahmen des Geräts. Absolute Werte liefert das separate Event deviceorientationabsolute (Chromium). Safari stellt stattdessen die nicht standardisierte Eigenschaft webkitCompassHeading bereit.

Typische Einsatzgebiete sind Neigungssteuerungen in Spielen, Kompass- und AR-Anwendungen, Parallax-Effekte und 360°-Panoramen. Wenn du Beschleunigung oder Drehgeschwindigkeit brauchst, nimm stattdessen DeviceMotionEvent.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Events, meist `"deviceorientation"` oder `"deviceorientationabsolute"` (nur beim Konstruktor `new DeviceOrientationEvent(type, options)`).
$options.alpha	number \| null	null	Drehung um die z-Achse in Grad (0 bis 360).
$options.beta	number \| null	null	Drehung um die x-Achse in Grad (−180 bis 180).
$options.gamma	number \| null	null	Drehung um die y-Achse in Grad (−90 bis 90).
$options.absolute	boolean	false	`true`, wenn sich die Werte auf das Koordinatensystem der Erde beziehen.

Rückgabewert

Typ

DeviceOrientationEvent

Beschreibung

Das Event-Objekt mit den schreibgeschützten Eigenschaften alpha, beta, gamma (jeweils number | null) und absolute (boolean). Außerdem gibt es die statische Methode DeviceOrientationEvent.requestPermission() (nur Safari), die ein Promise<"granted" | "denied"> zurückgibt.

Beispiele

Ausrichtung per addEventListener auslesen

const handleOrientation = (event) => {
  const { alpha, beta, gamma, absolute } = event;
  console.log(`alpha: ${alpha?.toFixed(1)}°, beta: ${beta?.toFixed(1)}°, gamma: ${gamma?.toFixed(1)}°, absolut: ${absolute}`);
};

window.addEventListener('deviceorientation', handleOrientation);

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

alpha: 123.4°, beta: 12.7°, gamma: -5.3°, absolut: false

Berechtigung auf iOS anfragen (nur nach Nutzeraktion)

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

startButton.addEventListener('click', async () => {
  // Safari ab iOS 13 verlangt eine ausdrückliche Zustimmung
  if (typeof DeviceOrientationEvent.requestPermission === 'function') {
    try {
      const state = await DeviceOrientationEvent.requestPermission();
      if (state !== 'granted') {
        console.warn('Zugriff auf den Sensor verweigert');
        return;
      }
    } catch (err) {
      console.error('Anfrage fehlgeschlagen:', err);
      return;
    }
  }
  window.addEventListener('deviceorientation', (e) => {
    console.log('beta:', e.beta);
  });
});

beta: 34.2

Kugel per Neigung bewegen (Spielsteuerung)

const ball = document.querySelector('#ball');
const garden = document.querySelector('#garden');
const maxX = garden.clientWidth - ball.clientWidth;
const maxY = garden.clientHeight - ball.clientHeight;

window.ondeviceorientation = ({ beta, gamma }) => {
  if (beta === null || gamma === null) return; // kein Sensor
  // beta auf [-90, 90] begrenzen, damit das Gerät nicht "überkippt"
  const x = Math.min(Math.max(beta, -90), 90) + 90;  // 0..180
  const y = gamma + 90;                             // 0..180
  ball.style.transform = `translate(${(maxY * y) / 180}px, ${(maxX * x) / 180}px)`;
};

// Abmelden über die on-Property:
// window.ondeviceorientation = null;

Kompassrichtung browserübergreifend ermitteln

const onHeading = (event) => {
  // Safari: webkitCompassHeading; Chromium: absolute alpha
  const heading = event.webkitCompassHeading ?? (event.absolute ? 360 - event.alpha : null);
  if (heading != null) {
    console.log(`Richtung: ${Math.round(heading)}°`);
  }
};

const eventName = 'ondeviceorientationabsolute' in window
  ? 'deviceorientationabsolute'
  : 'deviceorientation';

window.addEventListener(eventName, onHeading);

Richtung: 272°

// Wichtig · Fallstricke

Nur in sicheren Kontexten: Moderne Browser lösen das Event nur auf HTTPS-Seiten (oder localhost) aus. In iframes muss die Permissions-Policy accelerometer, gyroscope bzw. magnetometer erlaubt sein.
iOS/Safari: Ab iOS 13 musst du DeviceOrientationEvent.requestPermission() aufrufen, und zwar innerhalb einer Nutzeraktion wie click. Sonst schlägt der Aufruf fehl und es kommen keine Events an.
Werte können null sein: Desktop-Geräte ohne Sensor lösen das Event oft einmalig mit null-Werten aus oder gar nicht. Prüfe die Werte deshalb immer, bevor du sie verwendest.
Relativ oder absolut: alpha ist bei absolute === false kein Kompasswert. Für eine echte Himmelsrichtung nutzt du deviceorientationabsolute (Chromium) oder webkitCompassHeading (Safari).
Performance: Das Event feuert sehr häufig, oft mit 60 Hz. Aufwendige DOM-Änderungen solltest du über requestAnimationFrame bündeln und den Handler mit removeEventListener abmelden, sobald du ihn nicht mehr brauchst. Das schont auch den Akku.
Datenschutz: Sensordaten eignen sich für Fingerprinting. Einige Browser runden die Werte deshalb oder drosseln die Häufigkeit.
Die Achsen hängen von der Bildschirmausrichtung ab. Bei Querformat solltest du screen.orientation.angle einrechnen.

Siehe auch

DeviceMotionEventAcceleration DeviceMotionEvent MIDIConnectionEvent HIDConnectionEvent NotificationEvent