ScreenDetailed.availTop — Eigenschaft · JavaScript-Referenz

Signatur

ScreenDetailed.availTop

Beschreibung

Die schreibgeschützte Eigenschaft availTop eines ScreenDetailed-Objekts gibt die y-Koordinate der oberen Kante des verfügbaren Bereichs eines Bildschirms an. „Verfügbar“ heißt: Bereiche, die das Betriebssystem belegt, etwa eine oben angeordnete Menüleiste (macOS) oder eine oben angedockte Taskleiste (Windows), werden abgezogen. Der Wert wird in CSS-Pixeln relativ zum virtuellen Bildschirmarrangement angegeben, also zum gemeinsamen Koordinatensystem aller angeschlossenen Bildschirme.

Im Unterschied zu ScreenDetailed.top (obere Kante des gesamten Bildschirms) berücksichtigt availTop diese Systemelemente. Beim primären Bildschirm ist top meist 0; availTop kann dagegen z. B. 25 betragen, wenn oben eine Menüleiste liegt. Bei sekundären Bildschirmen, die über oder unter dem Hauptbildschirm angeordnet sind, kann der Wert auch negativ oder sehr groß sein.

Gebraucht wird availTop vor allem in Mehrbildschirm-Anwendungen (Präsentations-Software, Trading-Dashboards, Kreativ-Tools). Dort sollen Fenster per window.open() oder window.moveTo() gezielt auf einem bestimmten Bildschirm platziert werden, ohne von Systemleisten verdeckt zu werden. Zusammen mit availLeft, availWidth und availHeight ergibt sich das vollständige Rechteck des nutzbaren Bereichs.

An die ScreenDetailed-Objekte kommt man über window.getScreenDetails(). Dafür braucht es die Berechtigung window-management (früher window-placement), und die Seite muss in einem sicheren Kontext (HTTPS) laufen.

Rückgabewert

Typ

number

Beschreibung

Die y-Koordinate der oberen Kante des verfügbaren Bildschirmbereichs in CSS-Pixeln, relativ zum Ursprung des virtuellen Mehrbildschirm-Arrangements. Der Wert kann negativ sein.

Beispiele

Verfügbare obere Kante aller Bildschirme auslesen

const zeigeBildschirme = async () => {
  if (!('getScreenDetails' in window)) {
    console.log('Window Management API wird nicht unterstützt.');
    return;
  }
  // Fragt beim ersten Aufruf nach der Berechtigung
  const details = await window.getScreenDetails();
  for (const screen of details.screens) {
    console.log(`${screen.label}: top=${screen.top}, availTop=${screen.availTop}`);
  }
};

zeigeBildschirme();

Eingebauter Bildschirm: top=0, availTop=25 DELL U2720Q: top=-1440, availTop=-1440

Pop-up oben links im nutzbaren Bereich eines zweiten Bildschirms öffnen

const oeffneAufZweitemBildschirm = async (url) => {
  const details = await window.getScreenDetails();
  // Einen Bildschirm wählen, der nicht der aktuelle ist
  const ziel = details.screens.find((s) => s !== details.currentScreen) ?? details.currentScreen;

  const breite = Math.min(800, ziel.availWidth);
  const hoehe = Math.min(600, ziel.availHeight);

  // availLeft/availTop sorgen dafür, dass Menü- oder Taskleiste das Fenster nicht verdecken
  const features = [
    `left=${ziel.availLeft}`,
    `top=${ziel.availTop}`,
    `width=${breite}`,
    `height=${hoehe}`
  ].join(',');

  return window.open(url, 'praesentation', features);
};

document.querySelector('#start').addEventListener('click', () => {
  oeffneAufZweitemBildschirm('/praesentation.html');
});

Fenster auf dem aktuellen Bildschirm vertikal zentrieren

const zentriereVertikal = async () => {
  const { currentScreen } = await window.getScreenDetails();
  const y = currentScreen.availTop + Math.round((currentScreen.availHeight - window.outerHeight) / 2);
  window.moveTo(window.screenX, y);
  console.log('Neue y-Position:', y);
};

zentriereVertikal();

Neue y-Position: 262

Auf Layout-Änderungen reagieren

const beobachte = async () => {
  const details = await window.getScreenDetails();
  const { currentScreen } = details;

  // Feuert z. B., wenn die Taskleiste verschoben wird
  currentScreen.addEventListener('change', () => {
    console.log('Neuer availTop-Wert:', currentScreen.availTop);
  });

  // Feuert, wenn Bildschirme hinzukommen oder entfernt werden
  details.addEventListener('screenschange', () => {
    console.log('Anzahl Bildschirme:', details.screens.length);
  });
};

beobachte();

Neuer availTop-Wert: 48

// Wichtig · Fallstricke

Browser-Unterstützung: Die Window Management API gibt es nur in Chromium-basierten Browsern (ab Chrome/Edge 100). Firefox und Safari unterstützen sie nicht. Vor der Nutzung sollte man deshalb mit 'getScreenDetails' in window prüfen, ob die API vorhanden ist.
Berechtigung und sicherer Kontext: getScreenDetails() braucht HTTPS und die Berechtigung window-management. Lehnt der Nutzer ab, wird das Promise mit einem NotAllowedError verworfen. In iframes muss die Permissions Policy window-management die Nutzung erlauben.
Negative Werte: Liegt ein Bildschirm über dem primären, ist availTop negativ. Werte nicht auf >= 0 begrenzen.
Unterschied zu Screen.availTop: Die ältere, nicht standardisierte Eigenschaft window.screen.availTop bezieht sich nur auf den aktuellen Bildschirm und liefert nicht überall dieselben Werte. ScreenDetailed.availTop ist dagegen einheitlich im virtuellen Koordinatensystem definiert.
Werte können sich ändern: Wird die Taskleiste verschoben, die Auflösung geändert oder ein Bildschirm abgesteckt, ändert sich der Wert. Am besten auf das change-Event von ScreenDetailed und das screenschange-Event von ScreenDetails reagieren.
Fensterplatzierung: Browser können angeforderte Positionen von window.open()/moveTo() anpassen oder begrenzen. Außerdem erlauben sie moveTo() meist nur für Pop-ups, die das Skript selbst geöffnet hat.
Datenschutz: Details zum Bildschirm-Layout lassen sich für Fingerprinting nutzen. Deshalb gibt es sie nur mit ausdrücklicher Berechtigung.

Siehe auch

Window.open() ScreenDetailed.availLeft ScreenDetailed.top ScreenDetailed.label ScreenDetailed.left