下拉刷新

下拉刷新组件允许用户在应用内容的开头向下拖动以刷新数据。

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.pullToRefreshIndicator(
            state = state,
            isRefreshing = isRefreshing,
            containerColor = PullToRefreshDefaults.containerColor,
            threshold = PositionalThreshold
        ),
        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. 具有自定义指示器的下拉刷新实现。

其他资源