Kéo để làm mới

Thành phần kéo để làm mới cho phép người dùng kéo xuống ở đầu nội dung của ứng dụng để làm mới dữ liệu.

Nền tảng API

Sử dụng thành phần kết hợp PullToRefreshBox để triển khai tính năng kéo để làm mới, đóng vai trò là vùng chứa cho nội dung có thể cuộn. Các tham số chính sau đây kiểm soát hành vi và giao diện làm mới:

  • isRefreshing: Một giá trị boolean cho biết liệu thao tác làm mới có đang diễn ra hay không.
  • onRefresh: Một hàm lambda thực thi khi người dùng bắt đầu làm mới.
  • indicator: Tuỳ chỉnh chỉ báo mà hệ thống vẽ trên thao tác kéo để làm mới.

Ví dụ cơ bản

Đoạn mã này minh hoạ cách sử dụng cơ bản của 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

Các điểm chính về mã

  • PullToRefreshBox bao bọc một LazyColumn, hiển thị danh sách các chuỗi.
  • PullToRefreshBox yêu cầu các tham số isRefreshing và onRefresh.
  • Nội dung trong khối PullToRefreshBox biểu thị nội dung có thể cuộn.

Kết quả

Video này minh hoạ cách triển khai cơ bản tính năng kéo để làm mới từ mã trước đó:

Hình 1. Một cách triển khai cơ bản tính năng kéo để làm mới trên danh sách các mục.

Ví dụ nâng cao: Tuỳ chỉnh màu chỉ báo

@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

Các điểm chính về mã

  • Màu của chỉ báo được tuỳ chỉnh thông qua các thuộc tính containerColor và color trong tham số indicator.
  • rememberPullToRefreshState() quản lý trạng thái của thao tác làm mới. Bạn sử dụng trạng thái này cùng với tham số indicator.

Kết quả

Video này minh hoạ một cách triển khai thao tác kéo để làm mới bằng chỉ báo có màu:

Hình 2. Một cách triển khai tính năng kéo để làm mới có kiểu tuỳ chỉnh.

Ví dụ nâng cao: Tạo chỉ báo hoàn toàn tuỳ chỉnh

Bạn có thể tạo các chỉ báo tuỳ chỉnh phức tạp bằng cách tận dụng các thành phần kết hợp và ảnh động hiện có.Đoạn mã này minh hoạ cách tạo một chỉ báo hoàn toàn tuỳ chỉnh trong quá trình triển khai tính năng kéo để làm mới:

@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

Các điểm chính về mã

  • Đoạn mã trước đó đã sử dụng Indicator do thư viện cung cấp. Đoạn mã này tạo một thành phần kết hợp chỉ báo tuỳ chỉnh có tên là MyCustomIndicator. Trong thành phần kết hợp này, đối tượng sửa đổi pullToRefreshIndicator sẽ xử lý việc định vị và kích hoạt quá trình làm mới.
  • Như trong đoạn mã trước, ví dụ này trích xuất thực thể PullToRefreshState, vì vậy bạn có thể truyền cùng một thực thể cho cả PullToRefreshBox và pullToRefreshModifier.
  • Ví dụ này sử dụng màu vùng chứa và ngưỡng vị trí từ lớp PullToRefreshDefaults. Bằng cách này, bạn có thể sử dụng lại hành vi và kiểu mặc định từ thư viện Material, trong khi chỉ tuỳ chỉnh những phần tử mà bạn quan tâm.
  • MyCustomIndicator dùng Crossfade để chuyển đổi giữa biểu tượng đám mây và CircularProgressIndicator. Biểu tượng đám mây sẽ tăng kích thước khi người dùng kéo và chuyển sang biểu tượng CircularProgressIndicator khi hành động làm mới bắt đầu.
    • targetState sử dụng isRefreshing để xác định trạng thái cần hiển thị (biểu tượng đám mây hoặc chỉ báo tiến trình hình tròn).
    • animationSpec xác định một ảnh động tween cho hiệu ứng chuyển đổi, với thời lượng được chỉ định là CROSSFADE_DURATION_MILLIS.
    • state.distanceFraction biểu thị khoảng cách mà người dùng đã kéo xuống, từ 0f (không kéo) đến 1f (kéo hoàn toàn).
    • Đối tượng sửa đổi graphicsLayer sửa đổi tỷ lệ và độ trong suốt.

Kết quả

Video này cho thấy chỉ báo tuỳ chỉnh trong mã trước đó:

Hình 3. Một cách triển khai thao tác kéo để làm mới bằng chỉ báo tuỳ chỉnh.

Tài nguyên khác