Recomposed
Pager

Jetpack Compose : comprendre Pager

Oct 30, 2026 · 6 min read

Jetpack Compose : comprendre Pager

Ce qu'est réellement Pager

HorizontalPager et VerticalPager sont les composables à l'origine d'une séquence de pages pleine taille que l'on peut faire glisser et qui s'alignent automatiquement : écrans d'onboarding, carrousels d'images, et contenu d'onglets qui glisse au lieu de passer brutalement d'un écran à l'autre. Chaque page est son propre composable ; le pager les dispose côte à côte et gère le geste de glissement/lancer (drag/fling) qui permet de passer de l'une à l'autre.

rememberPagerState(pageCount = { ... }) crée le PagerState qui pilote tout cela. Cet état indique où se trouve l'utilisateur, pas seulement quelle page est affichée, et c'est cette distinction, plus que la disposition elle-même, qui est au cœur du reste de cet article.

L'intuition

Si vous traitez Pager comme une rangée de Tab, vous allez supposer qu'il vous indique seulement quelle page est sélectionnée. C'est ainsi que fonctionne selectedTabIndex de TabRow : un simple entier qui passe de 0 à 1. Construisez une transition de page sur cette même hypothèse, et elle s'enclenchera brusquement au lieu de glisser, parce que vous jetez justement la portion d'état qui rend une transition fluide possible.

  • pagerState.currentPage correspond déjà à la page la plus proche de l'endroit où se trouve actuellement le pager, y compris en plein glissement. Elle bascule à l'instant où vous franchissez le point médian entre deux pages, pas seulement lorsque le glissement ou le lancer se termine réellement.
  • pagerState.currentPageOffsetFraction est la part que currentPage laisse de côté : un float continu, grosso modo entre -0.5 et 0.5, qui indique de combien vous vous êtes déplacé par rapport à currentPage, vers la page précédente (<0) ou suivante (>0).
  • Chaque frame d'un glissement renvoie une fraction de décalage différente. C'est le signal à lire pour mettre à l'échelle une carte, estomper une voisine, ou faire évoluer un indicateur au rythme du doigt de l'utilisateur, pas currentPage seul, qui ne contient aucune notion de « à quel point ».

Pager prend également des décisions de disposition à partir de ce même état : pageSize contrôle la part visible de chaque page, pageSpacing définit l'espace entre les pages, et contentPadding contrôle la portion d'une page voisine qui apparaît depuis le bord. Ces trois valeurs sont mesurées une seule fois par page et ne changent pas avec la position de défilement. Seule la fraction de décalage se met à jour à chaque frame.

Exemple concret : lire le décalage pour mettre une carte à l'échelle

val pagerState = rememberPagerState(pageCount = { 6 })
 
