Window.viewport — Eigenschaft · JavaScript-Referenz

Signatur

get Window.viewport

Beschreibung

Die Eigenschaft window.viewport gibt eine Instanz der Schnittstelle Viewport zurück. Sie beschreibt den aktuellen Zustand des Geräte-Viewports. Sie ist Teil der Viewport Segments API. Diese API richtet sich an Geräte mit mehreren Bildschirmbereichen, etwa faltbare Smartphones oder Geräte mit zwei Bildschirmen, bei denen ein Scharnier oder eine Falz das Browserfenster in mehrere logische Bereiche teilt.

Die wichtigste Eigenschaft des zurückgegebenen Objekts ist Viewport.segments. Sie liefert ein Array von DOMRect-Objekten, eines pro Segment, jeweils mit Position und Größe relativ zum Layout-Viewport. So kann eine Seite ihren Inhalt gezielt verteilen, etwa eine Liste links und eine Detailansicht rechts vom Scharnier, damit nichts Wichtiges von der Falz verdeckt wird.

Die Eigenschaft selbst ist schreibgeschützt und hat keine Parameter. Das Viewport-Objekt ist ein „Live“-Objekt: Klappt jemand das Gerät auf oder zu oder dreht es, wird segments beim nächsten Lesen neu berechnet. Um auf solche Änderungen zu reagieren, lauscht man auf das resize-Ereignis von window oder nutzt die passenden CSS-Media-Queries (horizontal-viewport-segments, vertical-viewport-segments).

Für reines Layout reichen oft die CSS-Umgebungsvariablen env(viewport-segment-width 0 0) usw. Die JavaScript-Schnittstelle eignet sich besonders, wenn man die Aufteilung im Code braucht, z. B. für Canvas-Zeichnungen, Karten oder die Logik von Master-Detail-Ansichten.

Rückgabewert

Typ

Viewport

Beschreibung

Ein Viewport-Objekt. Seine Eigenschaft segments liefert ein Array von DOMRect-Objekten (eines pro Viewport-Segment) oder in bestimmten Zuständen null, z. B. wenn das Dokument nicht aktiv ist.

Beispiele

Unterstützung prüfen und Segmente auslesen

if ('viewport' in window && window.viewport) {
  const segments = window.viewport.segments ?? [];
  console.log(`Anzahl Segmente: ${segments.length}`);
  segments.forEach((rect, i) => {
    console.log(`Segment ${i}: x=${rect.x}, y=${rect.y}, ${rect.width}×${rect.height}`);
  });
} else {
  console.log('Viewport Segments API wird nicht unterstützt.');
}

Anzahl Segmente: 2 Segment 0: x=0, y=0, 540×720 Segment 1: x=564, y=0, 540×720

Layout bei Auf-/Zuklappen anpassen (Master-Detail)

const app = document.querySelector('#app');

const updateLayout = () => {
  const segments = window.viewport?.segments;
  if (!segments || segments.length < 2) {
    app.dataset.layout = 'single';
    return;
  }
  const [first, second] = segments;
  // Nebeneinander = horizontale Falz, übereinander = vertikale Anordnung
  const sideBySide = second.left >= first.right;
  app.dataset.layout = sideBySide ? 'dual-horizontal' : 'dual-vertical';
  // Breite der Falz als CSS-Variable bereitstellen
  const hinge = sideBySide ? second.left - first.right : second.top - first.bottom;
  app.style.setProperty('--hinge-size', `${hinge}px`);
};

updateLayout();
window.addEventListener('resize', updateLayout);

Kombination mit Media Query

const mq = window.matchMedia('(horizontal-viewport-segments: 2)');

const onChange = () => {
  if (mq.matches) {
    const [left, right] = window.viewport.segments;
    console.log(`Linkes Segment endet bei ${left.right}px, rechtes beginnt bei ${right.left}px`);
  } else {
    console.log('Einzelner Viewport-Bereich');
  }
};

mq.addEventListener('change', onChange);
onChange();

Linkes Segment endet bei 540px, rechtes beginnt bei 564px

// Wichtig · Fallstricke

Experimentell: Nur Chromium-basierte Browser unterstützen die Eigenschaft (ab etwa Version 138). Firefox und Safari kennen sie derzeit nicht. Prüfe deshalb immer vorher, z. B. mit 'viewport' in window oder optionaler Verkettung (window.viewport?.segments).
Nicht verwechseln mit window.visualViewport (VisualViewport). Diese API liefert Zoom, Verschiebung und sichtbaren Bereich, etwa bei eingeblendeter Bildschirmtastatur. window.viewport betrifft nur die Aufteilung in Segmente.
Auf normalen Geräten mit nur einem Bildschirmbereich enthält segments höchstens ein Rechteck. In Sonderfällen, etwa bei nicht aktiven Dokumenten, kann es auch null sein. Prüfe daher robust mit !segments || segments.length < 2.
Das Array wird bei Änderungen nicht automatisch neu übergeben. Lies segments nach jedem resize-Ereignis bzw. jeder Media-Query-Änderung erneut aus, statt eine alte Referenz zu behalten.
Zum Testen ohne faltbares Gerät bieten die Chrome DevTools im Geräte-Modus eine Emulation faltbarer Geräte (z. B. „Asus Zenbook Fold“ oder „Surface Duo“).

Siehe auch

Viewport Viewport.segments Window.visualViewport DOMRect Window.matchMedia() TimeEvent.view