ScreenOrientation: change — Ereignis · JavaScript-Referenz

Signatur

screen.orientation.addEventListener("change", handler)

Beschreibung

Das change-Ereignis der Schnittstelle ScreenOrientation wird ausgelöst, sobald sich die Ausrichtung des Bildschirms geändert hat. Das passiert zum Beispiel, wenn ein Nutzer sein Mobilgerät vom Hoch- ins Querformat dreht, oder wenn per screen.orientation.lock() eine andere Ausrichtung erzwungen wurde. Der Handler bekommt ein einfaches Event-Objekt ohne zusätzliche Eigenschaften. Die neue Ausrichtung liest man direkt aus screen.orientation.type (z. B. "portrait-primary", "landscape-secondary") und screen.orientation.angle (0, 90, 180 oder 270 Grad).

Registrieren kann man den Handler auf zwei Wegen:

screen.orientation.addEventListener("change", handler): Mehrere Handler sind möglich, und mit removeEventListener entfernt man sie wieder.
screen.orientation.onchange = handler: Hier gibt es nur einen einzigen Handler. Eine neue Zuweisung überschreibt den alten, und null entfernt ihn.

Typische Einsatzzwecke sind das Anpassen von Spiel- oder Canvas-Layouts, das Pausieren von Videos im Hochformat, Hinweise wie „Bitte Gerät drehen“ und das Neuberechnen von Maßen, die sich mit reinem CSS nicht ausdrücken lassen. Für reine Layout-Änderungen reicht oft die CSS-Media-Query @media (orientation: landscape) oder matchMedia().

Das Ereignis ersetzt das veraltete window.onorientationchange und die Eigenschaft window.orientation. Neuer Code sollte nur noch die ScreenOrientation-API verwenden.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses, hier immer `"change"`.
$handler Pflicht	(event: Event) => void		Callback-Funktion, die bei jeder Änderung der Ausrichtung aufgerufen wird. `event.target` ist das `ScreenOrientation`-Objekt.
$options	boolean \| AddEventListenerOptions	false	Optionale Listener-Optionen wie `once` oder `signal` (zum Entfernen über einen `AbortController`).

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Der Handler erhält ein generisches Event-Objekt.

Beispiele

Ausrichtung mit addEventListener überwachen

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

// Beim Start einmal ausgeben, danach bei jeder Änderung
logOrientation();
screen.orientation.addEventListener("change", logOrientation);

Ausrichtung: portrait-primary, Winkel: 0° // nach Drehen des Geräts: Ausrichtung: landscape-primary, Winkel: 90°

Hinweis „Bitte Gerät drehen“ für ein Querformat-Spiel

const hint = document.querySelector("#rotate-hint");

const updateHint = () => {
  const isPortrait = screen.orientation.type.startsWith("portrait");
  hint.hidden = !isPortrait;
};

updateHint();
screen.orientation.onchange = updateHint;

// Handler später wieder entfernen
// screen.orientation.onchange = null;

Listener mit AbortController aufräumen

const controller = new AbortController();
const canvas = document.querySelector("canvas");

const resizeCanvas = () => {
  canvas.width = window.innerWidth;
  canvas.height = window.innerHeight;
  console.log(`Canvas neu: ${canvas.width}×${canvas.height}`);
};

screen.orientation.addEventListener("change", resizeCanvas, {
  signal: controller.signal,
});

// z. B. beim Verlassen der Spielansicht:
const stopGame = () => controller.abort(); // entfernt den Listener

Canvas neu: 844×390

removeEventListener mit benannter Funktion

const onChange = (event) => {
  console.log("Neue Ausrichtung:", event.target.type);
  if (event.target.type.startsWith("landscape")) {
    // nur auf die erste Drehung ins Querformat reagieren
    screen.orientation.removeEventListener("change", onChange);
  }
};

screen.orientation.addEventListener("change", onChange);

Neue Ausrichtung: landscape-primary

// Wichtig · Fallstricke

Browser-Unterstützung: Chrome, Edge und Firefox unterstützen das Ereignis seit Langem, Safari erst ab Version 16.4 (macOS und iOS). Für ältere iOS-Versionen braucht man als Ersatz window.addEventListener("orientationchange", …) oder matchMedia("(orientation: portrait)"). Vorher prüfen: if ("orientation" in screen) { … }.
Maße zum Zeitpunkt des Ereignisses: Je nach Browser sind window.innerWidth und innerHeight beim Auslösen noch nicht aktualisiert. Für Layout-Berechnungen ist das resize-Ereignis auf window oder ein ResizeObserver oft zuverlässiger, alternativ wartet man mit requestAnimationFrame einen Frame ab.
Keine Ereignisdaten: Das Event-Objekt enthält keine Ausrichtungsinformationen. Die Werte liest man immer aus screen.orientation.type und angle.
Desktop: Auf Desktop-Rechnern wird das Ereignis meist nie ausgelöst. Ausnahmen sind drehbare Monitore und die Geräte-Emulation in den Entwicklerwerkzeugen.
Veraltete API: window.orientation und das Ereignis orientationchange auf window sind veraltet und sollten in neuem Code nicht mehr verwendet werden.
lock(): Auch eine programmatische Änderung per screen.orientation.lock() löst change aus. Viele Browser erlauben lock() allerdings nur im Vollbildmodus.

Siehe auch

Screen: orientationchange Window: orientationchange NetworkInformation: change Screen: change CookieStore: change