Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

Compose 中的呼叫器

如要水平或垂直翻閱內容，可以使用 HorizontalPager 和 VerticalPager 可組合函式。這些函式的功能與 View 系統中的 ViewPager 類似。根據預設，HorizontalPager 會占滿整個螢幕寬度，VerticalPager 則會占滿整個高度。翻頁元素也只能一次滑動一頁。所有預設值皆可設定。

HorizontalPager

如要建立可左右水平捲動的翻頁元素，請使用 HorizontalPager：

圖 1. HorizontalPager

示範

// Display 10 items
val pagerState = rememberPagerState(pageCount = {
    10
})
HorizontalPager(state = pagerState) { page ->
    // Our page content
    Text(
        text = "Page: $page",
        modifier = Modifier.fillMaxWidth()
    )
}PagerSnippets.kt

VerticalPager

如要建立可上下捲動的翻頁元素，請使用 VerticalPager：

圖 2. VerticalPager

示範

// Display 10 items
val pagerState = rememberPagerState(pageCount = {
    10
})
VerticalPager(state = pagerState) { page ->
    // Our page content
    Text(
        text = "Page: $page",
        modifier = Modifier.fillMaxWidth()
    )
}PagerSnippets.kt

延遲建立

HorizontalPager 和 VerticalPager 中的頁面都會延遲組成，並在需要時才進行版面配置。當使用者捲動頁面時，可組合項會移除不再需要的頁面。

在畫面外載入更多頁面

根據預設，翻頁元素只會載入畫面上顯示的頁面。如要在畫面外載入更多頁面，請將 beyondBoundsPageCount 設為大於零的值。

捲動至翻頁元素中的項目

如要捲動至翻頁元素中的特定頁面，請使用 rememberPagerState() 建立 PagerState 物件，並將其做為 state 參數傳遞至翻頁元素。您可以在 CoroutineScope 內對這個狀態呼叫 PagerState#scrollToPage()：

val pagerState = rememberPagerState(pageCount = {
    10
})
HorizontalPager(state = pagerState) { page ->
    // Our page content
    Text(
        text = "Page: $page",
        modifier = Modifier
            .fillMaxWidth()
            .height(100.dp)
    )
}

// scroll to page
val coroutineScope = rememberCoroutineScope()
Button(onClick = {
    coroutineScope.launch {
        // Call scroll to on pagerState
        pagerState.scrollToPage(5)
    }
}, modifier = Modifier.align(Alignment.BottomCenter)) {
    Text("Jump to Page 5")
}PagerSnippets.kt

如要為頁面加上動畫效果，請使用 PagerState#animateScrollToPage() 函式：

val pagerState = rememberPagerState(pageCount = {
    10
})

HorizontalPager(state = pagerState) { page ->
    // Our page content
    Text(
        text = "Page: $page",
        modifier = Modifier
            .fillMaxWidth()
            .height(100.dp)
    )
}

// scroll to page
val coroutineScope = rememberCoroutineScope()
Button(onClick = {
    coroutineScope.launch {
        // Call scroll to on pagerState
        pagerState.animateScrollToPage(5)
    }
}, modifier = Modifier.align(Alignment.BottomCenter)) {
    Text("Jump to Page 5")
}PagerSnippets.kt

接收網頁狀態變更通知

PagerState 有三個屬性，包含頁面相關資訊：currentPage、settledPage 和 targetPage。

currentPage：最接近貼齊位置的頁面。根據預設，貼齊位置位於版面配置的開頭。
settledPage：沒有動畫或捲動時的頁碼。這與 currentPage 屬性不同，因為如果頁面與貼齊位置夠近，currentPage 會立即更新，但 settledPage 會維持不變，直到所有動畫都執行完畢。
targetPage：捲動動作的建議停止位置。

您可以使用 snapshotFlow 函式觀察這些變數的變化，並做出反應。舉例來說，如要在每次頁面變更時傳送數據分析事件，可以執行下列操作：

val pagerState = rememberPagerState(pageCount = {
    10
})

LaunchedEffect(pagerState) {
    // Collect from the a snapshotFlow reading the currentPage
    snapshotFlow { pagerState.currentPage }.collect { page ->
        // Do something with each page change, for example:
        // viewModel.sendPageSelectedEvent(page)
        Log.d("Page change", "Page changed to $page")
    }
}

VerticalPager(
    state = pagerState,
) { page ->
    Text(text = "Page: $page")
}PagerSnippets.kt

新增頁面指標

如要在頁面中新增指標，請使用 PagerState 物件取得所選頁面的相關資訊，並繪製自訂指標。

舉例來說，如要建立圓形指標，您可以使用 pagerState.currentPage 重複圓形數量，並根據是否選取頁面變更圓形顏色：

