Recomposed
Pager

Jetpack Compose: Pager verstehen

Oct 30, 2026 · 5 min read

Jetpack Compose: Pager verstehen

Was Pager wirklich ist

HorizontalPager und VerticalPager sind die Composables hinter einer wischbaren, einrastenden Abfolge von vollformatigen Seiten: Onboarding-Screens, Bildkarussells und Tab-Inhalte, die gleiten statt zwischen Screens zu schneiden. Jede Seite ist ein eigenes Composable; der Pager ordnet sie nebeneinander an und übernimmt die Drag-/Fling-Geste, die zwischen ihnen wechselt.

rememberPagerState(pageCount = { ... }) erzeugt den PagerState, der das Ganze steuert. Dieser State meldet zurück, wo der Nutzer sich befindet, nicht nur welche Seite, und genau diese Unterscheidung, nicht das Layout selbst, ist das Thema dieses Beitrags.

Die Intuition

Wer Pager wie eine Tab-Zeile behandelt, geht davon aus, dass er nur mitteilt, welche Seite ausgewählt ist. TabRows selectedTabIndex funktioniert genau so: einfach ein Integer, der von 0 auf 1 springt. Baut man einen Seitenübergang auf dieser gleichen Annahme auf, rastet er ein statt zu gleiten, weil man genau den State-Teil wegwirft, der einen flüssigen Übergang überhaupt erst möglich macht.

  • pagerState.currentPage ist bereits die nächstgelegene Seite zu dem Punkt, an dem der Pager sich aktuell befindet, auch mitten im Drag. Der Wert springt in dem Moment, in dem man die Hälfte zwischen zwei Seiten überschreitet, nicht erst wenn der Drag oder Fling tatsächlich endet.
  • pagerState.currentPageOffsetFraction ist der Teil, den currentPage wegwirft: ein kontinuierlicher Float, grob zwischen -0.5 und 0.5, der angibt, wie weit man sich über currentPage hinaus in Richtung der vorherigen (<0) oder nächsten (>0) Seite bewegt hat.
  • Jeder einzelne Frame eines Drags liefert einen anderen Offset-Wert. Genau dieses Signal liest man aus, um eine Karte zu skalieren, einen Nachbarn ein- oder auszublenden oder einen Indikator synchron mit dem Finger zu morphen, nicht currentPage allein, dem jedes "wie weit" fehlt.

Pager trifft außerdem Layout-Entscheidungen aus genau diesem State: pageSize bestimmt, wie viel von jeder Seite sichtbar ist, pageSpacing legt den Abstand zwischen den Seiten fest, und contentPadding steuert, wie viel eines Nachbarn am Rand hereinragt. Alle drei werden einmal pro Seite gemessen und ändern sich nicht mit der Scroll-Position. Nur der Offset-Wert wird in jedem Frame aktualisiert.

Konkretes Beispiel: den Offset lesen, um eine Karte zu skalieren

val pagerState = rememberPagerState(pageCount = { 6 })
 
HorizontalPager(
    state = pagerState,
    modifier = Modifier.fillMaxWidth(),
    contentPadding = PaddingValues(horizontal = 64.dp),
) { page ->
    Card(
        modifier = Modifier
            .graphicsLayer {
                // Vorzeichenbehafteter Abstand, in Seitenbreiten, von dieser
                // Seite zum eingerasteten Slot von currentPage. Genau 0f,
                // wenn diese Seite die dort eingerastete ist, wächst
                // Richtung ±1f, solange ein Nachbar noch eine volle
                // Seitenbreite davon entfernt ist.
                val pageOffset =
                    (pagerState.currentPage - page + pagerState.currentPageOffsetFraction)
                        .absoluteValue
                val scale = lerp(0.7f, 1f, 1 - pageOffset.coerceIn(0f, 1f))
                scaleX = scale
                scaleY = scale
            }
            .fillMaxWidth()
            .height(240.dp)
    ) { /* ... */ }
}

