Recomposed
Pager

Jetpack Compose: Entendendo o Pager

Oct 30, 2026 · 5 min read

Jetpack Compose: Entendendo o Pager

O que o Pager realmente é

HorizontalPager e VerticalPager são os composables por trás de uma sequência de páginas em tamanho real, deslizáveis e com encaixe: telas de onboarding, carrosséis de imagens e conteúdo de abas que deslizam em vez de cortar entre telas. Cada página é seu próprio composable; o pager as organiza lado a lado e lida com o gesto de arrastar/soltar que move entre elas.

rememberPagerState(pageCount = { ... }) cria o PagerState que o conduz. Esse estado relata onde o usuário está, não apenas qual página, e essa distinção, não o layout em si, é o assunto do restante deste post.

A intuição

Trate o Pager como uma linha de Tab e você vai assumir que ele só informa qual página está selecionada. O selectedTabIndex do TabRow funciona assim: apenas um inteiro que salta de 0 para 1. Construa uma transição de página sobre essa mesma suposição e ela vai encaixar em vez de deslizar suavemente, porque você está descartando a única parte do estado que torna uma transição suave possível.

  • pagerState.currentPage já é a página mais próxima de onde o pager está atualmente, incluindo no meio de um arrasto. Ele muda no instante em que você cruza o ponto médio entre duas páginas, não quando o arrasto ou o soltar de fato termina.
  • pagerState.currentPageOffsetFraction é a parte que currentPage descarta: um float contínuo, aproximadamente de -0.5 a 0.5, indicando quão longe você se moveu além de currentPage em direção à página anterior (<0) ou à próxima (>0).
  • Cada frame de um arrasto reporta uma fração de deslocamento diferente. Esse é o sinal que você lê para escalar um card, esmaecer um vizinho ou transformar um indicador em sincronia com o dedo do usuário, não currentPage isoladamente, que não tem nenhum "quão longe" nele.

O Pager também toma decisões de layout a partir desse mesmo estado: pageSize controla quanto de cada página é visível, pageSpacing define o espaço entre páginas, e contentPadding controla quanto de um vizinho aparece pela borda. Os três são medidos uma vez por página e não mudam com a posição de rolagem. Apenas a fração de deslocamento é atualizada a cada frame.

Exemplo concreto: lendo o deslocamento para escalar um card

val pagerState = rememberPagerState(pageCount = { 6 })
 
