Recomposed
Pager

Jetpack Compose: Pager 제대로 이해하기

Oct 30, 2026 · 1 min read

Jetpack Compose: Pager 제대로 이해하기

Pager가 실제로 무엇인지

HorizontalPager와 VerticalPager는 스와이프로 넘기고 스냅되는 전체 크기 페이지 시퀀스 뒤에 있는 컴포저블로, 온보딩 화면, 이미지 캐러셀, 화면을 자르지 않고 슬라이드로 넘어가는 탭 콘텐츠 등에 쓰입니다. 각 페이지는 하나의 컴포저블이며, Pager는 이들을 나란히 배치하고 페이지 사이를 이동시키는 드래그/플링 제스처를 처리합니다.

rememberPagerState(pageCount = { ... })는 이를 구동하는 PagerState를 만듭니다. 이 상태는 어느 페이지인지뿐만 아니라 사용자가 어디에 있는지까지 알려주며, 이 글 전체가 다루는 것은 바로 이 차이이지 레이아웃 자체가 아닙니다.

직관적으로 이해하기

Pager를 Tab 행처럼 취급하면 어느 페이지가 선택되었는지만 알려준다고 생각하게 됩니다. TabRow의 selectedTabIndex는 그런 식으로 동작합니다. 그냥 0에서 1로 뛰어넘는 정수일 뿐이죠. 같은 가정 위에 페이지 전환을 만들면 매끄럽게 미끄러지는 대신 뚝뚝 끊기게 되는데, 부드러운 전환을 가능하게 만드는 바로 그 상태값을 버리고 있기 때문입니다.

  • pagerState.currentPage는 드래그 중이든 아니든 Pager가 현재 위치한 지점에서 가장 가까운 페이지를 즉시 반영합니다. 드래그나 플링이 실제로 끝났을 때가 아니라, 두 페이지 사이의 중간 지점을 넘는 순간 바로 바뀝니다.
  • pagerState.currentPageOffsetFraction은 currentPage가 버리는 부분입니다. 대략 -0.5에서 0.5 사이의 연속적인 float 값으로, currentPage를 기준으로 이전 페이지(<0) 또는 다음 페이지(>0) 쪽으로 얼마나 이동했는지를 나타냅니다.
  • 드래그의 매 프레임마다 서로 다른 offset fraction이 보고됩니다. 카드를 스케일링하거나, 이웃 페이지를 페이드시키거나, 인디케이터를 사용자의 손가락 움직임에 맞춰 모핑하려면 바로 이 값을 읽어야 하며, "얼마나" 이동했는지에 대한 정보가 전혀 없는 currentPage 단독으로는 불가능합니다.

Pager는 이 같은 상태를 바탕으로 레이아웃 결정도 내립니다. pageSize는 각 페이지가 얼마나 보이는지를 제어하고, pageSpacing은 페이지 사이의 간격을 설정하며, contentPadding은 가장자리에서 이웃 페이지가 얼마나 살짝 보이는지를 제어합니다. 이 세 가지는 모두 페이지당 한 번만 측정되며 스크롤 위치에 따라 바뀌지 않습니다. offset fraction만이 매 프레임 갱신됩니다.

구체적인 예: offset을 읽어 카드 스케일링하기

val pagerState = rememberPagerState(pageCount = { 6 })
 
