Start · Sprachen · JavaScript · Referenz · ScreenDetails.currentScreen

ScreenDetails.currentScreen

Eigenschaft

Schreibgeschützte Eigenschaft, die ein <code>ScreenDetailed</code>-Objekt für den Bildschirm liefert, auf dem sich das aktuelle Browserfenster gerade befindet.

seit JavaScript Window Management API – Chromium 100+ (Chrome, Edg Kategorie: webapi

Signatur

ScreenDetails.currentScreen

Beschreibung

Die Eigenschaft currentScreen der Schnittstelle ScreenDetails gehört zur Window Management API (früher „Multi-Screen Window Placement API“). Sie enthält ein einzelnes ScreenDetailed-Objekt mit ausführlichen Angaben zu dem Bildschirm, auf dem das aktuelle Browserfenster gerade dargestellt wird. Dazu gehören zum Beispiel label, isPrimary, isInternal, devicePixelRatio, left/top sowie die verfügbare Fläche.

An das ScreenDetails-Objekt kommt man über await window.getScreenDetails(). Dafür ist die Berechtigung window-management nötig. Ist das Fenster auf mehrere Bildschirme verteilt, gilt als aktueller Bildschirm der, auf dem der größte Teil des Fensters liegt.

Typische Einsatzfälle sind Präsentations-, Handels- oder Kontrollraum-Anwendungen. Dort will man zum Beispiel erkennen, ob das Fenster auf dem internen Laptop-Display oder auf einem externen Monitor liegt, um dann Inhalte gezielt auf einem anderen Bildschirm zu öffnen oder dort in den Vollbildmodus zu wechseln. Ändert sich der aktuelle Bildschirm, etwa weil jemand das Fenster auf einen anderen Monitor zieht, wird am ScreenDetails-Objekt das Ereignis currentscreenchange ausgelöst.

Rückgabewert

Typ
ScreenDetailed
Beschreibung
Ein ScreenDetailed-Objekt (erweitert Screen), das den Bildschirm beschreibt, auf dem das aktuelle Fenster liegt. Es ist auch in ScreenDetails.screens enthalten.

Beispiele

Informationen zum aktuellen Bildschirm auslesen

const zeigeAktuellenBildschirm = async () => {
  if (!('getScreenDetails' in window)) {
    console.log('Window Management API wird nicht unterstützt.');
    return;
  }
  const details = await window.getScreenDetails();
  const aktuell = details.currentScreen;
  console.log(`Bildschirm: ${aktuell.label}`);
  console.log(`Primär: ${aktuell.isPrimary}, intern: ${aktuell.isInternal}`);
  console.log(`Größe: ${aktuell.width}x${aktuell.height} @ ${aktuell.devicePixelRatio}x`);
};

zeigeAktuellenBildschirm();
Bildschirm: Built-in Retina Display Primär: true, intern: true Größe: 1512x982 @ 2x

Präsentation auf einem anderen Bildschirm als dem aktuellen im Vollbild zeigen

const button = document.querySelector('#praesentieren');

button.addEventListener('click', async () => {
  const details = await window.getScreenDetails();
  const { currentScreen, screens } = details;

  // Ersten Bildschirm wählen, auf dem das Fenster NICHT liegt
  const ziel = screens.find((s) => s !== currentScreen) ?? currentScreen;

  await document.querySelector('#folien').requestFullscreen({ screen: ziel });
  console.log(`Vollbild auf: ${ziel.label}`);
});
Vollbild auf: DELL U2720Q

Auf einen Bildschirmwechsel reagieren

const details = await window.getScreenDetails();

const aktualisiereLayout = () => {
  const { currentScreen } = details;
  document.body.classList.toggle('kompakt', currentScreen.isInternal);
  console.log(`Fenster liegt jetzt auf: ${currentScreen.label}`);
};

details.addEventListener('currentscreenchange', aktualisiereLayout);
aktualisiereLayout();
Fenster liegt jetzt auf: Built-in Retina Display Fenster liegt jetzt auf: DELL U2720Q

// Wichtig · Fallstricke

  • Browser-Unterstützung: Die Eigenschaft gibt es nur in Chromium-basierten Browsern (ab Chrome/Edge 100). Firefox und Safari unterstützen sie nicht. Vor der Nutzung sollte man per 'getScreenDetails' in window prüfen, ob die API vorhanden ist.
  • Berechtigung: getScreenDetails() fragt die Berechtigung window-management ab. Lehnt der Nutzer ab, wird das Promise mit einem NotAllowedError zurückgewiesen. Den Status kann man vorab mit navigator.permissions.query({ name: 'window-management' }) prüfen. In iframes ist die Permissions-Policy window-management nötig.
  • Die API steht nur in sicheren Kontexten (HTTPS) zur Verfügung.
  • Das zurückgegebene Objekt ist „live“: Seine Eigenschaften werden aktualisiert, und beim Monitorwechsel liefert currentScreen ein anderes Objekt. Den Wert also nicht dauerhaft zwischenspeichern, sondern bei Bedarf neu lesen oder auf currentscreenchange hören.
  • Datenschutz: Bildschirmbezeichnungen (label) und Anordnung können zum Fingerprinting beitragen. Deshalb ist die Berechtigung Pflicht.