ScreenDetailed — Schnittstelle · JavaScript-Referenz

Signatur

interface ScreenDetailed extends Screen

Beschreibung

ScreenDetailed gehört zur Window Management API und erweitert das bekannte Screen-Interface um Angaben, die man für Anwendungen mit mehreren Bildschirmen braucht. Instanzen erzeugt man nicht selbst. Man erhält sie über window.getScreenDetails(): Das zurückgegebene ScreenDetails-Objekt enthält im Array screens alle angeschlossenen Bildschirme und in currentScreen den Bildschirm, auf dem das aktuelle Fenster liegt.

Neben den geerbten Eigenschaften (width, height, availWidth, availHeight, colorDepth, orientation …) stellt ScreenDetailed diese Eigenschaften bereit, die man nur lesen kann:

left / top – Position der oberen linken Ecke des Bildschirms im gemeinsamen Koordinatensystem aller Bildschirme.
availLeft / availTop – Position des nutzbaren Bereichs, also ohne Taskleiste oder Dock.
devicePixelRatio – Verhältnis von physischen Pixeln zu CSS-Pixeln auf diesem Bildschirm.
isInternal – true bei einem eingebauten Bildschirm, etwa dem Laptop-Display.
isPrimary – true, wenn das Betriebssystem ihn als Hauptbildschirm führt.
label – für Menschen lesbarer Name, z. B. "DELL U2720Q" oder "Built-in Retina Display".

Typische Einsatzfälle sind Präsentationsprogramme (Folien auf dem Beamer, Sprechernotizen auf dem Laptop), Handelsplattformen, Werkzeuge für Leitstellen und Kreativ-Programme, die Fenster gezielt auf einem bestimmten Bildschirm öffnen oder dort in den Vollbildmodus wechseln sollen. Ändert sich ein Bildschirm, zum Beispiel durch eine neue Auflösung oder Skalierung, löst das Objekt das Ereignis change aus.

Rückgabewert

Typ

ScreenDetailed

Beschreibung

Hat keinen eigenen Konstruktor. Instanzen stehen in ScreenDetails.screens und ScreenDetails.currentScreen, die man über await window.getScreenDetails() erhält.

Beispiele

Alle Bildschirme auflisten

const listScreens = async () => {
  if (!('getScreenDetails' in window)) {
    console.warn('Window Management API wird nicht unterstützt.');
    return;
  }
  // Fragt beim ersten Aufruf die Berechtigung "window-management" ab
  const details = await window.getScreenDetails();

  for (const s of details.screens) {
    console.log(
      `${s.label}: ${s.width}x${s.height} @ (${s.left}, ${s.top}),`,
      `DPR ${s.devicePixelRatio}, primär: ${s.isPrimary}, intern: ${s.isInternal}`
    );
  }
  console.log('Aktueller Bildschirm:', details.currentScreen.label);
};

listScreens();

Built-in Retina Display: 1512x982 @ (0, 0), DPR 2, primär: true, intern: true DELL U2720Q: 2560x1440 @ (1512, 0), DPR 1, primär: false, intern: false Aktueller Bildschirm: Built-in Retina Display

Popup auf dem externen Bildschirm öffnen

const openOnExternalScreen = async (url) => {
  const { screens } = await window.getScreenDetails();
  // Erst einen externen Bildschirm suchen, sonst einen, der nicht primär ist
  const target = screens.find((s) => !s.isInternal) ?? screens.find((s) => !s.isPrimary);

  if (!target) {
    console.log('Kein zweiter Bildschirm gefunden.');
    return null;
  }

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

  return window.open(url, 'presenter', features);
};

document.querySelector('#present').addEventListener('click', () => {
  openOnExternalScreen('/slides.html');
});

Vollbild auf einem bestimmten Bildschirm

const fullscreenOnPrimary = async (element) => {
  const { screens } = await window.getScreenDetails();
  const primary = screens.find((s) => s.isPrimary);
  // requestFullscreen nimmt ein ScreenDetailed-Objekt als Option "screen"
  await element.requestFullscreen({ screen: primary });
};

document.querySelector('#video-btn').addEventListener('click', () => {
  fullscreenOnPrimary(document.querySelector('video'));
});

Auf Änderungen eines Bildschirms reagieren

const watchScreens = async () => {
  const details = await window.getScreenDetails();

  const onChange = (event) => {
    const s = event.target;
    console.log(`${s.label} geändert: ${s.width}x${s.height}, DPR ${s.devicePixelRatio}`);
  };

  details.screens.forEach((s) => s.addEventListener('change', onChange));

  // Bildschirm angeschlossen oder entfernt
  details.addEventListener('screenschange', () => {
    console.log('Anzahl Bildschirme:', details.screens.length);
  });

  // Handler als Eigenschaft (Alternative):
  // details.currentScreen.onchange = onChange;
};

watchScreens();

DELL U2720Q geändert: 1920x1080, DPR 1

// Wichtig · Fallstricke

Unterstützung: Bisher nur in Chromium-Browsern (ab Version 100). Firefox und Safari unterstützen die API nicht. Deshalb vor der Nutzung immer mit 'getScreenDetails' in window prüfen und eine Lösung ohne die API vorsehen.
Berechtigung: getScreenDetails() fragt die Berechtigung "window-management" ab (früher "window-placement"). Lehnt der Nutzer ab, wird das Promise mit einem NotAllowedError abgelehnt. Den Status kann man mit navigator.permissions.query({ name: 'window-management' }) vorab prüfen.
Sicherer Kontext: Die API funktioniert nur über HTTPS oder auf localhost. In iframes muss die Permissions-Policy window-management sie erlauben.
Mit window.screen.isExtended kann man ohne Berechtigung vorab feststellen, ob überhaupt mehrere Bildschirme angeschlossen sind.
Koordinaten: left und top können negativ sein, etwa wenn ein Bildschirm links vom Hauptbildschirm steht. Beim Platzieren von Fenstern sollten Sie deshalb besser availLeft/availTop verwenden, damit Taskleisten nicht verdeckt werden.
Datenschutz: label und die Anordnung der Bildschirme eignen sich zum Fingerprinting. Rufen Sie die API daher nur auf, wenn der Nutzer etwas auslöst und Sie die Daten wirklich brauchen.
window.open() mit Positionsangaben auf einem anderen Bildschirm funktioniert meist nur nach einer Nutzeraktion. Sonst blockiert der Popup-Blocker das Fenster.

Siehe auch

Screen Window.open() ScreenDetails Credential Scheduler