val pagerState = rememberPagerState(pageCount = {
    4
})
HorizontalPager(
    state = pagerState,
    modifier = Modifier.fillMaxSize()
) { page ->
    // Our page content
    Text(
        text = "Page: $page",
    )
}
Row(
    Modifier
        .wrapContentHeight()
        .fillMaxWidth()
        .align(Alignment.BottomCenter)
        .padding(bottom = 8.dp),
    horizontalArrangement = Arrangement.Center
) {
    repeat(pagerState.pageCount) { iteration ->
        val color = if (pagerState.currentPage == iteration) Color.DarkGray else Color.LightGray
        Box(
            modifier = Modifier
                .padding(2.dp)
                .clip(CircleShape)
                .background(color)
                .size(16.dp)
        )
    }
}PagerSnippets.kt

翻頁元素，在內容下方顯示圓形指標 — **圖 3**. Pager 在內容下方顯示圓形指標

為內容套用項目捲動效果

常見用途是使用捲動位置，將效果套用至翻頁元素項目。如要瞭解某個頁面與所選頁面的距離，可以使用 PagerState.currentPageOffsetFraction。接著，您可以根據與所選頁面的距離，對內容套用轉換特效。

圖 4. 對 Pager 內容套用轉換

舉例來說，如要根據項目與中心的距離調整不透明度，請在翻頁元素內的項目上使用 Modifier.graphicsLayer 變更 alpha：

val pagerState = rememberPagerState(pageCount = {
    4
})
HorizontalPager(state = pagerState) { page ->
    Card(
        Modifier
            .size(200.dp)
            .graphicsLayer {
                // Calculate the absolute offset for the current page from the
                // scroll position. We use the absolute value which allows us to mirror
                // any effects for both directions
                val pageOffset = (
                    (pagerState.currentPage - page) + pagerState
                        .currentPageOffsetFraction
                    ).absoluteValue

                // We animate the alpha, between 50% and 100%
                alpha = lerp(
                    start = 0.5f,
                    stop = 1f,
                    fraction = 1f - pageOffset.coerceIn(0f, 1f)
                )
            }
    ) {
        // Card content
    }
}PagerSnippets.kt

自訂頁面大小

根據預設，HorizontalPager 和 VerticalPager 分別會占滿整個寬度或高度。您可以將 pageSize 變數設為 Fixed、Fill (預設) 或自訂大小計算。

舉例來說，如要將頁面寬度固定為 100.dp，請按照下列步驟操作：

val pagerState = rememberPagerState(pageCount = {
    4
})
HorizontalPager(
    state = pagerState,
    pageSize = PageSize.Fixed(100.dp)
) { page ->
    // page content
}PagerSnippets.kt

如要根據可視區域大小調整頁面大小，請使用自訂頁面大小計算。建立自訂 PageSize 物件，並將 availableSpace 除以三，同時考量項目之間的間距：

private val threePagesPerViewport = object : PageSize {
    override fun Density.calculateMainAxisPageSize(
        availableSpace: Int,
        pageSpacing: Int
    ): Int {
        return (availableSpace - 2 * pageSpacing) / 3
    }
}PagerSnippets.kt

內容間距

HorizontalPager 和 VerticalPager 都支援變更內容邊框間距，可讓您影響頁面的大小上限和對齊方式。

舉例來說，設定 start 邊框間距會將頁面對齊結尾：

翻頁元素，開頭有內邊距，內容靠結尾對齊 — **圖 5**. 具有開頭邊框間距的翻頁元素。

val pagerState = rememberPagerState(pageCount = {
    4
})
HorizontalPager(
    state = pagerState,
    contentPadding = PaddingValues(start = 64.dp),
) { page ->
    // page content
}PagerSnippets.kt

將 start 和 end 邊框間距設為相同的值，即可將項目置中：

具有起始和結尾邊框間距的翻頁元素，內容置中 — **圖 6**. 具有水平邊框間距的翻頁元素。

val pagerState = rememberPagerState(pageCount = {
    4
})
HorizontalPager(
    state = pagerState,
    contentPadding = PaddingValues(horizontal = 32.dp),
) { page ->
    // page content
}PagerSnippets.kt

設定 end 邊框間距，將頁面對齊開頭：

具有起始和結尾邊框間距的翻頁元素，內容靠起始位置對齊 — **圖 7**. 結尾處有邊框間距的翻頁元素。

val pagerState = rememberPagerState(pageCount = {
    4
})
HorizontalPager(
    state = pagerState,
    contentPadding = PaddingValues(end = 64.dp),
) { page ->
    // page content
}PagerSnippets.kt

您可以設定 top 和 bottom 值，為 VerticalPager 達到類似效果。32.dp 值僅做為範例，您可以將每個邊框間距維度設為任何值。

自訂捲動行為

預設的 HorizontalPager 和 VerticalPager 可組合項會指定捲動手勢與翻頁元素的搭配運作方式。不過，您可以自訂及變更預設值，例如 pagerSnapDistance 或 flingBehavior。

貼齊距離

根據預設，HorizontalPager 和 VerticalPager 會將快速滑過手勢可捲動的頁面數量上限設為一次一頁。如要變更這項設定，請在 flingBehavior 上設定 pagerSnapDistance：

