Window: orientationchange — Ereignis · JavaScript-Referenz

Signatur

window.addEventListener("orientationchange", handler)

Beschreibung

Das Event orientationchange wird am Window-Objekt ausgelöst, sobald jemand das Gerät dreht, also vom Hochformat ins Querformat wechselt oder umgekehrt. Den Handler registrieren Sie entweder mit window.addEventListener("orientationchange", handler) oder über die Eigenschaft window.onorientationchange. Das Event ist ein einfaches Event ohne zusätzliche Daten. Es kann nicht abgebrochen werden und steigt nicht im DOM auf (kein Bubbling).

Früher las man die neue Ausrichtung meist über die ebenfalls veraltete Eigenschaft window.orientation aus. Sie liefert den Winkel in Grad: 0, 90, -90 oder 180. Heute empfiehlt der Standard die Screen Orientation API: screen.orientation.type gibt die Ausrichtung als Text an (z. B. "portrait-primary") und screen.orientation.angle den Winkel. Das zugehörige change-Event an screen.orientation ersetzt orientationchange.

Das Event passt, wenn das Layout, ein Canvas, ein Video-Player oder eine Spielsteuerung auf das Drehen des Geräts reagieren soll. Für reine Layout-Anpassungen reichen meist CSS-Media-Queries (@media (orientation: landscape)) oder window.matchMedia(). Diese funktionieren auch auf dem Desktop.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Name des Events: `"orientationchange"`.
$handler Pflicht	(event: Event) => void		Die Rückruffunktion, die bei jeder Ausrichtungsänderung aufgerufen wird. Sie bekommt ein einfaches `Event`-Objekt ohne Ausrichtungsdaten.
$options	boolean \| AddEventListenerOptions	false	Optionale Einstellungen wie `{ once: true }`, `{ passive: true }` oder `{ signal }` zum Entfernen per `AbortController`.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Die Informationen zur neuen Ausrichtung holen Sie sich im Handler über screen.orientation oder, in älteren Browsern, über window.orientation.

Beispiele

Ausrichtungswechsel mit addEventListener erkennen

const logOrientation = () => {
  // Moderne API bevorzugen, sonst auf das veraltete window.orientation zurückgreifen
  const type = screen.orientation?.type ?? (Math.abs(window.orientation) === 90 ? 'landscape' : 'portrait');
  const angle = screen.orientation?.angle ?? window.orientation;
  console.log(`Neue Ausrichtung: ${type} (${angle}°)`);
};

window.addEventListener('orientationchange', logOrientation);

Neue Ausrichtung: landscape-primary (90°)

Handler per on-Property setzen und mit removeEventListener entfernen

// Variante 1: über die on-Property (ersetzt einen vorher gesetzten Handler)
window.onorientationchange = () => {
  document.body.classList.toggle('is-landscape', screen.orientation.type.startsWith('landscape'));
};

// Variante 2: einmalig reagieren und danach wieder abmelden
const hideRotateHint = () => {
  document.querySelector('#rotate-hint')?.remove();
  window.removeEventListener('orientationchange', hideRotateHint);
};
window.addEventListener('orientationchange', hideRotateHint);

Moderne Alternative mit Rückfall auf das alte Event

const updateCanvasSize = () => {
  const canvas = document.querySelector('canvas');
  canvas.width = window.innerWidth;
  canvas.height = window.innerHeight;
  console.log('Canvas angepasst:', canvas.width, 'x', canvas.height);
};

const controller = new AbortController();

if (screen.orientation && 'onchange' in screen.orientation) {
  screen.orientation.addEventListener('change', updateCanvasSize, { signal: controller.signal });
} else {
  window.addEventListener('orientationchange', updateCanvasSize, { signal: controller.signal });
}

// Später alle Listener auf einmal entfernen:
// controller.abort();

Canvas angepasst: 844 x 390

// Wichtig · Fallstricke

Veraltet: orientationchange und window.orientation gelten als deprecated. Nutzen Sie für neuen Code das change-Event von screen.orientation, das ab iOS Safari 16.4 überall unterstützt wird.
Browser-Kompatibilität: Das Event gibt es vor allem in mobilen Browsern (Safari auf iOS, Chrome/Samsung Internet auf Android). Desktop-Firefox und viele Desktop-Browser lösen es nicht aus. Prüfen Sie die Unterstützung mit 'onorientationchange' in window.
Zeitpunkt: Wenn das Event feuert, haben sich innerWidth/innerHeight in manchen Browsern (vor allem älteren iOS-Versionen) noch nicht geändert. Für Maß-Berechnungen ist das resize-Event zuverlässiger. Alternativ warten Sie im Handler mit requestAnimationFrame.
180°-Drehung: Dreht man das Gerät direkt vom Querformat links ins Querformat rechts, lösen manche Browser kein resize aus, wohl aber orientationchange.
Ist die Ausrichtung gesperrt (Systemeinstellung oder screen.orientation.lock()), wird das Event nicht ausgelöst.
Für reine Layout-Änderungen sind CSS-Media-Queries (orientation) oder matchMedia('(orientation: portrait)') meist die robustere Lösung.

Siehe auch

Window.orientation HTMLSlotElement: slotchange Window: rejectionhandled Window: hashchange Window: languagechange