Viewport.segments — Eigenschaft · JavaScript-Referenz

Signatur

get Viewport.segments

Beschreibung

Die Eigenschaft segments der Viewport-Schnittstelle (erreichbar über window.viewport) gehört zur Viewport Segments API. Sie beschreibt, wie der sichtbare Bereich eines Fensters auf Geräten mit mehreren Bildschirmbereichen aufgeteilt ist, etwa bei faltbaren Smartphones oder Geräten mit zwei Displays, bei denen ein Scharnier oder ein Falz den Viewport in logisch getrennte Bereiche teilt.

Jedes Element des zurückgegebenen Arrays ist ein DOMRect mit x, y, width und height relativ zum Viewport. Die Segmente sind von links nach rechts bzw. von oben nach unten sortiert. Aus den Rechtecken lässt sich auch die Lage und Breite des Scharniers ablesen, nämlich als Lücke zwischen zwei benachbarten Segmenten.

Brauchen wirst du die Eigenschaft, wenn ein Layout per JavaScript an die Faltung angepasst werden soll, zum Beispiel für eine Listen-Detail-Ansicht mit einem Bereich pro Segment oder damit Dialoge und Videos nicht über den Falz hinweg dargestellt werden. Für reine Layout-Anpassungen reicht oft CSS: Es gibt die Media Features horizontal-viewport-segments und vertical-viewport-segments sowie die Umgebungsvariablen env(viewport-segment-width 0 0), env(viewport-segment-left 1 0) usw.

Der Wert ist eine Momentaufnahme. Ändert sich die Haltung des Geräts, etwa beim Auf- oder Zuklappen, beim Drehen oder beim Ändern der Fenstergröße, musst du segments erneut auslesen. Ein eigenes Change-Event gibt es an Viewport nicht. Üblich ist, auf resize oder auf das change-Event einer passenden matchMedia-Abfrage zu reagieren.

Rückgabewert

Typ

DOMRect[] | null

Beschreibung

Ein eingefrorenes Array von DOMRect-Objekten, ein Eintrag pro Viewport-Segment. Ist der Viewport nicht geteilt, enthält das Array je nach Umsetzung nur einen Eintrag. In Kontexten ohne Segment-Informationen, zum Beispiel in eingebetteten Frames, kann null zurückkommen.

Beispiele

Segmente auslesen und ausgeben

const segments = window.viewport?.segments ?? null;

if (!segments) {
  console.log('Keine Segment-Informationen verfügbar');
} else {
  segments.forEach((rect, i) => {
    console.log(`Segment ${i}: x=${rect.x}, y=${rect.y}, ${rect.width}×${rect.height}`);
  });
}

Segment 0: x=0, y=0, 540×720 Segment 1: x=560, y=0, 540×720

Scharnier-Position und Ausrichtung berechnen

const getFoldInfo = () => {
  const segs = window.viewport?.segments;
  if (!segs || segs.length < 2) return { folded: false };

  const [a, b] = segs;
  // Nebeneinander liegende Segmente = vertikales Scharnier
  const sideBySide = b.x >= a.right;
  return sideBySide
    ? { folded: true, orientation: 'vertikal', hingeX: a.right, hingeWidth: b.left - a.right }
    : { folded: true, orientation: 'horizontal', hingeY: a.bottom, hingeHeight: b.top - a.bottom };
};

console.log(getFoldInfo());

{ folded: true, orientation: 'vertikal', hingeX: 540, hingeWidth: 20 }

Layout bei Haltungswechsel aktualisieren

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

const applyLayout = () => {
  const segs = window.viewport?.segments ?? [];
  app.dataset.layout = segs.length > 1 ? 'dual' : 'single';
  if (segs.length > 1) {
    // Listenbereich exakt auf das erste Segment legen
    app.style.setProperty('--list-width', `${segs[0].width}px`);
  }
};

// Kein eigenes Event an Viewport: auf Media-Query-Wechsel und resize reagieren
const mq = matchMedia('(horizontal-viewport-segments: 2), (vertical-viewport-segments: 2)');
mq.addEventListener('change', applyLayout);
window.addEventListener('resize', applyLayout);
applyLayout();

// Wichtig · Fallstricke

Kompatibilität: Die Funktion ist experimentell und steht derzeit nur in Chromium-Browsern (Chrome/Edge ab etwa Version 138) zur Verfügung. Firefox und Safari unterstützen sie nicht. Prüfe deshalb vorher mit 'viewport' in window bzw. mit optionaler Verkettung (window.viewport?.segments).
Kein Live-Wert: Das Array ist eingefroren und ändert sich nicht von selbst. Nach einer Haltungsänderung oder einem resize musst du es neu auslesen.
null oder ein einzelnes Segment: Behandle beide Fälle so, als wäre der Viewport nicht geteilt. Verlass dich nicht darauf, dass immer mindestens zwei Einträge vorhanden sind.
Bevorzugt CSS verwenden: Reine Layout-Anpassungen lassen sich mit @media (horizontal-viewport-segments: 2) und env(viewport-segment-*) ohne JavaScript und ohne sichtbaren Layout-Sprung umsetzen.
Testen: Die Chrome DevTools können im Geräte-Modus faltbare Geräte (z. B. „Surface Duo“, „Galaxy Z Fold“) mit Dual-Screen-Modus nachbilden.

Siehe auch

Viewport Window.viewport DOMRect Window.matchMedia() VisualViewport ScreenDetails.screens