currentPage - page liefert für jede Seite den ganzzahligen Abstand zum eingerasteten Slot von currentPage. Addiert man currentPageOffsetFraction dazu, wird daraus ein kontinuierlicher, vorzeichenbehafteter Abstand, der in jedem Frame des Drags aktualisiert wird, statt nur dann, wenn eine Seite einrastet. pageOffset == 0f bedeutet "diese Seite ist gerade jetzt die in diesem Slot eingerastete", ±1f bedeutet "eine volle Seitenbreite davon entfernt". Dass der Slot hier zentriert aussieht, liegt nur am symmetrischen contentPadding; der Wert selbst weiß nicht, wo auf dem Bildschirm dieser Slot liegt.

Dieser kontinuierliche Wert ist das, was braucht. Füttert man stattdessen nur currentPage, springt die Skalierung in Stufen, statt dem Finger zu folgen.

Probier es aus: Zieh die Karten unten und beobachte, wie currentPage und der Offset live aktualisiert werden, inklusive des Zurückschnappens beim Loslassen.

currentPage: 2 offset: +0.00

current page 2, offset 0.00, every card's offset +2.00, +1.00, +0.00, -1.00, -2.00
0+2.00
1+1.00
2+0.00
3-1.00
4-2.00

every card's offset

card 0: +2.00

card 1: +1.00

card 2: +0.00

card 3: -1.00

card 4: -2.00

drag the cards

FIG. 01
Der Pager wird auf einem echten Gerät gezogen, wobei jede benachbarte Karte beim Annähern an den eingerasteten Slot von currentPage größer wird und beim Wegrutschen kleiner, synchron mit dem Finger. Die Debug-Anzeige darunter zeigt currentPage, settledPage, targetPage, currentPageOffsetFraction und isScrollInProgress live beim Aktualisieren.

Weitere Fälle: derselbe Offset, anders gelesen

Der Offset-Wert taucht überall auf, wo sich ein Wischen kontinuierlich anfühlen soll, nicht nur in den eigenen Draw-Serien-Beiträgen dieses Blogs:

  • Ein Layout mit durchblickendem Nachbarn liest contentPadding und pageSpacing, um zu bestimmen, wie viel der nächsten Seite im Ruhezustand sichtbar ist, und liest dann currentPageOffsetFraction, um diesen Streifen beim Ziehen zu verschieben/skalieren.
  • Ein morphender Seitenindikator liest denselben Wert, um die Form eines Punkts in die nächste überzublenden, statt zwischen zwei statischen Zuständen umzuschalten.
  • Ein Onboarding-Flow skaliert und blendet die Illustration des aktuellen Schritts herunter, während der nächste hineinskaliert, basierend auf demselben Wert, statt zwischen zwei statischen Screens zu kreuzblenden.
  • Ein Story-Viewer (Instagram, WhatsApp Status) verkleinert und verdunkelt die ausgehende Story, während die eingehende beim Wischen auf volle Größe skaliert, statt direkt von der einen zur anderen zu schneiden.
  • Ein Foto-Karussell nutzt genau dieselbe Skalierung-nach-Offset-Formel wie im konkreten Beispiel oben, nur mit Fotos statt nummerierter Karten.

Unterschiedliche Optik, derselbe zugrunde liegende Wert: currentPage, currentPageOffsetFraction und der Pro-Seite-Abstand, den die Formel oben berechnet.

Das Fundamentale

Das ist kontinuierlicher Scroll-Fortschritt: Der State einer Geste wird als Float dargestellt, der in jedem Frame aktualisiert wird, in dem die Geste läuft, nicht nur als diskretes "vorher" und "nachher".

currentPage ist der Anker. currentPageOffsetFraction ist der Fortschritt Richtung nächstem Anker. Zusammen sind sie ein reichhaltigeres Signal als jeder für sich allein.

pagerState.isScrollInProgress verrät, wann dieser kontinuierliche Wert tatsächlich relevant ist: true, während ein Drag, Fling oder programmatisches Scrollen läuft, false, sobald es zur Ruhe kommt.

