Window.getScreenDetails() — Methode · JavaScript-Referenz

Signatur

Window.prototype.getScreenDetails()

Beschreibung

window.getScreenDetails() gehört zur Window Management API. Anders als window.screen, das nur den aktuellen Bildschirm beschreibt, liefert die Methode Informationen über alle angeschlossenen Bildschirme: Position im virtuellen Gesamtbereich, Auflösung, verfügbare Fläche, Skalierungsfaktor (devicePixelRatio), Bezeichnung (label) sowie ob es der primäre oder der interne Bildschirm ist.

Gebraucht wird das vor allem für Anwendungen mit mehreren Bildschirmen: Präsentationssoftware (Folien auf dem Beamer, Notizen auf dem Laptop), Handelsplattformen, Leitstände, Bildbearbeitung mit abgetrennten Werkzeugfenstern oder das gezielte Öffnen von Fenstern per window.open() auf einem bestimmten Bildschirm. Außerdem lässt sich der Vollbildmodus über element.requestFullscreen({ screen }) auf einem bestimmten Bildschirm starten.

Beim ersten Aufruf fragt der Browser den Nutzer um Erlaubnis (Berechtigung "window-management", früher "window-placement"). Das zurückgegebene ScreenDetails-Objekt enthält die Eigenschaften screens (Array aus ScreenDetailed) und currentScreen. Es löst die Ereignisse screenschange (Bildschirm angeschlossen oder entfernt) und currentscreenchange (Fenster auf einen anderen Bildschirm verschoben oder dessen Eigenschaften geändert) aus.

Rückgabewert

Typ

Promise<ScreenDetails>

Beschreibung

Ein Promise, das mit einer ScreenDetails-Instanz erfüllt wird. Wird die Berechtigung verweigert, wird es mit einer NotAllowedError-DOMException abgelehnt.

Beispiele

Alle Bildschirme auflisten

const listScreens = async () => {
  if (!('getScreenDetails' in window)) {
    console.warn('Window Management API wird nicht unterstützt.');
    return;
  }
  try {
    const details = await window.getScreenDetails();
    details.screens.forEach((s, i) => {
      console.log(`#${i} ${s.label}: ${s.width}x${s.height} @ (${s.left}, ${s.top}), primär: ${s.isPrimary}, DPR: ${s.devicePixelRatio}`);
    });
    console.log('Aktueller Bildschirm:', details.currentScreen.label);
  } catch (err) {
    console.error('Zugriff verweigert:', err.name);
  }
};

document.querySelector('#screens-btn').addEventListener('click', listScreens);

#0 Integrierter Bildschirm: 1512x982 @ (0, 0), primär: true, DPR: 2 #1 DELL U2720Q: 2560x1440 @ (1512, 0), primär: false, DPR: 1 Aktueller Bildschirm: Integrierter Bildschirm

Präsentationsfenster auf dem zweiten Bildschirm öffnen

const openPresentation = async () => {
  const { screens, currentScreen } = await window.getScreenDetails();
  // Ersten Bildschirm wählen, der nicht der aktuelle ist
  const target = screens.find((s) => s !== currentScreen) ?? currentScreen;

  const features = [
    `left=${target.availLeft}`,
    `top=${target.availTop}`,
    `width=${target.availWidth}`,
    `height=${target.availHeight}`
  ].join(',');

  const win = window.open('/praesentation.html', 'praesentation', features);
  if (!win) console.warn('Popup wurde blockiert.');
};

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

Vollbild auf einem bestimmten Bildschirm und auf Änderungen reagieren

const details = await window.getScreenDetails();

details.addEventListener('screenschange', () => {
  console.log(`Anzahl Bildschirme: ${details.screens.length}`);
});

details.addEventListener('currentscreenchange', () => {
  console.log('Fenster ist jetzt auf:', details.currentScreen.label);
});

document.querySelector('#fullscreen').addEventListener('click', async () => {
  const external = details.screens.find((s) => !s.isInternal) ?? details.currentScreen;
  await document.documentElement.requestFullscreen({ screen: external });
});

Anzahl Bildschirme: 2 Fenster ist jetzt auf: DELL U2720Q

Berechtigungsstatus vorab prüfen

const checkPermission = async () => {
  try {
    const status = await navigator.permissions.query({ name: 'window-management' });
    console.log('Berechtigung:', status.state);
    status.addEventListener('change', () => console.log('Neu:', status.state));
  } catch {
    console.log('Berechtigungsname nicht bekannt (älterer Browser?)');
  }
};

checkPermission();

Berechtigung: prompt

// Wichtig · Fallstricke

Browser-Unterstützung: Aktuell nur in Chromium-Browsern (Chrome/Edge ab 100). Firefox und Safari unterstützen die API nicht. Deshalb immer vorher mit 'getScreenDetails' in window prüfen und einen Ersatzweg über window.screen vorsehen.
Sicherer Kontext und Berechtigung: Die Methode ist nur über HTTPS (bzw. localhost) verfügbar. Der Nutzer muss sie freigeben. Lehnt er ab, wird das Promise mit NotAllowedError abgelehnt – also immer try/catch verwenden.
Permissions Policy: In iframes muss die Einbettung allow="window-management" gesetzt sein, sonst schlägt der Aufruf fehl.
Berechtigungsname: Ältere Chrome-Versionen (vor ca. 111) nutzen "window-placement" statt "window-management".
Benutzeraktion: window.open() mit Positionsangaben und requestFullscreen() brauchen in der Regel eine Nutzeraktion (z. B. einen Klick). Popup-Blocker können mehrere gleichzeitig geöffnete Fenster verhindern.
Datenschutz: Bildschirmdaten eignen sich zum Fingerprinting. Frag deshalb nur nach, wenn du die Daten wirklich brauchst, und am besten erst nach einer erklärenden Nutzeraktion.
Koordinaten (left, top) beziehen sich auf den virtuellen Gesamtbereich aller Bildschirme und können negativ sein, zum Beispiel wenn ein Bildschirm links vom primären steht.

Siehe auch

Window.screen Window.open() Permissions.query() Window.getSelection() Window.setResizable()