Recomposed
Pager

Jetpack Compose: Pager を理解する

Oct 30, 2026 · 7 min read

Jetpack Compose: Pager を理解する

Pager の正体

HorizontalPager と VerticalPager は、スワイプ可能でスナップする全画面ページの並びを実現する Composable です。オンボーディング画面、画像カルーセル、画面を切り替えるのではなくスライドするタブコンテンツなどがその例です。各ページはそれぞれ独立した Composable であり、pager はそれらを横に並べてレイアウトし、ページ間を移動するドラッグ/フリングジェスチャーを処理します。

rememberPagerState(pageCount = { ... }) は、それを駆動する PagerState を作成します。この state はどのページかだけでなくユーザーが今どこにいるかを返します。この記事の残りの部分が扱うのは、レイアウトそのものではなく、この区別です。

直感的な理解

Pager を Tab の行と同じように扱うと、どのページが選択されているかだけを教えてくれるものだと思い込んでしまいます。TabRow の selectedTabIndex はまさにそのように動作します: 0 から 1 へ飛ぶだけの整数です。同じ前提でページトランジションを作ると、滑らかに動くはずのものがスナップしてしまいます。これは、滑らかなトランジションを可能にする唯一の state を捨ててしまっているからです。

  • pagerState.currentPage は、ドラッグの最中も含めて、pager が現在位置している場所に最も近いページを常に示しています。ドラッグやフリングが実際に終わったときではなく、2つのページの中間点を越えた瞬間に切り替わります。
  • pagerState.currentPageOffsetFraction は currentPage が捨ててしまう部分を表します。おおよそ -0.5 から 0.5 の連続的な float で、currentPage からどれだけ前のページ (<0) または次のページ (>0) へ移動したかを示します。
  • ドラッグの各フレームごとに異なるオフセット割合が報告されます。これこそが、カードをスケールさせたり、隣接要素をフェードさせたり、インジケーターをユーザーの指の動きに合わせてモーフィングさせたりするために読み取るべき信号です。「どれだけ」という情報を持たない currentPage だけでは実現できません。

Pager はこの同じ state からレイアウトの決定も行います: pageSize は各ページがどの程度表示されるかを制御し、pageSpacing はページ間の間隔を設定し、contentPadding は隣接ページが端からどの程度覗き見えるかを制御します。これら3つはページごとに一度だけ計測され、スクロール位置によって変化しません。フレームごとに更新されるのはオフセット割合だけです。

具体例: オフセットを読み取ってカードをスケールする

val pagerState = rememberPagerState(pageCount = { 6 })
 
