VisualViewport.pageTop — Eigenschaft · JavaScript-Referenz

Signatur

VisualViewport.pageTop

Beschreibung

Die schreibgeschützte Eigenschaft pageTop des VisualViewport-Interfaces liefert die vertikale Position der oberen Kante des visuellen Viewports. Gemessen wird relativ zum Ursprung des initialen enthaltenen Blocks, also zum Dokumentanfang, in CSS-Pixeln. Ist das Dokument nicht vollständig aktiv, etwa in einem abgelösten iframe, gibt die Eigenschaft 0 zurück.

Im Unterschied zu window.scrollY berücksichtigt pageTop auch das Pinch-Zoom auf Mobilgeräten. Beim Pinch-Zoom verschiebt sich der visuelle Viewport innerhalb des Layout-Viewports, während der Layout-Viewport an seiner Stelle bleibt. Dabei gilt: pageTop entspricht ungefähr window.scrollY + visualViewport.offsetTop.

Typische Einsatzfälle sind Elemente, die trotz Zoom sichtbar bleiben sollen, zum Beispiel schwebende Werkzeugleisten, eigene Tooltips oder Overlays. Auch wer beim Einblenden der Bildschirmtastatur erkennen will, welcher Dokumentbereich gerade tatsächlich sichtbar ist, braucht diesen Wert. Ausgelesen wird er meist in den Handlern der Events scroll und resize von window.visualViewport.

Rückgabewert

Typ

number

Beschreibung

Die y-Koordinate der oberen Kante des visuellen Viewports relativ zum Dokumentanfang in CSS-Pixeln. Der Wert kann eine Gleitkommazahl sein. Ist das Dokument nicht vollständig aktiv, ist er 0.

Beispiele

Aktuelle Position auslesen

const vv = window.visualViewport;

if (vv) {
  console.log(`pageTop: ${vv.pageTop}`);
  console.log(`scrollY: ${window.scrollY}`);
  console.log(`offsetTop: ${vv.offsetTop}`);
} else {
  console.log('VisualViewport wird nicht unterstützt');
}

pageTop: 480 scrollY: 480 offsetTop: 0

Schwebende Leiste trotz Pinch-Zoom oben halten

// CSS-Voraussetzung: #toolbar { position: absolute; top: 0; left: 0; transform-origin: 0 0; }
const toolbar = document.querySelector('#toolbar');
const vv = window.visualViewport;

const positionToolbar = () => {
  // Leiste an die obere linke Ecke des sichtbaren Bereichs setzen
  // und den Zoom ausgleichen, damit sie gleich groß bleibt
  toolbar.style.transform =
    `translate(${vv.pageLeft}px, ${vv.pageTop}px) scale(${1 / vv.scale})`;
};

vv.addEventListener('scroll', positionToolbar);
vv.addEventListener('resize', positionToolbar);
positionToolbar();

Prüfen, ob ein Element im sichtbaren Bereich liegt

const isVisible = (el) => {
  const vv = window.visualViewport;
  const rect = el.getBoundingClientRect();
  // Elementposition in Dokument-Koordinaten umrechnen
  const top = rect.top + window.scrollY;
  const bottom = top + rect.height;
  return bottom > vv.pageTop && top < vv.pageTop + vv.height;
};

const heading = document.querySelector('h1');
console.log(isVisible(heading) ? 'sichtbar' : 'außerhalb');

sichtbar

// Wichtig · Fallstricke

Unterstützung prüfen: window.visualViewport kann in älteren Browsern undefined sein. Vor dem Zugriff also prüfen, zum Beispiel mit window.visualViewport?.pageTop.
Nur lesbar: Eine Zuweisung an pageTop hat keine Wirkung. Zum Scrollen window.scrollTo() verwenden.
Unterschied zu offsetTop: offsetTop ist relativ zum Layout-Viewport, pageTop relativ zum Dokumentanfang. Wer die beiden verwechselt, positioniert Elemente falsch.
Desktop: Ohne Pinch-Zoom ist pageTop meist identisch mit window.scrollY. Unterschiede zeigen sich vor allem auf Touch-Geräten.
Leistung: Das Event scroll feuert sehr häufig. Aufwendige DOM-Änderungen im Handler per requestAnimationFrame bündeln.
Gleitkommazahlen: Der Wert muss keine ganze Zahl sein. Bei Vergleichen gegebenenfalls runden.

Siehe auch

VisualViewport VisualViewport.pageLeft VisualViewport.offsetTop VisualViewport.scale VisualViewport.height Window.scrollY