VisualViewport.pageLeft — Eigenschaft · JavaScript-Referenz

Signatur

VisualViewport.pageLeft

Beschreibung

Die Eigenschaft pageLeft von window.visualViewport gibt an, wie weit der sichtbare Ausschnitt der Seite horizontal vom linken Rand des Dokuments (genauer: dem Ursprung des initialen umschließenden Blocks) entfernt ist. Der Wert wird in CSS-Pixeln angegeben und kann Nachkommastellen haben.

Im Unterschied zu window.scrollX berücksichtigt pageLeft auch den Pinch-Zoom: Zoomt eine Person auf dem Smartphone in die Seite hinein und verschiebt den Ausschnitt, ändert sich pageLeft, während scrollX (Layout-Viewport) gleich bleiben kann. Es gilt näherungsweise pageLeft = scrollX + offsetLeft.

Typische Einsatzfälle sind Elemente, die trotz Zoom exakt im sichtbaren Bereich positioniert werden sollen – etwa Toolbars, Tooltips, Kontextmenüs oder Overlays mit position: absolute in Dokumentkoordinaten. Man liest den Wert in den Events resize und scroll des VisualViewport aus.

Ist das zugehörige Dokument nicht (mehr) vollständig aktiv, etwa bei einem getrennten iframe, liefert die Eigenschaft 0.

Rückgabewert

Typ

number

Beschreibung

Horizontaler Versatz des visuellen Viewports zum Dokumentursprung in CSS-Pixeln (Gleitkommazahl, ggf. 0).

Beispiele

Aktuellen Wert auslesen und mit scrollX vergleichen

const vv = window.visualViewport;
if (vv) {
  console.log('pageLeft:', vv.pageLeft);
  console.log('scrollX:', window.scrollX);
  console.log('offsetLeft:', vv.offsetLeft);
}

pageLeft: 0 scrollX: 0 offsetLeft: 0

Toolbar trotz Pinch-Zoom im sichtbaren Bereich halten

const bar = document.querySelector('#toolbar');
bar.style.position = 'absolute';
bar.style.transformOrigin = '0 0';

const updateBar = () => {
  const vv = window.visualViewport;
  // Position in Dokumentkoordinaten, Größe gegen den Zoom ausgleichen
  bar.style.left = `${vv.pageLeft}px`;
  bar.style.top = `${vv.pageTop}px`;
  bar.style.transform = `scale(${1 / vv.scale})`;
};

window.visualViewport.addEventListener('scroll', updateBar);
window.visualViewport.addEventListener('resize', updateBar);
updateBar();

Sichtbaren Ausschnitt als Rechteck in Dokumentkoordinaten

const getVisibleRect = () => {
  const { pageLeft, pageTop, width, height } = window.visualViewport;
  return {
    left: Math.round(pageLeft),
    top: Math.round(pageTop),
    right: Math.round(pageLeft + width),
    bottom: Math.round(pageTop + height)
  };
};

console.log(getVisibleRect());

{ left: 0, top: 0, right: 1280, bottom: 720 }

// Wichtig · Fallstricke

Schreibgeschützt: Zuweisungen werden ignoriert. Zum Scrollen window.scrollTo() verwenden – den Pinch-Zoom-Versatz kann man per Skript nicht direkt setzen.
Der Wert ist oft eine Gleitkommazahl; für Pixel-genaues Layout ggf. runden.
Auf Desktop-Browsern ohne Pinch-Zoom entspricht pageLeft in der Regel scrollX.
scroll- und resize-Events können sehr häufig feuern; aufwendige Arbeit mit requestAnimationFrame bündeln.
Vor der Nutzung auf window.visualViewport prüfen – ältere Browser (z. B. Firefox vor Version 91 auf Desktop) kennen das Objekt nicht.
Bei getrenntem Dokument (z. B. entferntem iframe) wird 0 geliefert.

Siehe auch

VisualViewport VisualViewport.pageTop VisualViewport.offsetLeft VisualViewport.scale Window.scrollX WindowSharedStorage.worklet