Signatur
Beschreibung
Die Eigenschaft screens des Interfaces ScreenDetails gehört zur Window Management API (früher „Multi-Screen Window Placement API“). Sie liefert ein Array mit einem ScreenDetailed-Objekt pro verfügbarem Bildschirm. Jedes Objekt enthält unter anderem Position (left, top), Größe (width, height, availWidth, availHeight), devicePixelRatio, label sowie die Flags isPrimary und isInternal.
An ein ScreenDetails-Objekt kommst du nur über await window.getScreenDetails(). Das erfordert die Berechtigung window-management (vorher window-placement). Beim ersten Aufruf fragt der Browser den Nutzer um Erlaubnis.
Typische Anwendungsfälle sind Präsentationssoftware (Folien auf dem Beamer, Notizen auf dem Laptop), Trading- oder Leitstand-Dashboards mit mehreren Fenstern und Apps, die ein Element gezielt auf einem bestimmten Monitor im Vollbild anzeigen sollen. Verbinden oder trennt der Nutzer Monitore, wird das Array aktualisiert und das Event screenschange auf dem ScreenDetails-Objekt ausgelöst.
Rückgabewert
ScreenDetailed-Objekt pro angeschlossenem Bildschirm. Die Reihenfolge ist nicht garantiert. Um den Hauptbildschirm zu finden, prüfe isPrimary.Beispiele
Alle Bildschirme auflisten
const listScreens = async () => {
if (!('getScreenDetails' in window)) {
console.log('Window Management API 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}), primär: ${s.isPrimary}`);
});
} catch (err) {
console.error('Berechtigung verweigert:', err.name);
}
};
document.querySelector('#btn-screens').addEventListener('click', listScreens);Präsentation im Vollbild auf dem externen Monitor
const presentOnExternal = async (element) => {
const { screens } = await window.getScreenDetails();
// Bevorzugt einen externen, nicht primären Bildschirm
const target = screens.find((s) => !s.isInternal && !s.isPrimary)
?? screens.find((s) => !s.isPrimary)
?? screens[0];
await element.requestFullscreen({ screen: target });
};
document.querySelector('#start').addEventListener('click', () => {
presentOnExternal(document.querySelector('#slides'));
});Fenster auf jedem Bildschirm öffnen und auf Änderungen reagieren
const details = await window.getScreenDetails();
const openDashboards = () => {
details.screens.forEach((s, i) => {
window.open(
`/dashboard?panel=${i}`,
`panel-${i}`,
`left=${s.availLeft},top=${s.availTop},width=${s.availWidth},height=${s.availHeight}`
);
});
};
details.addEventListener('screenschange', () => {
console.log(`Anzahl Bildschirme jetzt: ${details.screens.length}`);
});
document.querySelector('#open').addEventListener('click', openDashboards);// Wichtig · Fallstricke
- Kompatibilität: Nur in Chromium-basierten Browsern (ab Chrome/Edge 100) verfügbar, Firefox und Safari unterstützen die API nicht. Prüfe deshalb vorher mit
'getScreenDetails' in window. - Sicherer Kontext und Berechtigung: Die API funktioniert nur über HTTPS. Sie braucht die Berechtigung
window-managementund in iframes zusätzlich die Permissions Policyallow="window-management". Verweigert der Nutzer die Erlaubnis, wird das Promise vongetScreenDetails()mitNotAllowedErrorabgelehnt. - Nutzergeste: Für
window.open()mit mehreren Fenstern und fürrequestFullscreen()ist eine Nutzeraktivierung nötig. Popup-Blocker lassen oft nur ein Fenster pro Klick zu. - Kein fester Stand: Das Array wird live aktualisiert. Speichere keine Indizes dauerhaft, sondern reagiere auf
screenschange. Die Koordinaten beziehen sich auf den gesamten virtuellen Bildschirmbereich und können negativ sein. - Datenschutz: Bildschirmdetails wie
labelkönnen zum Fingerprinting beitragen. Deshalb gibt es sie nur mit Berechtigung. Frage die Berechtigung erst an, wenn die Funktion wirklich gebraucht wird.