Signatur
Beschreibung
Die schreibgeschützte Eigenschaft isPrimary gehört zum Interface ScreenDetailed der Window Management API (früher „Multi-Screen Window Placement API“). Sie liefert true, wenn der Bildschirm in den Anzeigeeinstellungen des Betriebssystems als Hauptbildschirm festgelegt ist. Ansonsten liefert sie false.
Ein ScreenDetailed-Objekt bekommt man nicht direkt über window.screen, sondern über await window.getScreenDetails(). Das zurückgegebene ScreenDetails-Objekt enthält in screens alle angeschlossenen Bildschirme und in currentScreen den Bildschirm, auf dem das aktuelle Fenster liegt.
Typische Einsatzfälle sind Präsentations-, Trading- oder Kiosk-Anwendungen mit mehreren Monitoren. Dort sollen Steuerelemente z. B. auf dem Hauptbildschirm bleiben, während Inhalte auf einem Zweitbildschirm im Vollbild erscheinen. Mit isPrimary lässt sich der Hauptbildschirm eindeutig bestimmen, ohne dass man ihn über die Koordinaten erraten muss.
Der Wert kann sich zur Laufzeit ändern, wenn der Nutzer die Anzeigeeinstellungen ändert. Solche Änderungen meldet das change-Event des jeweiligen ScreenDetailed-Objekts.
Rückgabewert
true, wenn der Bildschirm der primäre Bildschirm des Betriebssystems ist, sonst false.Beispiele
Primären Bildschirm ermitteln
const findPrimaryScreen = async () => {
if (!('getScreenDetails' in window)) {
console.log('Window Management API nicht unterstützt');
return null;
}
// Löst eine Berechtigungsabfrage „window-management“ aus
const details = await window.getScreenDetails();
const primary = details.screens.find((s) => s.isPrimary);
console.log(`Primär: ${primary.label} (${primary.width}×${primary.height})`);
return primary;
};
findPrimaryScreen();Präsentation auf Zweitbildschirm im Vollbild öffnen
const button = document.querySelector('#present');
button.addEventListener('click', async () => {
const { screens } = await window.getScreenDetails();
// Ersten Nicht-Primärbildschirm wählen, sonst den primären
const target = screens.find((s) => !s.isPrimary) ?? screens[0];
await document.querySelector('#slides').requestFullscreen({ screen: target });
});Prüfen, ob das aktuelle Fenster auf dem Hauptbildschirm liegt, und Änderungen verfolgen
const details = await window.getScreenDetails();
const report = () => {
const { currentScreen } = details;
console.log(currentScreen.isPrimary
? 'Fenster liegt auf dem Hauptbildschirm'
: 'Fenster liegt auf einem Nebenbildschirm');
};
report();
// Fenster wurde auf einen anderen Bildschirm verschoben
details.addEventListener('currentscreenchange', report);
// Anzeigeeinstellungen (z. B. Hauptbildschirm) geändert
details.currentScreen.addEventListener('change', report);// Wichtig · Fallstricke
- Browser-Kompatibilität: Die Eigenschaft ist experimentell. Nur Chromium-basierte Browser (Chrome, Edge, Opera) unterstützen sie. Firefox und Safari unterstützen sie nicht. Prüfen Sie die Unterstützung vorher mit
'getScreenDetails' in window. - Berechtigung und sicherer Kontext:
getScreenDetails()funktioniert nur über HTTPS und verlangt die Berechtigungwindow-management. Lehnt der Nutzer ab, wird das Promise mit einemNotAllowedErrorabgelehnt. In iframes muss die Permissions-Policywindow-managementerlaubt sein. - Das normale
window.screenist ein einfachesScreen-Objekt ohneisPrimary. Die Eigenschaft gibt es nur aufScreenDetailed-Objekten. - Ist nur ein Bildschirm angeschlossen, ist dieser in der Regel auch der primäre. Rechnen Sie trotzdem mit Fällen, in denen kein Bildschirm als primär gemeldet wird. Planen Sie dafür einen Rückfallwert ein, z. B.
screens[0]. - Datenschutz: Angaben zu mehreren Bildschirmen erhöhen das Fingerprinting-Risiko. Fragen Sie die Details deshalb nur ab, wenn Sie sie wirklich brauchen, idealerweise erst nach einer Nutzeraktion.