HorizontalPager(
    state = pagerState,
    modifier = Modifier.fillMaxWidth(),
    contentPadding = PaddingValues(horizontal = 64.dp),
) { page ->
    Card(
        modifier = Modifier
            .graphicsLayer {
                // このページから currentPage の定着スロットまでの、ページ幅を単位とした符号付き距離。
                // このページがそのスロットに定着しているときはちょうど 0f になり、
                // 隣接ページがそこから丸々1ページ幅離れているときは ±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 は「そこから丸々1ページ幅離れている」ことを意味します。ここでスロットが中央に見えるのは、対称的な contentPadding のおかげに過ぎません。オフセット割合自体は、そのスロットが画面上のどこにあるかを一切知りません。

この連続的な値こそが が必要とするものです。代わりに currentPage だけを渡すと、スケールは指の動きを追従せずに段階的に飛ぶようになります。

試してみましょう: 以下のカードをドラッグして、currentPage とオフセットがリアルタイムで更新される様子を見てください。リリース時のスナップバックも含まれています。

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 がリアルタイムで更新される様子が表示されています。

さらなるケース: 同じオフセットの異なる読み取り方

オフセット割合は、このブログ自身の Draw シリーズの記事に限らず、スワイプが連続的に感じられる必要がある場所ならどこにでも現れます:

  • 隣接ページが覗き見えるレイアウトでは、contentPadding と pageSpacing を読み取って静止時に次のページがどれだけ見えるかを決め、ユーザーがドラッグするとその一部をスライド/スケールさせるために currentPageOffsetFraction を読み取ります。
  • モーフィングするページインジケーターは、同じオフセット割合を読み取って、2つの静的な状態を切り替えるのではなく、一つのドットの形状を次の形状へブレンドします。
  • オンボーディングフローでは、2つの静的な画面をクロスフェードする代わりに、同じオフセット割合をもとに現在のステップのイラストを縮小・フェードさせながら次のイラストを拡大させていきます。
  • ストーリービューアー (Instagram、WhatsApp Status) では、一方から他方へ直接切り替えるのではなく、スワイプに合わせて退場するストーリーを縮小・暗転させつつ、入場するストーリーを全サイズまで拡大させます。
  • フォトカルーセルは、上の具体例とまったく同じオフセットによるスケール計算式を、番号付きカードの代わりに写真に適用して再利用します。

見た目は違っても、根底にある読み取り方は同じです: currentPage、currentPageOffsetFraction、そして上の式が計算するページごとの距離です。

核心

これは 連続的なスクロール進行度 です: ジェスチャーの state は、単なる離散的な「前」と「後」ではなく、ジェスチャーが進行している間、毎フレーム更新される float として表現されます。

currentPage はアンカーです。currentPageOffsetFraction は次のアンカーへの進行度です。この2つを組み合わせることで、どちらか一方だけよりも豊かな信号になります。

pagerState.isScrollInProgress は、その連続的な読み取りが実際に意味を持つタイミングを教えてくれます: ドラッグ、フリング、またはプログラムによるスクロールが進行中は true、定着すると false になります。

他のフレームワークでも: 同じ本質、異なる実装

  • Android の View ベースの ViewPager/ViewPager2: このモデルそのものの直接の祖先です。onPageScrolled(position, positionOffset, positionOffsetPixels) は整数のページと [0, 1) の float オフセットを渡してきます。これは Compose で currentPage/currentPageOffsetFraction が引き継いでいる、まったく同じ2要素の形です。
  • SwiftUI の scrollTransition: ページ形式の ScrollView や TabView の内部では、各アイテムに渡される phase は、アイテムがビューポートを横切る際の連続的な float であり、単なる「どのページか」というインデックスではありません。currentPage/currentPageOffsetFraction と同じ2要素の読み取りですが、pager 単位ではなくアイテム単位で報告される点が異なります。
  • CSS の scroll-driven animations: animation-timeline: scroll() は、アニメーションの進行度を時間ではなくスクロール位置に直接結びつけます。これによりアニメーションは、どれだけスクロールしたかの連続的な関数になります。まさに currentPageOffsetFraction から scaleX/scaleY を駆動するのと同じ考え方です。
  • Swiper.js (Web 用のカルーセルライブラリ): スライドごとに、おおよそ -1 から 1 の progress 値を公開しており、スライドが中央を通過する際にまさにこの種のスケール/パララックス効果を作るために使えます。

エッジケース

  • currentPage は1つ以上のインデックスをスキップすることがあります。 速いフリングは、定着するまでに pager を複数ページ分動かすことがあります。currentPage がフレーム間で常に ±1 しか変化しないという前提でトランジションのコードを書いてはいけません。そのフリングがどこに着地するかを着地前に知る必要がある場合は pagerState.targetPage を読み取ってください。
  • currentPage と settledPage の違い。 currentPage は、速いフリングが通過するすべての中間ページを含めて、ドラッグやフリングの間ずっと連続的に更新されます。settledPage は、pager が実際に静止したときにのみ更新されます。「ユーザーはページの変更を終えたか」を知りたいときは settledPage を読み取り、「pager は今どこにあるか」を知りたいときは currentPage を読み取ってください。
  • pageSpacing と contentPadding は互いに影響し合います。 padding はコンテナの端から隣接ページがどれだけ覗き見えるかを制御し、spacing はそれに加えてページ間の間隔を追加します。片方だけを設定してもう片方を考慮しないと、ページが意図より近すぎたり遠すぎたりして見える原因になりやすいです。
  • 符号は文字どおり「左」と「右」を意味するわけではありません。 currentPageOffsetFraction は、レイアウトの start 方向に向かうと負、end 方向に向かうと正になります。start/end は論理的な方向です。左から右へのレイアウトでは確かに負が左、正が右を意味しますが、RTL ロケールに切り替えたり reverseLayout = true を設定したりすると start/end は画面上で左右が入れ替わり、符号もそれに伴って入れ替わります。「正の値はカードが左へ退場することを意味する」とハードコードしたコードは RTL 下で破綻します。

実際に使うべきメンタルモデル

「どのページが選択されているか」ではなく、「pager は今、連続的な値として正確にどこにあるか」と問いましょう。そしてその答えを得るために currentPage と currentPageOffsetFraction を合わせて読み取りましょう。

Keep reading

Related reads

新しい記事をメールで受け取る