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.currentPagejá é 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 quecurrentPagedescarta: um float contínuo, aproximadamente de-0.5a0.5, indicando quão longe você se moveu além decurrentPageem 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
currentPageisoladamente, 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.00every 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
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ê
contentPaddingepageSpacingpara decidir quanto da próxima página aparece em repouso, e então lêcurrentPageOffsetFractionpara 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/ViewPager2baseados 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 quecurrentPage/currentPageOffsetFractioncontinua no Compose.scrollTransitiondo SwiftUI: dentro de umScrollViewouTabViewno 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 quecurrentPage/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 conduzirscaleX/scaleYa partir decurrentPageOffsetFraction. - Swiper.js (a biblioteca de carrossel para web): expõe um valor
progresspor slide, aproximadamente de-1a1, para construir exatamente esse tipo de efeito de escala/paralaxe conforme os slides passam pelo centro.
Casos extremos
currentPagepode 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 quecurrentPagesó muda em ±1 entre frames. LeiapagerState.targetPagese precisar saber onde esse fling vai parar antes que ele chegue lá.currentPagevssettledPage.currentPageé atualizado continuamente durante um arrasto ou fling, incluindo toda página intermediária por onde um fling rápido passa.settledPagesó é atualizado quando o pager de fato chega ao repouso. LeiasettledPagequando a pergunta for "o usuário terminou de mudar de página", ecurrentPagequando for "onde o pager está agora".pageSpacingecontentPaddinginteragem. 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 definareverseLayout = truee 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.



