下拉即可刷新

借助下拉刷新组件，用户可以在应用内容开头处向下拉动来刷新数据。

API Surface

使用 PullToRefreshBox 可组合项来实现下拉刷新，该可组合项充当可滚动内容的容器。以下关键参数可控制刷新行为和外观：

  • isRefreshing：一个布尔值，用于指示刷新操作是否正在进行。
  • onRefresh：当用户发起刷新时执行的 lambda 函数。
  • indicator：自定义系统在下拉刷新时绘制的指示器。

基本示例

以下代码段演示了 PullToRefreshBox 的基本用法：

@Composable
fun PullToRefreshBasicSample(
    items: List<String>,
    isRefreshing: Boolean,
    onRefresh: () -> Unit,
    modifier: Modifier = Modifier
) {
    PullToRefreshBox(
        isRefreshing = isRefreshing,
        onRefresh = onRefresh,
        modifier = modifier
    ) {
        LazyColumn(Modifier.fillMaxSize()) {
            items(items) {
                ListItem({ Text(text = it) })
            }
        }
    }
}
PullToRefreshBox.kt

代码要点

  • PullToRefreshBox 封装了 LazyColumn，用于显示字符串列表。
  • PullToRefreshBox 需要 isRefreshing 和 onRefresh 参数。
  • PullToRefreshBox 块中的内容表示可滚动的内容。

结果

此视频演示了上述代码中的基本下拉刷新实现：

图 1. 针对商品列表的基本下拉刷新实现。

高级示例：自定义指示器颜色

@Composable
fun PullToRefreshCustomStyleSample(
    items: List<String>,
    isRefreshing: Boolean,
    onRefresh: () -> Unit,
    modifier: Modifier = Modifier
) {
    val state = rememberPullToRefreshState()

    PullToRefreshBox(
        isRefreshing = isRefreshing,
        onRefresh = onRefresh,
        modifier = modifier,
        state = state,
        indicator = {
            Indicator(
                modifier = Modifier.align(Alignment.TopCenter),
                isRefreshing = isRefreshing,
                containerColor = MaterialTheme.colorScheme.primaryContainer,
                color = MaterialTheme.colorScheme.onPrimaryContainer,
                state = state
            )
        },
    ) {
        LazyColumn(Modifier.fillMaxSize()) {
            items(items) {
                ListItem({ Text(text = it) })
            }
        }
    }
}
PullToRefreshBox.kt

代码要点

  • 通过 indicator 参数中的 containerColor 和 color 属性自定义指示器颜色。
  • rememberPullToRefreshState() 用于管理刷新操作的状态。 您可将此状态与 indicator 参数搭配使用。

结果

此视频展示了带有彩色指示器的下拉刷新实现：

图 2. 具有自定义样式的下拉刷新实现。

高级示例：创建完全自定义的指示器

您可以利用现有的可组合项和动画创建复杂的自定义指示器。此代码段演示了如何在下拉刷新实现中创建完全自定义的指示器：

@Composable
fun PullToRefreshCustomIndicatorSample(
    items: List<String>,
    isRefreshing: Boolean,
    onRefresh: () -> Unit,
    modifier: Modifier = Modifier
) {
    val state = rememberPullToRefreshState()

    PullToRefreshBox(
        isRefreshing = isRefreshing,
        onRefresh = onRefresh,
        modifier = modifier,
        state = state,
        indicator = {
            MyCustomIndicator(
                state = state,
                isRefreshing = isRefreshing,
                modifier = Modifier.align(Alignment.TopCenter)
            )
        }
    ) {
        LazyColumn(Modifier.fillMaxSize()) {
            items(items) {
                ListItem({ Text(text = it) })
            }
        }
    }
}

// ...
@Composable
fun MyCustomIndicator(
    state: PullToRefreshState,
    isRefreshing: Boolean,
    modifier: Modifier = Modifier,
) {
    Box(
        modifier = modifier.pullToRefresh(
            state = state,
            isRefreshing = isRefreshing,
            threshold = PositionalThreshold,
            onRefresh = {

            }
        ),
        contentAlignment = Alignment.Center
    ) {
        Crossfade(
            targetState = isRefreshing,
            animationSpec = tween(durationMillis = CROSSFADE_DURATION_MILLIS),
            modifier = Modifier.align(Alignment.Center)
        ) { refreshing ->
            if (refreshing) {
                CircularProgressIndicator(Modifier.size(SPINNER_SIZE))
            } else {
                val distanceFraction = { state.distanceFraction.coerceIn(0f, 1f) }
                Icon(
                    imageVector = Icons.Filled.CloudDownload,
                    contentDescription = "Refresh",
                    modifier = Modifier
                        .size(18.dp)
                        .graphicsLayer {
                            val progress = distanceFraction()
                            this.alpha = progress
                            this.scaleX = progress
                            this.scaleY = progress
                        }
                )
            }
        }
    }
}
PullToRefreshBox.kt

代码要点

  • 上一个代码段使用了库提供的 Indicator。此代码段会创建一个名为 MyCustomIndicator 的自定义指示器可组合项。在此可组合项中，pullToRefreshIndicator 修饰符负责处理定位和触发刷新。
  • 与上一个代码段一样，此示例提取了 PullToRefreshState 实例，因此您可以将同一实例传递给 PullToRefreshBox 和 pullToRefreshModifier。
  • 该示例使用了 PullToRefreshDefaults 类中的容器颜色和位置阈值。这样，您就可以重复使用 Material 库中的默认行为和样式，同时仅自定义您感兴趣的元素。
  • MyCustomIndicator 使用 Crossfade 在云图标和 CircularProgressIndicator 之间进行过渡。当用户下拉时，云图标会放大，并在刷新操作开始时转换为 CircularProgressIndicator。
    • targetState 使用 isRefreshing 来确定要显示的状态（云图标或圆形进度指示器）。
    • animationSpec 定义了过渡的 tween 动画，并指定了时长 CROSSFADE_DURATION_MILLIS。
    • state.distanceFraction 表示用户下拉的距离，范围从 0f（未下拉）到 1f（完全下拉）。
    • graphicsLayer 修饰符可修改缩放比例和透明度。

结果

此视频展示了上述代码中的自定义指标：

图 3。具有自定义指示器的下拉刷新实现。

其他资源