val pagerState = rememberPagerState(pageCount = { 10 })

val fling = PagerDefaults.flingBehavior(
    state = pagerState,
    pagerSnapDistance = PagerSnapDistance.atMost(10)
)

Column(modifier = Modifier.fillMaxSize()) {
    HorizontalPager(
        state = pagerState,
        pageSize = PageSize.Fixed(200.dp),
        beyondViewportPageCount = 10,
        flingBehavior = fling
    ) {
        PagerSampleItem(page = it)
    }
}PagerSnippets.kt

建立自動跳轉的翻頁元素

本節說明如何在 Compose 中建立具有頁面指標的自動跳轉翻頁元素。項目集合會自動水平捲動，但使用者也可以手動滑動切換項目。如果使用者與翻頁元素互動，系統就會停止自動切換。

基本範例

下列程式碼片段會共同建立基本的自動跳轉翻頁元素，並附有視覺指標，其中每個頁面都會以不同顏色顯示：

@Composable
fun AutoAdvancePager(pageItems: List<Color>, modifier: Modifier = Modifier) {
    Box(modifier = Modifier.fillMaxSize()) {
        val pagerState = rememberPagerState(pageCount = { pageItems.size })
        val pagerIsDragged by pagerState.interactionSource.collectIsDraggedAsState()

        val pageInteractionSource = remember { MutableInteractionSource() }
        val pageIsPressed by pageInteractionSource.collectIsPressedAsState()

        // Stop auto-advancing when pager is dragged or one of the pages is pressed
        val autoAdvance = !pagerIsDragged && !pageIsPressed

        if (autoAdvance) {
            LaunchedEffect(pagerState, pageInteractionSource) {
                while (true) {
                    delay(2000)
                    val nextPage = (pagerState.currentPage + 1) % pageItems.size
                    pagerState.animateScrollToPage(nextPage)
                }
            }
        }

        HorizontalPager(
            state = pagerState
        ) { page ->
            Text(
                text = "Page: $page",
                textAlign = TextAlign.Center,
                modifier = modifier
                    .fillMaxSize()
                    .background(pageItems[page])
                    .clickable(
                        interactionSource = pageInteractionSource,
                        indication = LocalIndication.current
                    ) {
                        // Handle page click
                    }
                    .wrapContentSize(align = Alignment.Center)
            )
        }

        PagerIndicator(pageItems.size, pagerState.currentPage)
    }
}PagerSnippets.kt

程式碼重點

AutoAdvancePager 函式會建立水平分頁檢視畫面，並自動前進。它會將 Color 物件清單做為輸入內容，並做為每個頁面的背景顏色。
pagerState 是使用 rememberPagerState 建立，用於保存翻頁元素的狀態。
pagerIsDragged 和 pageIsPressed 會追蹤使用者互動。
除非使用者拖曳翻頁元素或按下其中一個頁面，否則 LaunchedEffect 會每兩秒自動推進翻頁元素。
HorizontalPager 會顯示頁面清單，每個頁面都有一個顯示頁碼的 Text 可組合項。修飾符會填滿頁面、從 pageItems 設定背景顏色，並讓頁面可供點選。

@Composable
fun PagerIndicator(pageCount: Int, currentPageIndex: Int, modifier: Modifier = Modifier) {
    Box(modifier = Modifier.fillMaxSize()) {
        Row(
            modifier = Modifier
                .wrapContentHeight()
                .fillMaxWidth()
                .align(Alignment.BottomCenter)
                .padding(bottom = 8.dp),
            horizontalArrangement = Arrangement.Center
        ) {
            repeat(pageCount) { iteration ->
                val color = if (currentPageIndex == iteration) Color.DarkGray else Color.LightGray
                Box(
                    modifier = modifier
                        .padding(2.dp)
                        .clip(CircleShape)
                        .background(color)
                        .size(16.dp)
                )
            }
        }
    }
}PagerSnippets.kt

程式碼重點

Box 可組合函式會做為根元素，並包含 Row，以水平方式排列頁面指標。
自訂頁面指標會顯示為一列圓圈，其中每個裁剪為 CircleShape 的 Box 都代表一個頁面。
目前頁面的圓圈顏色為 DarkGray，其他圓圈則為 LightGray。currentPageIndex 參數會決定哪個圓圈會顯示為深灰色。

結果

這部影片顯示上述程式碼片段的基本自動前進翻頁元素：

圖 8. 自動前進的翻頁元素，每頁之間有兩秒的延遲。

其他資源

顯示分頁清單

Lazy 清單和 Lazy 格線

流程版面配置

Compose 中的呼叫器 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

HorizontalPager

VerticalPager

延遲建立

在畫面外載入更多頁面

捲動至翻頁元素中的項目

接收網頁狀態變更通知

新增頁面指標

為內容套用項目捲動效果

自訂頁面大小

內容間距

自訂捲動行為

貼齊距離

建立自動跳轉的翻頁元素

基本範例

程式碼重點

程式碼重點

結果

其他資源

Compose 中的呼叫器