HorizontalPager(
    state = pagerState,
    modifier = Modifier.fillMaxWidth(),
    contentPadding = PaddingValues(horizontal = 64.dp),
) { page ->
    Card(
        modifier = Modifier
            .graphicsLayer {
                // Distância com sinal, em larguras de página, desta página até
                // o slot assentado de currentPage. Exatamente 0f quando esta página
                // é a que está assentada ali, crescendo até ±1f conforme um
                // vizinho ainda está a uma largura de página completa de distância.
                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 dá a distância inteira de cada página em relação ao slot assentado de currentPage. Somar currentPageOffsetFraction transforma isso numa distância contínua com sinal, atualizada a cada frame do arrasto, em vez de apenas quando uma página se assenta. pageOffset == 0f significa "esta página é a que está assentada nesse slot agora", ±1f significa "a uma largura de página completa de distância dele". O slot só parece centralizado aqui por causa do contentPadding simétrico; a própria fração não tem ideia de onde na tela esse slot está.

Esse valor contínuo é o que precisa. Alimente-o apenas com currentPage em vez disso, e a escala salta em etapas em vez de acompanhar o dedo.

Experimente: arraste os cards abaixo e observe currentPage e o deslocamento atualizarem em tempo real, incluindo o retorno de encaixe ao soltar.

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
Arrastando o pager em um dispositivo real, com cada card vizinho aumentando de escala conforme se aproxima do slot assentado de currentPage e diminuindo conforme se afasta, em sincronia com o dedo. O painel de depuração abaixo mostra currentPage, settledPage, targetPage, currentPageOffsetFraction e isScrollInProgress atualizando em tempo real.

Mais casos: o mesmo deslocamento, lido de forma diferente

A fração de deslocamento aparece em qualquer lugar onde um swipe precisa parecer contínuo, não apenas nos próprios posts da série Draw deste blog:

  • Um layout de vizinho que espia lê contentPadding e pageSpacing para decidir quanto da próxima página aparece em repouso, e então lê currentPageOffsetFraction para deslizar/escalar essa fatia enquanto o usuário arrasta.
  • Um indicador de página com transformação lê a mesma fração para misturar a forma de um ponto na do próximo, em vez de trocar entre dois estados estáticos.
  • Um fluxo de onboarding escala e esmaece a ilustração da etapa atual enquanto a próxima aumenta de escala, a partir da mesma fração, em vez de fazer um crossfade entre duas telas estáticas.
  • Um visualizador de stories (Instagram, WhatsApp Status) reduz e escurece a story que está saindo enquanto a que está entrando aumenta até o tamanho total conforme você arrasta, em vez de cortar diretamente de uma para a outra.
  • Um carrossel de fotos reutiliza exatamente a fórmula de escala por deslocamento do exemplo concreto acima, apenas com fotos no lugar dos cards numerados.

Visual diferente, mesma leitura subjacente: currentPage, currentPageOffsetFraction, e a distância por página que aquela fórmula acima calcula.

O fundamental

Isto é progresso contínuo de rolagem: o estado de um gesto é representado como um float que se atualiza a cada frame enquanto o gesto está em andamento, não apenas um "antes" e "depois" discretos.

currentPage é a âncora. currentPageOffsetFraction é o progresso em direção à próxima âncora. Juntos, eles são um sinal mais rico do que qualquer um dos dois isoladamente.

pagerState.isScrollInProgress informa quando essa leitura contínua realmente importa: verdadeiro enquanto um arrasto, um soltar ou uma rolagem programática está em andamento, falso uma vez que se assenta.

Em outros lugares: mesmo fundamento, framework diferente

  • ViewPager/ViewPager2 baseados em View do Android: o ancestral direto desse exato modelo. onPageScrolled(position, positionOffset, positionOffsetPixels) entrega uma página inteira e um float de deslocamento [0, 1), a mesma forma em duas partes que currentPage/currentPageOffsetFraction continua no Compose.
  • scrollTransition do SwiftUI: dentro de um ScrollView ou TabView no estilo de página, a fase que ele entrega a cada item é um float contínuo conforme esse item cruza a viewport, não apenas um índice de "qual página". Mesma leitura em duas partes que currentPage/currentPageOffsetFraction, só que relatada por item em vez de por pager.
  • Animações de rolagem do CSS: animation-timeline: scroll() liga o progresso de uma animação diretamente à posição de rolagem em vez do tempo. A animação se torna uma função contínua de quanto você rolou, exatamente como conduzir scaleX/scaleY a partir de currentPageOffsetFraction.
  • Swiper.js (a biblioteca de carrossel para web): expõe um valor progress por slide, aproximadamente de -1 a 1, para construir exatamente esse tipo de efeito de escala/paralaxe conforme os slides passam pelo centro.

Casos extremos

  • currentPage pode saltar mais de um índice. Um fling rápido pode levar o pager por várias páginas antes de se assentar; não escreva código de transição que assuma que currentPage só muda em ±1 entre frames. Leia pagerState.targetPage se precisar saber onde esse fling vai parar antes que ele chegue lá.
  • currentPage vs settledPage. currentPage é atualizado continuamente durante um arrasto ou fling, incluindo toda página intermediária por onde um fling rápido passa. settledPage só é atualizado quando o pager de fato chega ao repouso. Leia settledPage quando a pergunta for "o usuário terminou de mudar de página", e currentPage quando for "onde o pager está agora".
  • pageSpacing e contentPadding interagem. O padding controla quanto das páginas vizinhas aparece pelas bordas do contêiner; o spacing adiciona um espaço entre páginas por cima disso. Definir um sem considerar o outro é uma fonte comum de páginas parecerem mais próximas ou mais distantes do que o pretendido.
  • O sinal não é literalmente "esquerda" e "direita". currentPageOffsetFraction é negativo em direção ao início do layout e positivo em direção ao fim, e início/fim são direções lógicas. Em um layout da esquerda para a direita isso de fato significa negativo-esquerda, positivo-direita, mas mude para um locale RTL ou defina reverseLayout = true e início/fim trocam de lado na tela, então o sinal troca junto. Código que fixa "positivo significa que o card sai pela esquerda" quebra sob RTL.

Modelo mental para realmente usar

Não pergunte "qual página está selecionada". Pergunte "onde exatamente, como um valor contínuo, o pager está agora", e leia currentPage + currentPageOffsetFraction juntos para responder.

Keep reading

Related reads

Receba novos posts no seu e-mail