ScreenDetailed.top — Eigenschaft · JavaScript-Referenz

Signatur

ScreenDetailed.top

Beschreibung

ScreenDetailed.top ist eine schreibgeschützte Eigenschaft der ScreenDetailed-Schnittstelle aus der Window Management API. Sie gibt als Zahl in CSS-Pixeln an, wo die obere Kante eines bestimmten Bildschirms innerhalb des vom Betriebssystem gebildeten virtuellen Gesamtbildschirms liegt. Der Wert gilt für den gesamten Bildschirmbereich, also auch für Bereiche, die Taskleiste, Dock oder Menüleiste belegen.

In der Praxis braucht man die Eigenschaft, wenn man Fenster gezielt auf einem bestimmten Monitor öffnen oder platzieren will, etwa bei Präsentations-, Trading- oder Kiosk-Anwendungen mit mehreren Bildschirmen. Zusammen mit left, width und height beschreibt top das Rechteck eines Monitors. Diese Werte kann man direkt an window.open() oder window.moveTo() übergeben.

Der Koordinatenursprung (0, 0) liegt normalerweise in der linken oberen Ecke des primären Bildschirms. Monitore, die oberhalb davon angeordnet sind, haben deshalb einen negativen top-Wert. Den nutzbaren Bereich ohne Systemleisten liefert stattdessen availTop.

Inhaltlich entspricht top der nicht standardisierten Eigenschaft Screen.top bzw. screen.screenTop, die manche Browser kennen. ScreenDetailed.top ist jedoch standardisiert und für jeden Bildschirm einzeln abrufbar.

Rückgabewert

Typ

number

Beschreibung

Die y-Koordinate der oberen Kante des Bildschirms in CSS-Pixeln, bezogen auf den virtuellen Gesamtbildschirm. Der Wert kann negativ sein.

Beispiele

Obere Kante aller Bildschirme auslesen

const zeigeBildschirme = async () => {
  if (!('getScreenDetails' in window)) {
    console.log('Window Management API wird nicht unterstützt.');
    return;
  }
  // Löst ggf. eine Berechtigungsabfrage aus
  const details = await window.getScreenDetails();
  for (const s of details.screens) {
    console.log(`${s.label}: top=${s.top}, left=${s.left}, ${s.width}x${s.height}`);
  }
};

document.querySelector('#scan').addEventListener('click', zeigeBildschirme);

Built-in Retina Display: top=0, left=0, 1512x982 DELL U2720Q: top=-1080, left=0, 1920x1080

Fenster am oberen Rand des zweiten Monitors öffnen

const oeffneAufZweitemMonitor = async () => {
  const { screens, currentScreen } = await window.getScreenDetails();
  const ziel = screens.find((s) => s !== currentScreen) ?? currentScreen;

  const features = [
    `left=${ziel.left}`,
    `top=${ziel.top}`,
    `width=${Math.round(ziel.width / 2)}`,
    `height=${Math.round(ziel.height / 2)}`
  ].join(',');

  window.open('/praesentation.html', 'praesentation', features);
};

document.querySelector('#present').addEventListener('click', oeffneAufZweitemMonitor);

top mit availTop vergleichen (Höhe der Menüleiste)

const pruefeSystemleiste = async () => {
  const { currentScreen } = await window.getScreenDetails();
  const leisteOben = currentScreen.availTop - currentScreen.top;
  console.log(`Oben reservierter Bereich: ${leisteOben}px`);
};

pruefeSystemleiste();

Oben reservierter Bereich: 25px

Auf Änderungen der Anordnung reagieren

const details = await window.getScreenDetails();

details.currentScreen.addEventListener('change', (event) => {
  const s = event.target;
  console.log(`Bildschirm geändert, neue obere Kante: ${s.top}`);
});

details.addEventListener('screenschange', () => {
  console.log('Bildschirme:', details.screens.map((s) => s.top));
});

Bildschirm geändert, neue obere Kante: -1080

// Wichtig · Fallstricke

Berechtigung nötig: window.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 vorab mit navigator.permissions.query({ name: 'window-management' }) prüfen.
Browser-Unterstützung: Die API gibt es nur in Chromium-Browsern ab Version 100. Firefox und Safari unterstützen sie nicht. Prüfen Sie deshalb immer mit 'getScreenDetails' in window, ob sie vorhanden ist.
Die API ist nur in einem sicheren Kontext (HTTPS) verfügbar. In iframes kann sie per Permissions-Policy window-management gesperrt sein.
Mit negativen Werten rechnen: Liegt ein Monitor oberhalb des primären Bildschirms, ist top kleiner als 0.
top beschreibt den gesamten Bildschirm. Wer Fenster platziert, sollte meist availTop verwenden, damit das Fenster nicht unter der Menüleiste oder Taskleiste landet.
Die Eigenschaft ist schreibgeschützt. Eine Zuweisung wird ignoriert bzw. wirft im Strict Mode einen Fehler.
Den Einfluss von Skalierung und DPI beachten: Die Werte sind CSS-Pixel. devicePixelRatio kann sich zwischen Monitoren unterscheiden.

Siehe auch

Window.open() ScreenDetailed.left ScreenDetailed.availTop ScreenDetailed.label ScreenDetailed.isPrimary