Screen: orientationchange — Ereignis · JavaScript-Referenz

Signatur

screen.addEventListener("orientationchange", handler)

Beschreibung

Das Ereignis orientationchange am Screen-Objekt gehörte zu einem frühen Entwurf der Screen Orientation API. Es wird ausgelöst, wenn das Gerät zwischen Hoch- und Querformat wechselt. Den Handler registrieren Sie entweder mit screen.addEventListener("orientationchange", handler) oder über die Eigenschaft screen.onorientationchange.

Das Ereignis ist ein einfaches Event ohne zusätzliche Eigenschaften. Die neue Ausrichtung lesen Sie im Handler aus. Im alten Entwurf ging das über screen.orientation als String (z. B. "portrait-primary"), in der heutigen API über screen.orientation.type und screen.orientation.angle.

Für neuen Code sollten Sie dieses Ereignis nicht verwenden. Der Standardweg ist das Ereignis change an screen.orientation (Interface ScreenOrientation). Alternativ können Sie mit window.matchMedia("(orientation: portrait)") auf Änderungen der Ausrichtung reagieren. Das Ereignis wird hier nur dokumentiert, damit Sie Altcode verstehen und umstellen können.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"orientationchange"` (in alten Firefox-Versionen `"mozorientationchange"`).
$handler Pflicht	(event: Event) => void		Callback, das bei jeder Änderung der Ausrichtung aufgerufen wird. Es bekommt ein einfaches `Event`-Objekt.
$options	boolean \| AddEventListenerOptions	false	Optionale Listener-Optionen wie `once`, `passive` oder `signal`.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Die neue Ausrichtung lesen Sie im Handler aus screen.orientation.

Beispiele

Altcode: Listener am Screen-Objekt registrieren

// Nur zum Verständnis von Altcode – moderne Browser lösen dieses Ereignis nicht aus
const onOrientation = () => {
  const o = screen.orientation;
  // Alter Entwurf: String, neue API: Objekt mit .type
  const type = typeof o === 'string' ? o : o?.type;
  console.log('Neue Ausrichtung:', type);
};

if ('onorientationchange' in screen) {
  screen.addEventListener('orientationchange', onOrientation);
} else {
  console.log('Screen: orientationchange wird nicht unterstützt');
}

Screen: orientationchange wird nicht unterstützt

Über die on-Property registrieren und wieder entfernen

const handler = () => console.log('Ausrichtung geändert');

// Registrieren über die Eigenschaft
screen.onorientationchange = handler;

// Später wieder entfernen
screen.onorientationchange = null;

// Gleichwertig mit addEventListener/removeEventListener
screen.addEventListener('orientationchange', handler);
screen.removeEventListener('orientationchange', handler);

Moderner Ersatz mit Rückfallebene

const logOrientation = () => {
  const { type, angle } = screen.orientation ?? {};
  console.log(`Ausrichtung: ${type ?? 'unbekannt'} (${angle ?? '?'}°)`);
};

if (screen.orientation?.addEventListener) {
  // Standard: ScreenOrientation-change-Ereignis
  screen.orientation.addEventListener('change', logOrientation);
} else {
  // Rückfallebene: Media Query
  const mq = window.matchMedia('(orientation: portrait)');
  mq.addEventListener('change', (e) => {
    console.log(e.matches ? 'Hochformat' : 'Querformat');
  });
}

Ausrichtung: landscape-primary (90°)

Layout beim Wechsel der Ausrichtung anpassen

const controller = new AbortController();

const updateLayout = () => {
  const portrait = screen.orientation?.type.startsWith('portrait')
    ?? window.matchMedia('(orientation: portrait)').matches;
  document.body.classList.toggle('is-portrait', portrait);
  document.body.classList.toggle('is-landscape', !portrait);
};

screen.orientation?.addEventListener('change', updateLayout, { signal: controller.signal });
updateLayout();

// Alle Listener auf einmal entfernen, z. B. beim Verlassen der Ansicht
// controller.abort();

// Wichtig · Fallstricke

Veraltet und nicht standardisiert: Screen: orientationchange wurde nur in alten Firefox-Versionen unterstützt, teils mit dem Präfix mozorientationchange. Aktuelle Browser lösen es nicht aus. Verwenden Sie stattdessen screen.orientation.addEventListener("change", …). Das ist in allen modernen Browsern verfügbar, in Safari ab Version 16.4.
Nicht verwechseln mit window.onorientationchange: Das Ereignis orientationchange am window-Objekt ist ein anderes Ereignis. Es ist ebenfalls veraltet, wird aber vor allem von mobilen Browsern (iOS Safari, Android) noch unterstützt. Dort liefert window.orientation den Winkel (0, 90, -90, 180).
Unterschiedlicher Wert von screen.orientation: Im alten Entwurf war das ein String, heute ist es ein ScreenOrientation-Objekt. Altcode, der screen.orientation === "portrait-primary" vergleicht, funktioniert deshalb nicht mehr.
Zeitpunkt: Wenn das Ereignis ausgelöst wird, sind Viewport-Maße wie innerWidth nicht in jedem Browser schon aktualisiert. Für Layout-Berechnungen ist das Ereignis resize oder ein ResizeObserver oft zuverlässiger.
Auf Desktop-Geräten ohne Lagesensor wird das Ereignis in der Regel nie ausgelöst.

Siehe auch

Screen.orientation ScreenOrientation Window.matchMedia() ScreenOrientation.lock() Screen