HorizontalPager(
    state = pagerState,
    modifier = Modifier.fillMaxWidth(),
    contentPadding = PaddingValues(horizontal = 64.dp),
) { page ->
    Card(
        modifier = Modifier
            .graphicsLayer {
                // Distance signée, en largeurs de page, entre cette page et
                // l'emplacement stabilisé de currentPage. Exactement 0f lorsque
                // cette page est celle qui y est stabilisée, et qui croît vers
                // ±1f tandis qu'une page voisine est encore à une largeur de
                // page complète de cet emplacement.
                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 donne, pour chaque page, sa distance entière par rapport à l'emplacement stabilisé de currentPage. En y ajoutant currentPageOffsetFraction, on obtient une distance signée continue, qui se met à jour à chaque frame du glissement au lieu de ne changer que lorsqu'une page se stabilise. pageOffset == 0f signifie « cette page est actuellement celle qui est stabilisée dans cet emplacement », ±1f signifie « à une largeur de page complète de celui-ci ». L'emplacement semble seulement centré ici en raison du contentPadding symétrique ; la fraction elle-même n'a aucune idée de l'endroit de l'écran où se trouve cet emplacement.

Cette valeur continue est ce dont a besoin. Donnez-lui currentPage seul à la place, et l'échelle avancera par sauts plutôt que de suivre le doigt.

Essayez : faites glisser les cartes ci-dessous et observez currentPage ainsi que le décalage se mettre à jour en temps réel, y compris le retour en place au relâchement.

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
Glissement du pager sur un appareil réel : chaque carte voisine s'agrandit à mesure qu'elle approche de l'emplacement stabilisé de currentPage, puis se réduit en s'éloignant, en synchronisation avec le doigt. L'affichage de débogage en dessous montre currentPage, settledPage, targetPage, currentPageOffsetFraction et isScrollInProgress se mettre à jour en direct.

D'autres cas : le même décalage, lu différemment

La fraction de décalage apparaît partout où un balayage doit paraître continu, et pas seulement dans les articles de la série « Draw » de ce blog :

  • Une disposition qui laisse apparaître un aperçu de la page voisine lit contentPadding et pageSpacing pour décider de la portion de la page suivante visible au repos, puis lit currentPageOffsetFraction pour faire glisser/mettre à l'échelle cette tranche pendant que l'utilisateur fait glisser l'écran.
  • Un indicateur de page qui se métamorphose lit cette même fraction pour fondre la forme d'un point dans la suivante au lieu de basculer entre deux états statiques.
  • Un flux d'onboarding réduit et estompe l'illustration de l'étape en cours tandis que la suivante s'agrandit, en se basant sur cette même fraction, au lieu d'effectuer un fondu croisé entre deux écrans statiques.
  • Une visionneuse de stories (Instagram, WhatsApp Status) réduit et assombrit la story sortante tandis que celle qui entre s'agrandit jusqu'à sa taille complète pendant le balayage, plutôt que de passer brutalement de l'une à l'autre.
  • Un carrousel de photos réutilise exactement la même formule de mise à l'échelle par décalage que dans l'exemple concret ci-dessus, simplement avec des photos à la place des cartes numérotées.

Visuel différent, mais la même lecture sous-jacente : currentPage, currentPageOffsetFraction, et la distance par page que la formule ci-dessus calcule.

Le concept fondamental

Il s'agit d'une progression de défilement continue : l'état d'un geste est représenté par un float qui se met à jour à chaque frame pendant que le geste est en cours, et non par un simple « avant » et « après » discrets.

currentPage est l'ancre. currentPageOffsetFraction est la progression vers l'ancre suivante. Ensemble, ils forment un signal plus riche que chacun pris isolément.

pagerState.isScrollInProgress indique quand cette lecture continue compte réellement : vrai pendant qu'un glissement, un lancer, ou un défilement programmatique est en cours, faux une fois qu'il se stabilise.

Ailleurs : même principe fondamental, framework différent

  • Le ViewPager/ViewPager2 basé sur les Views d'Android : l'ancêtre direct exact de ce modèle. onPageScrolled(position, positionOffset, positionOffsetPixels) vous fournit une page entière et un décalage flottant [0, 1), la même structure en deux parties que currentPage/currentPageOffsetFraction perpétue dans Compose.
  • Le scrollTransition de SwiftUI : à l'intérieur d'une ScrollView ou d'une TabView en mode page, la phase transmise à chaque élément est un float continu au fur et à mesure que cet élément traverse la zone visible, pas seulement un index « quelle page ». La même lecture en deux parties que currentPage/currentPageOffsetFraction, simplement rapportée par élément plutôt que par pager.
  • Les animations pilotées par le défilement en CSS : animation-timeline: scroll() relie la progression d'une animation directement à la position de défilement plutôt qu'au temps. L'animation devient une fonction continue de la distance parcourue en défilement, exactement comme piloter scaleX/scaleY à partir de currentPageOffsetFraction.
  • Swiper.js (la bibliothèque de carrousel web) : expose une valeur progress par diapositive, grosso modo entre -1 et 1, pour construire exactement ce genre d'effet d'échelle/parallaxe lorsque les diapositives passent par le centre.

Cas limites

  • currentPage peut sauter plus d'un index. Un lancer rapide peut faire passer le pager par plusieurs pages avant de se stabiliser ; n'écrivez pas de code de transition qui suppose que currentPage ne change jamais que de ±1 entre deux frames. Lisez pagerState.targetPage si vous avez besoin de savoir où ce lancer va atterrir avant qu'il n'y arrive.
  • currentPage contre settledPage. currentPage se met à jour en continu pendant un glissement ou un lancer, y compris pour chaque page intermédiaire traversée par un lancer rapide. settledPage ne se met à jour qu'une fois que le pager est réellement arrivé au repos. Lisez settledPage quand la question est « l'utilisateur a-t-il fini de changer de page », et currentPage quand c'est « où se trouve le pager en ce moment ».
  • pageSpacing et contentPadding interagissent. Le padding contrôle la portion des pages voisines qui apparaît depuis les bords du conteneur ; l'espacement ajoute en plus un vide entre les pages. Définir l'un sans tenir compte de l'autre est une cause fréquente de pages qui paraissent plus rapprochées ou plus éloignées que prévu.
  • Le signe n'est pas littéralement « gauche » et « droite ». currentPageOffsetFraction est négatif vers le début de la disposition et positif vers sa fin, et début/fin sont des directions logiques. Dans une disposition de gauche à droite, cela signifie bien négatif-gauche, positif-droite, mais passez à une locale RTL ou définissez reverseLayout = true, et début/fin échangent leurs côtés à l'écran, donc le signe s'inverse avec eux. Un code qui code en dur « positif signifie que la carte sort par la gauche » se casse en RTL.

Le modèle mental à utiliser réellement

Ne demandez pas « quelle page est sélectionnée ». Demandez « où se trouve exactement le pager en ce moment, en tant que valeur continue », et lisez currentPage + currentPageOffsetFraction ensemble pour y répondre.

Keep reading

Related reads

Recevez les nouveaux articles par e-mail