Screen: change — Ereignis · JavaScript-Referenz

Signatur

screen.addEventListener("change", handler)

Beschreibung

Das change-Ereignis gehört zur Window Management API. Es wird auf einem bestimmten Screen-Objekt ausgelöst, sobald sich eine oder mehrere seiner Eigenschaften ändern: width, height, availWidth, availHeight, colorDepth oder orientation. Bei ScreenDetailed-Objekten (aus window.getScreenDetails()) lösen außerdem Änderungen an left, top, availLeft, availTop, devicePixelRatio, label, isPrimary und isInternal das Ereignis aus.

Du registrierst den Handler entweder mit screen.addEventListener("change", handler) oder über die Eigenschaft screen.onchange = handler. Das Ereignisobjekt ist ein einfaches Event ohne zusätzliche Eigenschaften. Die neuen Werte liest du deshalb direkt vom Bildschirmobjekt (event.target) ab.

Typische Anwendungsfälle sind Mehrfenster-Anwendungen wie Trading-Dashboards, Präsentations- oder Grafiksoftware. Diese müssen ihre Fensteranordnung anpassen, wenn der Nutzer die Auflösung ändert, die Taskleiste verschiebt, die Skalierung umstellt oder den Bildschirm dreht. Anders als resize auf window bezieht sich das Ereignis auf den physischen Bildschirm und nicht auf den Viewport.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname, immer `"change"`.
$handler Pflicht	(event: Event) => void		Callback, der beim Ereignis aufgerufen wird. `event.target` ist das geänderte `Screen`- bzw. `ScreenDetailed`-Objekt.
$options	boolean \| AddEventListenerOptions	false	Optionale Listener-Optionen wie `once` oder `signal` (`AbortSignal` zum Entfernen).

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Der Handler erhält ein Event-Objekt ohne zusätzliche Daten.

Beispiele

Änderungen am aktuellen Bildschirm protokollieren

const logScreen = (event) => {
  const s = event.target;
  console.log(`Bildschirm: ${s.width}×${s.height}, verfügbar: ${s.availWidth}×${s.availHeight}, Farbtiefe: ${s.colorDepth}`);
};

if ('onchange' in window.screen) {
  window.screen.addEventListener('change', logScreen);
} else {
  console.log('Screen-change wird nicht unterstützt');
}

Bildschirm: 2560×1440, verfügbar: 2560×1400, Farbtiefe: 24

Über die onchange-Eigenschaft und wieder entfernen

window.screen.onchange = () => {
  console.log('Neue Ausrichtung:', screen.orientation.type);
};

// Später: Handler entfernen
window.screen.onchange = null;

Neue Ausrichtung: portrait-primary

Alle Bildschirme mit getScreenDetails() überwachen

const watchAllScreens = async () => {
  // Fragt die Berechtigung "window-management" ab
  const details = await window.getScreenDetails();

  const onScreenChange = (event) => {
    const s = event.target;
    console.log(`${s.label}: ${s.width}×${s.height} @ ${s.devicePixelRatio}x, Position ${s.left}/${s.top}`);
  };

  const attach = (s) => s.addEventListener('change', onScreenChange);
  details.screens.forEach(attach);

  // Neu angeschlossene Bildschirme ebenfalls überwachen
  details.addEventListener('screenschange', () => {
    details.screens.forEach(attach); // doppelte Registrierung derselben Funktion ist wirkungslos
  });
};

document.querySelector('#start').addEventListener('click', watchAllScreens);

DELL U2720Q: 3840×2160 @ 1.5x, Position 1920/0

Listener per AbortController aufräumen

const controller = new AbortController();

screen.addEventListener('change', () => {
  console.log('Verfügbare Höhe jetzt:', screen.availHeight);
}, { signal: controller.signal });

// Beim Verlassen der Ansicht
controller.abort();

Verfügbare Höhe jetzt: 1400

// Wichtig · Fallstricke

Kompatibilität: Experimentell und nur in Chromium-Browsern (ab Version 100) verfügbar. Firefox und Safari unterstützen das Ereignis nicht. Prüfe die Unterstützung mit 'onchange' in screen.
Sicherer Kontext: Die API steht nur über HTTPS (oder localhost) zur Verfügung.
Berechtigung: Für getScreenDetails() muss der Nutzer die Berechtigung window-management erteilen, und der Aufruf erfordert in der Regel eine Nutzerinteraktion. In iframes muss zusätzlich die Permissions-Policy window-management erlaubt sein.
Das Ereignis liefert keine Angaben dazu, welche Eigenschaft sich geändert hat. Speichere bei Bedarf die alten Werte selbst und vergleiche sie.
Für Änderungen am Viewport ist window-resize das richtige Ereignis, für reine Drehungen screen.orientation-change. Das Hinzufügen oder Entfernen ganzer Bildschirme meldet screenschange auf ScreenDetails.
Datenschutz: Bildschirmdaten eignen sich zum Fingerprinting. Frage die Berechtigung deshalb nur an, wenn sie wirklich gebraucht wird.

Siehe auch

Screen Window: resize Window.screen Screen: orientationchange HTMLElement: change