new DeviceOrientationEvent() — Methode · JavaScript-Referenz

Signatur

new DeviceOrientationEvent(type, options)

Beschreibung

Der Konstruktor DeviceOrientationEvent() erstellt ein synthetisches Ereignis vom Typ DeviceOrientationEvent. Normalerweise erzeugt der Browser solche Ereignisse selbst, wenn sich die Ausrichtung des Geräts ändert, und sendet sie als deviceorientation oder deviceorientationabsolute an window.

Den Konstruktor braucht man vor allem für Tests, Simulationen und Desktop-Fallbacks: So lässt sich Code prüfen, der auf die Winkel alpha (Drehung um die z-Achse, 0–360°), beta (Neigung vorn/hinten, −180–180°) und gamma (Neigung links/rechts, −90–90°) reagiert, ohne dass ein echtes Mobilgerät bewegt werden muss.

Das erzeugte Ereignis wird mit dispatchEvent() ausgelöst. Seine Eigenschaft isTrusted ist dabei immer false. Code, der echte Benutzereingaben voraussetzt, kann das also unterscheiden.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses, üblicherweise `"deviceorientation"` oder `"deviceorientationabsolute"`. Groß- und Kleinschreibung wird beachtet.
$options	object	{}	Optionales Objekt, das zusätzlich zu den `Event`-Optionen (`bubbles`, `cancelable`, `composed`) folgende Felder annimmt: `alpha` (`number \| null`, Standard `null`): Drehung um die z-Achse in Grad (0 bis 360) `beta` (`number \| null`, Standard `null`): Drehung um die x-Achse in Grad (−180 bis 180) `gamma` (`number \| null`, Standard `null`): Drehung um die y-Achse in Grad (−90 bis 90) `absolute` (`boolean`, Standard `false`): `true`, wenn sich die Werte auf das Koordinatensystem der Erde beziehen (magnetischer Norden)

Rückgabewert

Typ

DeviceOrientationEvent

Beschreibung

Ein neues DeviceOrientationEvent-Objekt mit den übergebenen Werten. Nicht angegebene Winkel sind null.

Beispiele

Ereignis erzeugen und Eigenschaften auslesen

const event = new DeviceOrientationEvent('deviceorientation', {
  alpha: 90,
  beta: 45,
  gamma: -10,
  absolute: false
});

console.log(event.type, event.alpha, event.beta, event.gamma, event.absolute);
console.log(event.isTrusted);

deviceorientation 90 45 -10 false false

Neigungssteuerung am Desktop simulieren

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

const handleOrientation = ({ beta, gamma }) => {
  if (beta === null || gamma === null) return;
  // Neigung in Pixelverschiebung umrechnen
  ball.style.transform = `translate(${gamma * 2}px, ${beta * 2}px)`;
  console.log(`beta=${beta}, gamma=${gamma}`);
};

window.addEventListener('deviceorientation', handleOrientation);

// Pfeiltasten simulieren die Geräteneigung
let sim = { beta: 0, gamma: 0 };
document.addEventListener('keydown', (e) => {
  if (e.key === 'ArrowUp') sim.beta -= 5;
  if (e.key === 'ArrowDown') sim.beta += 5;
  if (e.key === 'ArrowLeft') sim.gamma -= 5;
  if (e.key === 'ArrowRight') sim.gamma += 5;
  window.dispatchEvent(new DeviceOrientationEvent('deviceorientation', sim));
});

beta=5, gamma=0 (nach Drücken von Pfeil nach unten)

Unit-Test für einen Orientierungs-Handler

const getDirection = (event) => {
  if (event.gamma === null) return 'unbekannt';
  if (event.gamma > 15) return 'rechts';
  if (event.gamma < -15) return 'links';
  return 'gerade';
};

const cases = [30, -20, 0, null];
for (const gamma of cases) {
  const ev = new DeviceOrientationEvent('deviceorientation', { gamma });
  console.log(gamma, '->', getDirection(ev));
}

30 -> rechts -20 -> links 0 -> gerade null -> unbekannt

// Wichtig · Fallstricke

Kein Zugriff auf echte Sensoren: Der Konstruktor erzeugt nur ein Datenobjekt. Er fragt keine Sensordaten ab und löst auch keine Berechtigungsanfrage aus.
iOS-Berechtigung: Seit iOS 13 müssen echte Ereignisse über DeviceOrientationEvent.requestPermission() (statisch, nur in Safari) nach einer Benutzeraktion freigeschaltet werden. Prüfe vorher, ob die Methode existiert: typeof DeviceOrientationEvent.requestPermission === 'function'.
Sicherer Kontext: Echte Orientierungsereignisse werden in modernen Browsern nur über HTTPS geliefert. Außerdem können sie per Permissions-Policy eingeschränkt sein, etwa in iframes.
isTrusted ist bei synthetischen Ereignissen immer false.
Werte außerhalb der dokumentierten Bereiche werden nicht abgeschnitten. Prüfe sie also selbst.
Die Unterstützung von deviceorientationabsolute ist in den Browsern uneinheitlich: Chrome unterstützt es, Safari und Firefox nicht bzw. nur eingeschränkt.
In Node.js gibt es diesen Konstruktor nicht. Für Tests brauchst du eine Browser-Umgebung oder ein eigenes Polyfill, denn jsdom liefert ihn standardmäßig nicht mit.

Siehe auch

new Event() new AbsoluteOrientationSensor() new DeviceMotionEvent() new MIDIConnectionEvent() new HIDConnectionEvent()