DeviceOrientationEvent.gamma — Eigenschaft · JavaScript-Referenz

Signatur

DeviceOrientationEvent.gamma

Beschreibung

Die Eigenschaft gamma eines DeviceOrientationEvent gibt an, wie weit das Gerät um seine Y-Achse gedreht ist, also wie stark es nach links oder rechts gekippt wird. Der Wert liegt im Bereich [-90, 90) Grad. Positive Werte bedeuten, dass das Gerät nach rechts gekippt ist, negative Werte stehen für eine Neigung nach links. Liegt das Gerät flach auf dem Tisch, ist gamma ungefähr 0.

Zusammen mit alpha (Drehung um die Z-Achse, Kompassrichtung) und beta (Neigung vor/zurück um die X-Achse) beschreibt gamma die vollständige räumliche Ausrichtung des Geräts. Typische Einsatzgebiete sind Neigungssteuerung in Browserspielen (z. B. eine Kugel durch ein Labyrinth rollen), Parallax-Effekte, Wasserwaagen-Apps oder 360°-Panoramaansichten.

Man liest den Wert im Handler des Events deviceorientation aus, das über window.addEventListener("deviceorientation", handler) oder window.ondeviceorientation registriert wird. Kann der Browser keine Orientierungsdaten liefern, ist der Wert null – dies sollte immer geprüft werden.

Wichtig: Wird das Gerät so weit gekippt, dass beta über ±90° hinausgeht, springt gamma teilweise sprunghaft (Gimbal-Lock-Effekt der Euler-Winkel). Für robuste 3D-Berechnungen sind Quaternionen oder die Generic Sensor API (AbsoluteOrientationSensor) besser geeignet.

Rückgabewert

Typ

number | null

Beschreibung

Neigung um die Y-Achse in Grad im Bereich -90 bis 90 (Gleitkommazahl). null, wenn keine Sensordaten verfügbar sind.

Beispiele

Neigung links/rechts auslesen (addEventListener)

const handleOrientation = (event) => {
  const { gamma } = event;
  if (gamma === null) {
    console.log('Keine Orientierungsdaten verfügbar');
    return;
  }
  const richtung = gamma > 0 ? 'rechts' : gamma < 0 ? 'links' : 'gerade';
  console.log(`Gerät ist ${Math.abs(gamma).toFixed(1)}° nach ${richtung} gekippt`);
};

window.addEventListener('deviceorientation', handleOrientation);

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

Gerät ist 23.4° nach rechts gekippt

Kugel per Neigung bewegen (Spielsteuerung)

// HTML: <div id="feld" style="..."><div id="kugel"></div></div>
const feld = document.getElementById('feld');
const kugel = document.getElementById('kugel');

window.ondeviceorientation = ({ beta, gamma }) => {
  if (beta === null || gamma === null) return;

  // beta auf [-90, 90] begrenzen, um Überschlag zu vermeiden
  const x = gamma;                          // -90 .. 90
  const y = Math.max(-90, Math.min(90, beta));

  const maxX = feld.clientWidth - kugel.clientWidth;
  const maxY = feld.clientHeight - kugel.clientHeight;

  // Winkel auf 0..1 normieren und in Pixel umrechnen
  const left = ((x + 90) / 180) * maxX;
  const top = ((y + 90) / 180) * maxY;

  kugel.style.transform = `translate(${left}px, ${top}px)`;
};

Berechtigung auf iOS anfragen (Safari 13+)

const button = document.getElementById('start');

button.addEventListener('click', async () => {
  // iOS verlangt eine explizite Erlaubnis nach Nutzerinteraktion
  if (typeof DeviceOrientationEvent?.requestPermission === 'function') {
    const status = await DeviceOrientationEvent.requestPermission();
    if (status !== 'granted') {
      console.log('Zugriff verweigert');
      return;
    }
  }

  window.addEventListener('deviceorientation', (e) => {
    console.log('gamma:', e.gamma?.toFixed(2));
  });
});

gamma: -12.57

// Wichtig · Fallstricke

Wertebereich: Nur -90 bis 90 – anders als beta (-180 bis 180). Bei starker Vor-/Rückneigung (|beta| > 90°) kann gamma springen bzw. das Vorzeichen wechseln (Gimbal Lock).
null-Werte: Desktop-Browser ohne Sensor feuern das Event teils einmalig mit null-Werten oder gar nicht. Immer auf null prüfen.
Bildschirmausrichtung: Die Achsen beziehen sich auf das Gerät, nicht auf den Bildschirm. Im Querformat entspricht „links/rechts“ auf dem Bildschirm eher beta. Mit screen.orientation.angle korrigieren.
Sicherheit/Datenschutz: Nur in sicheren Kontexten (HTTPS) verfügbar. iOS Safari 13+ erfordert DeviceOrientationEvent.requestPermission() nach einer Nutzergeste. In iframes kann die Permissions-Policy (accelerometer, gyroscope) den Zugriff sperren. Sensordaten lassen sich für Fingerprinting missbrauchen.
Performance: Das Event feuert sehr häufig (bis ca. 60 Hz). Aufwendige DOM-Updates per requestAnimationFrame bündeln und Listener entfernen, wenn sie nicht gebraucht werden.

Siehe auch

DeviceMotionEventRotationRate.alpha DeviceOrientationEvent.alpha DeviceOrientationEvent.beta DeviceOrientationEvent.absolute CompositionEvent.data