ScreenDetails: currentscreenchange — Ereignis · JavaScript-Referenz

Signatur

screenDetails.addEventListener("currentscreenchange", handler)

Beschreibung

Das Ereignis currentscreenchange gehört zur Window Management API (früher „Multi-Screen Window Placement“). Es wird auf dem ScreenDetails-Objekt ausgelöst, das man über window.getScreenDetails() erhält, sobald sich ScreenDetails.currentScreen ändert. Das passiert in zwei Fällen:

Das Browserfenster wird auf einen anderen Bildschirm verschoben, und currentScreen zeigt danach auf ein anderes ScreenDetailed-Objekt.
Eine oder mehrere Eigenschaften des aktuellen Bildschirms ändern sich, z. B. width, height, availWidth, availHeight, colorDepth, orientation, left, top, availLeft, availTop, devicePixelRatio, label, isPrimary oder isInternal.

Typische Einsatzfälle sind Präsentations-, Trading- oder Dashboard-Anwendungen, die ihr Layout, die Auflösung von Canvas-Grafiken oder die Platzierung weiterer Fenster anpassen, sobald der Nutzer das Fenster auf einen anderen Monitor zieht oder sich Skalierung bzw. Auflösung ändern.

Das Ereignis ist ein einfaches Event ohne zusätzliche Eigenschaften. Die neuen Werte liest man direkt aus screenDetails.currentScreen ab. Registrieren lässt sich der Handler per addEventListener("currentscreenchange", …) oder über die Eigenschaft screenDetails.oncurrentscreenchange.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"currentscreenchange"`.
$handler Pflicht	(event: Event) => void		Callback, der bei jeder Änderung von `currentScreen` aufgerufen wird. Er bekommt ein einfaches `Event`, dessen `target` das `ScreenDetails`-Objekt ist.
$options	boolean \| AddEventListenerOptions	false	Übliche Listener-Optionen wie `once` oder `signal` (zum Entfernen per `AbortController`).

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Der Handler bekommt ein Event-Objekt; die aktuellen Bildschirmdaten stehen in screenDetails.currentScreen (ScreenDetailed).

Beispiele

Monitorwechsel mit addEventListener erkennen

const initScreenWatcher = async () => {
  if (!('getScreenDetails' in window)) {
    console.warn('Window Management API wird nicht unterstützt');
    return;
  }

  // Fragt beim ersten Aufruf nach der Berechtigung "window-management"
  const screenDetails = await window.getScreenDetails();
  let lastLabel = screenDetails.currentScreen.label;

  screenDetails.addEventListener('currentscreenchange', () => {
    const s = screenDetails.currentScreen;
    if (s.label !== lastLabel) {
      console.log(`Fenster auf "${s.label}" verschoben`);
      lastLabel = s.label;
    }
    console.log(`Auflösung: ${s.width}x${s.height}, DPR: ${s.devicePixelRatio}`);
  });
};

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

Fenster auf "DELL U2720Q" verschoben Auflösung: 2560x1440, DPR: 1.5

Canvas-Auflösung per on-Property anpassen

const canvas = document.querySelector('canvas');

const resizeCanvas = (dpr) => {
  const { clientWidth, clientHeight } = canvas;
  canvas.width = Math.round(clientWidth * dpr);
  canvas.height = Math.round(clientHeight * dpr);
  console.log(`Canvas neu skaliert für DPR ${dpr}`);
};

const screenDetails = await window.getScreenDetails();
resizeCanvas(screenDetails.currentScreen.devicePixelRatio);

// Alternative zu addEventListener: nur ein Handler möglich
screenDetails.oncurrentscreenchange = () => {
  resizeCanvas(screenDetails.currentScreen.devicePixelRatio);
};

Canvas neu skaliert für DPR 1 Canvas neu skaliert für DPR 2

Listener wieder entfernen (removeEventListener und AbortController)

const screenDetails = await window.getScreenDetails();

const onScreenChange = () => {
  console.log('Aktueller Bildschirm:', screenDetails.currentScreen.label);
};

screenDetails.addEventListener('currentscreenchange', onScreenChange);

// Später, z. B. beim Verlassen der Ansicht:
screenDetails.removeEventListener('currentscreenchange', onScreenChange);

// Oder mehrere Listener gesammelt per AbortController entfernen
const controller = new AbortController();
screenDetails.addEventListener('currentscreenchange', onScreenChange, {
  signal: controller.signal
});
controller.abort(); // entfernt den Listener

// Wichtig · Fallstricke

Browser-Unterstützung: Nur in Chromium-basierten Browsern (ab Version 100). Firefox und Safari unterstützen die Window Management API nicht – immer per 'getScreenDetails' in window prüfen.
Berechtigung: window.getScreenDetails() braucht die Berechtigung "window-management" (früher "window-placement") und einen sicheren Kontext (HTTPS). Der erste Aufruf sollte durch eine Nutzeraktion ausgelöst werden, damit die Berechtigungsabfrage erscheint. In iframes muss die Permissions-Policy window-management erlaubt sein.
Das Ereignis wird nicht auf window.screen ausgelöst, sondern nur auf dem ScreenDetails-Objekt. Für Änderungen an der Menge angeschlossener Bildschirme gibt es das separate Ereignis screenschange, für Änderungen an einem einzelnen Bildschirm das change-Ereignis auf Screen/ScreenDetailed.
Das Ereignis kann bei schrittweisem Verschieben oder Skalieren mehrfach kurz hintereinander feuern. Aufwendige Neuberechnungen deshalb entprellen (Debounce) oder mit requestAnimationFrame bündeln.
Das Event-Objekt enthält keine Detaildaten. Welche Eigenschaft sich geändert hat, muss man selbst durch Vergleich mit gespeicherten Werten ermitteln.

Siehe auch

Screen: change ScreenDetails: screenschange Screen: orientationchange Document: fullscreenchange Element: fullscreenchange