Compose 中的分页器

如需向左或向右或向上或向下翻阅内容,您可以分别使用 HorizontalPagerVerticalPager 可组合项。这些可组合函数的功能类似于 视图中的 ViewPager 系统。默认情况下,HorizontalPager 占据整个屏幕的宽度,VerticalPager 占据整个屏幕的高度,并且分页器一次只能快速滑动一页。这些默认值都可以配置。

HorizontalPager

要创建左右滚动的分页器,请使用 HorizontalPager

图 1HorizontalPager的演示

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

VerticalPager

如需创建可以上下滚动的分页器,请使用 VerticalPager

<ph type="x-smartling-placeholder">
</ph>
图 2.VerticalPager 演示

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

延迟创建

HorizontalPagerVerticalPager 中的网页都出现延迟 组合和布局。以用户的身份 滚动浏览页面时,该可组合项会移除不再位于 必填字段。

在屏幕外加载更多页面

默认情况下,分页器仅加载屏幕上可见的网页。如需在屏幕外加载更多页面,请将 beyondBoundsPageCount 设置为大于零的值。

滚动到分页器中的某个项

要滚动到分页器中的某个特定页面,请创建一个 PagerState 使用 rememberPagerState() 并将其作为 state 参数传递给分页器。您可以拨打 PagerState#scrollToPage()CoroutineScope 内针对此状态:

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")
}

如果您要为页面添加动画效果,请使用 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")
}

接收有关页面状态更改的通知

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")
}

添加页面指示器

如需向页面添加指示器,请使用 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)
        )
    }
}

在内容下方显示圆形指示器的页面浏览器
图 3. 在内容下方显示圆圈指示器的分页器

将内容滚动效果应用于内容

一个常见的用例是使用滚动位置对页面浏览器项应用效果。如需了解某个网页距离当前所选网页有多远,您可以 使用 PagerState.currentPageOffsetFraction。 然后,您可以根据与所选页面的距离,对内容应用转换效果。

<ph type="x-smartling-placeholder">
</ph>
图 4.对分页器内容应用转换

例如,根据项目距离项目有多远,调整其不透明度 使用以下代码更改 alphaModifier.graphicsLayer

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
    }
}

自定义页面大小

默认情况下,HorizontalPagerVerticalPager 会占据整个宽度或 和整个高度。您可以将 pageSize 变量设置为 Fixed, Fill (默认)或自定义尺寸计算。

例如,如需设置 100.dp 这一固定宽度的页面,请使用以下代码:

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

若要根据视口大小调整页面大小,请使用自定义页面大小 计算。创建自定义 PageSize 对象,并将 availableSpace 除以 3,同时将间距因素考虑在内 之间:

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

内容内边距

HorizontalPagerVerticalPager 都支持更改内容内边距,以便您影响页面的最大尺寸和对齐方式。

例如,设置 start 内边距可将页面对齐到末尾:

带有起始内边距的分页器,显示内容向末尾对齐

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

startend 的内边距设置为相同的值,使项居中 水平:

带有开始和结束内边距的页面浏览器,用于居中显示内容

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

设置 end 内边距可将页面对齐到起始位置:

带有开始和结束内边距的页面浏览器,显示与开始对齐的内容

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

您可以设置 topbottom 值,以实现与 VerticalPager。值 32.dp 在这里仅用作示例;您可以将每个内边距维度设置为任何值。

自定义滚动行为

默认的 HorizontalPagerVerticalPager 可组合项会指定 滚动手势适用于分页器。不过,您可以自定义和更改默认值,例如 pagerSnapDistanceflingBehavior

吸附距离

默认情况下,HorizontalPagerVerticalPager 会将一次滑动手势可滚过的页面数量上限设置为 1 页。要更改 这个,设置 pagerSnapDistanceflingBehavior 上:

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)
    }
}