Window: deviceorientation — Ereignis · JavaScript-Referenz

Signatur

window.addEventListener("deviceorientation", handler)

Beschreibung

Das Ereignis deviceorientation liefert die räumliche Ausrichtung des Geräts als DeviceOrientationEvent. Die drei Drehwinkel beschreiben die Lage des Geräts: alpha (Drehung um die Z-Achse, 0–360°, Kompassrichtung), beta (Neigung nach vorn/hinten um die X-Achse, −180° bis 180°) und gamma (Neigung nach links/rechts um die Y-Achse, −90° bis 90°).

Registriert wird das Ereignis entweder mit window.addEventListener("deviceorientation", handler) oder über die Eigenschaft window.ondeviceorientation. Typische Einsatzfälle sind Neigungssteuerung in Browserspielen, Parallax-Effekte, Kompass-Anzeigen, Panorama- und 360°-Ansichten sowie Augmented-Reality-Anwendungen.

Die Eigenschaft absolute gibt an, ob die Werte relativ zum Erdkoordinatensystem (magnetischer Norden) oder nur relativ zu einem beliebigen Ausgangszustand gemessen werden. Für echte Kompasswerte gibt es in Chromium-Browsern das eigene Ereignis deviceorientationabsolute, in Safari die Eigenschaft webkitCompassHeading.

Das Ereignis wird nur in einem sicheren Kontext (HTTPS) ausgelöst. Unter iOS 13+ muss zuerst eine Berechtigung per DeviceOrientationEvent.requestPermission() eingeholt werden, und dieser Aufruf muss aus einer Nutzeraktion heraus erfolgen (z. B. einem Klick).

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Ereignisname: `"deviceorientation"`.
$handler Pflicht	(event: DeviceOrientationEvent) => void		Callback, der ein `DeviceOrientationEvent` mit den Eigenschaften `alpha`, `beta`, `gamma` (jeweils `number \| null`) und `absolute` (`boolean`) bekommt.
$options	boolean \| AddEventListenerOptions	false	Optionale Listener-Optionen wie `{ passive: true }` oder `{ signal }` zum späteren Entfernen.

Rückgabewert

Typ

void

Beschreibung

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

Beispiele

Orientierung mit 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 wieder entfernen, z. B. beim Verlassen der Ansicht
// window.removeEventListener("deviceorientation", handleOrientation);

alpha: 312.4°, beta: 12.8°, gamma: -4.2°, absolut: false

Berechtigung unter iOS 13+ per Klick anfordern

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

const onOrientation = (event) => {
  document.querySelector("#anzeige").textContent =
    `Neigung: ${Math.round(event.beta ?? 0)}° / ${Math.round(event.gamma ?? 0)}°`;
};

startButton.addEventListener("click", async () => {
  if (typeof DeviceOrientationEvent?.requestPermission === "function") {
    try {
      const state = await DeviceOrientationEvent.requestPermission();
      if (state !== "granted") {
        console.warn("Zugriff auf Bewegungssensoren verweigert");
        return;
      }
    } catch (err) {
      console.error("Berechtigungsanfrage fehlgeschlagen:", err);
      return;
    }
  }
  window.addEventListener("deviceorientation", onOrientation);
});

Neigungssteuerung einer Kugel mit ondeviceorientation

const ball = document.querySelector("#ball");
const area = document.querySelector("#spielfeld");
let frameRequested = false;
let latest = { beta: 0, gamma: 0 };

window.ondeviceorientation = ({ beta, gamma }) => {
  if (beta === null || gamma === null) return; // kein Sensor
  // Werte begrenzen: beta auf [-90, 90]
  latest = { beta: Math.max(-90, Math.min(90, beta)), gamma };
  if (!frameRequested) {
    frameRequested = true;
    requestAnimationFrame(() => {
      const maxX = area.clientWidth - ball.clientWidth;
      const maxY = area.clientHeight - ball.clientHeight;
      const x = ((latest.gamma + 90) / 180) * maxX;
      const y = ((latest.beta + 90) / 180) * maxY;
      ball.style.transform = `translate(${x}px, ${y}px)`;
      frameRequested = false;
    });
  }
};

// Deaktivieren:
// window.ondeviceorientation = null;

Unterstützung prüfen und Listener per AbortController beenden

if (!("DeviceOrientationEvent" in window)) {
  console.log("DeviceOrientation wird nicht unterstützt");
} else {
  const controller = new AbortController();
  let received = false;

  window.addEventListener("deviceorientation", (e) => {
    if (e.alpha !== null) received = true;
  }, { signal: controller.signal });

  // Nach 2 Sekunden prüfen, ob echte Sensordaten kamen
  setTimeout(() => {
    console.log(received ? "Sensor aktiv" : "Kein Orientierungssensor gefunden");
    controller.abort(); // Listener entfernen
  }, 2000);
}

Kein Orientierungssensor gefunden

// Wichtig · Fallstricke

Nur über HTTPS: In unsicheren Kontexten wird das Ereignis nicht ausgelöst. In iframes muss zusätzlich die Permissions Policy (allow="accelerometer; gyroscope; magnetometer") den Zugriff erlauben.
iOS/Safari: Ab iOS 13 ist DeviceOrientationEvent.requestPermission() Pflicht, und zwar innerhalb einer Nutzeraktion. Ohne das kommen einfach keine Ereignisse an, eine Fehlermeldung gibt es nicht.
null-Werte: Auf Desktop-Rechnern ohne Sensor feuert das Ereignis unter Umständen einmal mit alpha/beta/gamma = null. Prüfe immer auf null, bevor du die Werte verwendest.
Relativ oder absolut: alpha ist oft relativ (absolute === false). Für Kompassrichtungen nimmst du deviceorientationabsolute (Chromium) oder event.webkitCompassHeading (Safari).
Bildschirmdrehung: Die Werte beziehen sich auf das Gerät, nicht auf den Bildschirm. Bei Querformat musst du sie mit screen.orientation.angle umrechnen.
Leistung und Akku: Das Ereignis feuert sehr oft (bis zu 60 Hz). Drossle DOM-Änderungen deshalb mit requestAnimationFrame und entferne den Listener, sobald du ihn nicht mehr brauchst.
Datenschutz: Mit Sensordaten lässt sich ein Gerät wiedererkennen (Fingerprinting). Manche Browser runden die Werte deshalb oder drosseln die Ereignisrate.
Für neue Projekte gibt es die modernere Generic Sensor API (AbsoluteOrientationSensor, RelativeOrientationSensor). Sie wird aber bisher nur von Chromium-Browsern unterstützt.

Siehe auch

Window: devicemotion Window: deviceorientationabsolute Window: beforeprint Window: orientationchange Window: unhandledrejection