Signatur
interface ScreenDetails extends EventTarget
Beschreibung
ScreenDetails ist das zentrale Objekt der Window Management API (früher „Multi-Screen Window Placement API“). Es bietet eine Übersicht über alle Bildschirme, die mit dem Gerät verbunden sind. Das klassische window.screen kennt dagegen nur den Bildschirm, auf dem das Fenster gerade angezeigt wird. Einen Konstruktor gibt es nicht. Eine Instanz erhält man nur über das Promise von window.getScreenDetails(), und auch nur, wenn der Nutzer die Berechtigung "window-management" erteilt hat.
Das Interface hat zwei schreibgeschützte Eigenschaften und zwei Ereignisse:
screens: ein Array vonScreenDetailed-Objekten, eines für jeden verbundenen Bildschirm. Jedes Objekt enthält unter anderemleft,top,availLeft,availTop,isPrimary,isInternal,devicePixelRatioundlabel.currentScreen: dasScreenDetailed-Objekt des Bildschirms, auf dem sich das aktuelle Fenster befindet.- Ereignis
screenschange: wird ausgelöst, wenn ein Bildschirm angeschlossen oder entfernt wird. - Ereignis
currentscreenchange: wird ausgelöst, wenn sich Eigenschaften des aktuellen Bildschirms ändern oder das Fenster auf einen anderen Bildschirm verschoben wird.
Typische Einsatzfälle sind Präsentationsprogramme (Folien auf dem Beamer, Notizen auf dem Laptop), Handels- und Überwachungs-Dashboards, Bildbearbeitung mit ausgelagerten Werkzeugpaletten und Videokonferenzen. Mit den Koordinaten aus screens kann man neue Fenster über window.open() gezielt auf einem bestimmten Bildschirm öffnen. Außerdem kann man mit element.requestFullscreen({ screen }) den Vollbildmodus auf einem anderen Bildschirm starten.
Rückgabewert
Typ
ScreenDetails
Beschreibung
Instanzen gibt es nur als Ergebnis von
await window.getScreenDetails(). Das Objekt ist „live“: screens und currentScreen werden automatisch aktualisiert, wenn sich die Bildschirmkonfiguration ändert.Beispiele
Alle Bildschirme abfragen und 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 || 'Unbenannt'}: ${s.width}x${s.height} @ (${s.left}, ${s.top})` +
`${s.isPrimary ? ' [primär]' : ''}${s.isInternal ? ' [intern]' : ''}`);
});
console.log('Aktueller Bildschirm:', details.currentScreen.label);
} catch (err) {
// NotAllowedError, wenn der Nutzer die Berechtigung verweigert
console.error('Zugriff verweigert:', err.name);
}
};
listScreens();#0 Built-in Retina Display: 1512x982 @ (0, 0) [primär] [intern]
#1 DELL U2720Q: 2560x1440 @ (1512, -200)
Aktueller Bildschirm: Built-in Retina Display
Präsentationsfenster auf dem zweiten Bildschirm öffnen
const openOnSecondaryScreen = async (url) => {
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(',');
return window.open(url, 'praesentation', features);
};
// Muss durch eine Nutzeraktion ausgelöst werden (Popup-Blocker)
document.querySelector('#start').addEventListener('click', () => {
openOnSecondaryScreen('/folien.html');
});Vollbild auf einem anderen Bildschirm starten
const fullscreenElsewhere = async (element) => {
const details = await window.getScreenDetails();
const other = details.screens.find((s) => !s.isPrimary);
if (!other) {
console.log('Kein zweiter Bildschirm vorhanden');
return;
}
await element.requestFullscreen({ screen: other });
};
document.querySelector('#video-btn').addEventListener('click', () => {
fullscreenElsewhere(document.querySelector('video'));
});Auf Änderungen der Bildschirmkonfiguration reagieren
const details = await window.getScreenDetails();
const onScreensChange = () => {
console.log(`Anzahl Bildschirme: ${details.screens.length}`);
};
details.addEventListener('screenschange', onScreensChange);
// Alternativ über die on-Property
details.oncurrentscreenchange = () => {
const s = details.currentScreen;
console.log(`Fenster ist jetzt auf "${s.label}" (DPR ${s.devicePixelRatio})`);
};
// Später wieder abmelden
// details.removeEventListener('screenschange', onScreensChange);
// details.oncurrentscreenchange = null;Anzahl Bildschirme: 2
Fenster ist jetzt auf "DELL U2720Q" (DPR 1.5)
// Wichtig · Fallstricke
- Browser-Unterstützung: Die API gibt es nur in Chromium-Browsern (ab Chrome/Edge 100). Firefox und Safari unterstützen sie nicht. Daher immer mit
'getScreenDetails' in windowprüfen und notfalls aufwindow.screenzurückgreifen. - Berechtigung: Beim ersten Aufruf von
getScreenDetails()erscheint eine Berechtigungsabfrage. Wird sie abgelehnt, wird das Promise mit einemNotAllowedErrorabgewiesen. Den aktuellen Status kann man übernavigator.permissions.query({ name: 'window-management' })abfragen. Ältere Chrome-Versionen verwenden noch den Namen'window-placement'. - Sicherer Kontext und Permissions-Policy: Die API funktioniert nur über HTTPS (oder localhost). In iframes muss sie mit
allow="window-management"freigegeben werden. - Koordinaten:
leftundtopbeziehen sich auf den gesamten virtuellen Arbeitsbereich aller Bildschirme und können negativ sein, zum Beispiel bei einem Monitor links oder oberhalb des Hauptbildschirms. Werte nicht auf 0 begrenzen. - Datenschutz: Mit der Liste der Bildschirme lässt sich ein Nutzer leichter wiedererkennen (Fingerprinting). Deshalb die Berechtigung erst anfordern, wenn die Funktion wirklich gebraucht wird, und zwar direkt nach einer Nutzeraktion.
window.screen.isExtendedzeigt ohne Berechtigung an, ob mehrere Bildschirme vorhanden sind. Damit kann man entscheiden, ob sich die Abfrage überhaupt lohnt.window.open()undrequestFullscreen()brauchen weiterhin eine Nutzeraktion. Sonst blockiert der Browser das Popup oder weist die Anfrage ab.