Anderswo: dasselbe Fundamentale, anderes Framework

  • Androids View-basiertes ViewPager/ViewPager2: der direkte Vorfahre genau dieses Modells. onPageScrolled(position, positionOffset, positionOffsetPixels) liefert eine ganzzahlige Seite und einen [0, 1)-Float-Offset, dieselbe zweiteilige Form, die currentPage/currentPageOffsetFraction in Compose weiterführt.
  • SwiftUIs scrollTransition: Innerhalb eines seitenartigen ScrollView oder TabView liefert die Phase, die jedem Element übergeben wird, einen kontinuierlichen Float, während dieses Element den Viewport durchquert, nicht nur einen "welche Seite"-Index. Derselbe zweiteilige Wert wie bei currentPage/currentPageOffsetFraction, nur pro Element statt pro Pager gemeldet.
  • CSS scroll-gesteuerte Animationen: animation-timeline: scroll() koppelt den Fortschritt einer Animation direkt an die Scroll-Position statt an die Zeit. Die Animation wird zu einer kontinuierlichen Funktion davon, wie weit man gescrollt hat, genau wie beim Steuern von scaleX/scaleY über currentPageOffsetFraction.
  • Swiper.js (die Web-Karussell-Bibliothek): stellt pro Folie einen progress-Wert bereit, grob zwischen -1 und 1, um genau diese Art von Skalierungs-/Parallax-Effekt zu bauen, während Folien die Mitte durchlaufen.

Edge Cases

  • currentPage kann mehr als einen Index überspringen. Ein schneller Fling kann den Pager über mehrere Seiten hinweg tragen, bevor er zur Ruhe kommt; schreib keinen Übergangscode, der davon ausgeht, dass sich currentPage zwischen Frames immer nur um ±1 ändert. Lies pagerState.targetPage, wenn du wissen musst, wo dieser Fling landen wird, bevor er dort ankommt.
  • currentPage vs. settledPage. currentPage wird während eines Drags oder Flings kontinuierlich aktualisiert, einschließlich jeder Zwischenseite, die ein schneller Fling durchläuft. settledPage aktualisiert sich erst, wenn der Pager tatsächlich zur Ruhe kommt. Lies settledPage, wenn die Frage lautet "hat der Nutzer den Seitenwechsel abgeschlossen", und currentPage, wenn es "wo befindet sich der Pager gerade jetzt" lautet.
  • pageSpacing und contentPadding wirken zusammen. Padding bestimmt, wie viel benachbarte Seiten von den Container-Rändern aus hereinragen; Spacing fügt zusätzlich einen Abstand zwischen den Seiten ein. Das eine zu setzen, ohne das andere zu berücksichtigen, ist eine häufige Ursache dafür, dass Seiten näher beieinander oder weiter voneinander entfernt wirken als beabsichtigt.
  • Das Vorzeichen ist nicht wörtlich "links" und "rechts". currentPageOffsetFraction ist negativ Richtung Layout-Anfang und positiv Richtung Layout-Ende, und Anfang/Ende sind logische Richtungen. In einem Links-nach-Rechts-Layout bedeutet das zwar negativ-links, positiv-rechts, aber wechselt man zu einer RTL-Locale oder setzt reverseLayout = true, tauschen Anfang/Ende auf dem Bildschirm die Seiten, und das Vorzeichen tauscht mit ihnen. Code, der hartcodiert "positiv bedeutet, die Karte verschwindet nach links", bricht unter RTL.

Das Mentalmodell, das man wirklich nutzen sollte

Frag nicht "welche Seite ist ausgewählt". Frag "wo genau, als kontinuierlicher Wert, befindet sich der Pager gerade jetzt", und lies currentPage + currentPageOffsetFraction zusammen, um das zu beantworten.

Keep reading

Related reads

Neue Beiträge direkt in dein Postfach