HorizontalPager(
    state = pagerState,
    modifier = Modifier.fillMaxWidth(),
    contentPadding = PaddingValues(horizontal = 64.dp),
) { page ->
    Card(
        modifier = Modifier
            .graphicsLayer {
                // 이 페이지에서 currentPage가 정착한 슬롯까지의
                // 부호 있는 거리(페이지 너비 단위). 이 페이지가
                // 바로 그 슬롯에 정착해 있을 때 정확히 0f이고,
                // 이웃 페이지가 거기서 한 페이지 너비만큼 떨어져
                // 있을수록 ±1f에 가까워진다.
                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는 각 페이지가 currentPage가 정착한 슬롯으로부터 얼마나 떨어져 있는지를 정수 거리로 알려줍니다. 여기에 currentPageOffsetFraction을 더하면 이 값이 연속적인 부호 있는 거리로 바뀌어, 페이지가 정착할 때만이 아니라 드래그의 매 프레임마다 갱신됩니다. pageOffset == 0f는 "이 페이지가 지금 바로 그 슬롯에 정착해 있다"는 뜻이고, ±1f는 "거기서 한 페이지 너비만큼 떨어져 있다"는 뜻입니다. 여기서 슬롯이 중앙에 있는 것처럼 보이는 이유는 단지 대칭적인 contentPadding 때문이며, fraction 값 자체는 그 슬롯이 화면 어디에 있는지 전혀 알지 못합니다.

이 연속적인 값이 바로 가 필요로 하는 값입니다. 대신 currentPage만 넣으면 스케일이 손가락을 따라가지 않고 계단식으로 뛰게 됩니다.

직접 해보세요: 아래 카드를 드래그해보면서 currentPage와 offset이 실시간으로 갱신되는 모습을, 손을 떼었을 때 다시 스냅되는 모습까지 함께 확인해보세요.

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
실제 기기에서 Pager를 드래그하는 모습으로, 각 이웃 카드가 currentPage가 정착한 슬롯에 가까워질수록 커지고 멀어질수록 작아지며 손가락 움직임과 동기화된다. 아래의 디버그 표시에는 currentPage, settledPage, targetPage, currentPageOffsetFraction, isScrollInProgress가 실시간으로 갱신되는 모습이 나타난다.

더 많은 사례: 같은 offset, 다르게 읽기

offset fraction은 이 블로그의 Draw 시리즈 포스트뿐 아니라, 스와이프가 연속적으로 느껴져야 하는 곳이라면 어디서든 등장합니다.

  • 이웃 페이지가 살짝 보이는 레이아웃은 contentPadding과 pageSpacing을 읽어 정지 상태에서 다음 페이지가 얼마나 보일지 결정한 다음, currentPageOffsetFraction을 읽어 사용자가 드래그할 때 그 조각을 슬라이드/스케일링합니다.
  • 모핑되는 페이지 인디케이터는 두 개의 정적 상태를 전환하는 대신, 같은 fraction을 읽어 한 점의 모양을 다음 점으로 블렌딩합니다.
  • 온보딩 플로우는 두 개의 정적 화면을 크로스페이드하는 대신, 같은 fraction을 기반으로 현재 단계의 일러스트를 축소/페이드시키면서 다음 단계의 일러스트를 확대합니다.
  • 스토리 뷰어(인스타그램, WhatsApp Status)는 하나에서 다른 하나로 바로 잘라내는 대신, 스와이프할 때 나가는 스토리를 축소하고 어둡게 하면서 들어오는 스토리를 원래 크기로 확대합니다.
  • 포토 캐러셀은 위 구체적인 예시의 scale-by-offset 공식을 숫자가 적힌 카드 대신 사진에 그대로 적용합니다.

시각적으로는 다르지만 근본적으로 읽는 것은 같습니다. currentPage, currentPageOffsetFraction, 그리고 위 공식이 계산하는 페이지별 거리입니다.

핵심 원리

이것이 바로 연속적인 스크롤 진행도입니다. 제스처의 상태는 단순히 "이전"과 "이후"라는 이분법적 값이 아니라, 제스처가 진행되는 매 프레임마다 갱신되는 float 값으로 표현됩니다.

currentPage는 기준점입니다. currentPageOffsetFraction은 다음 기준점을 향한 진행도입니다. 둘을 함께 쓰면 각각보다 더 풍부한 신호가 됩니다.

pagerState.isScrollInProgress는 이 연속적인 값이 실제로 중요한 순간을 알려줍니다. 드래그, 플링, 또는 프로그래밍적 스크롤이 진행 중이면 true이고, 정착하면 false입니다.

다른 곳에서: 같은 원리, 다른 프레임워크

  • Android의 View 기반 ViewPager/ViewPager2: 이 모델의 직접적인 조상입니다. onPageScrolled(position, positionOffset, positionOffsetPixels)는 정수 페이지와 [0, 1) 범위의 float offset을 건네주는데, 이는 Compose에서 currentPage/currentPageOffsetFraction으로 이어지는 바로 그 두 부분 구조입니다.
  • SwiftUI의 scrollTransition: 페이지 스타일의 ScrollView나 TabView 안에서, 각 항목에 건네지는 phase는 단순히 "어느 페이지인지" 인덱스가 아니라 그 항목이 뷰포트를 지나가는 동안의 연속적인 float 값입니다. currentPage/currentPageOffsetFraction과 같은 두 부분 구조이며, 다만 Pager 단위가 아니라 항목 단위로 보고됩니다.
  • CSS scroll-driven animations: animation-timeline: scroll()은 애니메이션의 진행도를 시간이 아니라 스크롤 위치에 직접 연결합니다. 애니메이션은 얼마나 스크롤했는지에 대한 연속적인 함수가 되며, 이는 currentPageOffsetFraction으로 scaleX/scaleY를 구동하는 것과 정확히 같은 방식입니다.
  • Swiper.js(웹 캐러셀 라이브러리): 슬라이드마다 대략 -1에서 1 사이의 progress 값을 제공하여, 슬라이드가 중앙을 지나갈 때 정확히 이런 종류의 스케일/패럴랙스 효과를 만들 수 있게 합니다.

엣지 케이스

  • currentPage는 한 인덱스 이상을 건너뛸 수 있습니다. 빠른 플링은 정착하기 전에 여러 페이지를 지나갈 수 있으므로, currentPage가 프레임 사이에 항상 ±1만큼만 바뀐다고 가정하는 전환 코드를 작성하지 마세요. 플링이 도착하기 전에 어디로 향할지 알아야 한다면 pagerState.targetPage를 읽으세요.
  • currentPage와 settledPage의 차이. currentPage는 드래그나 플링 중에 연속적으로 갱신되며, 빠른 플링이 지나가는 모든 중간 페이지를 포함합니다. settledPage는 Pager가 실제로 정지했을 때만 갱신됩니다. "사용자가 페이지 변경을 완료했는가"를 물을 때는 settledPage를 읽고, "Pager가 지금 어디에 있는가"를 물을 때는 currentPage를 읽으세요.
  • pageSpacing과 contentPadding은 상호작용합니다. 패딩은 컨테이너 가장자리에서 이웃 페이지가 얼마나 살짝 보이는지를 제어하고, spacing은 그 위에 페이지 사이의 간격을 추가합니다. 하나만 설정하고 다른 하나를 고려하지 않으면 페이지들이 의도한 것보다 더 가깝거나 멀게 보이는 흔한 원인이 됩니다.
  • 부호는 문자 그대로 "왼쪽"과 "오른쪽"을 의미하지 않습니다. currentPageOffsetFraction은 레이아웃의 시작 쪽으로는 음수, 끝 쪽으로는 양수이며, 시작/끝은 논리적인 방향입니다. 왼쪽에서 오른쪽으로 읽는 레이아웃에서는 실제로 음수가 왼쪽, 양수가 오른쪽을 의미하지만, RTL 로케일로 바꾸거나 reverseLayout = true를 설정하면 시작/끝이 화면상의 방향을 바꾸므로 부호도 함께 바뀝니다. "양수는 카드가 왼쪽으로 빠져나간다는 뜻"이라고 하드코딩한 코드는 RTL에서 깨집니다.

실제로 사용할 사고방식

"어느 페이지가 선택되었는가"를 묻지 마세요. "지금 Pager가 연속적인 값으로서 정확히 어디에 있는가"를 묻고, 이를 알아내기 위해 currentPage와 currentPageOffsetFraction을 함께 읽으세요.

Keep reading

Related reads

새 글을 이메일로 받아보세요