Quản lý và trình bày trạng thái tải

Thư viện phân trang theo dõi trạng thái của các yêu cầu tải dữ liệu được phân trang và hiển thị thông qua lớp LoadState.

Bạn có thể cung cấp tín hiệu LoadState riêng biệt cho từng LoadType và loại nguồn dữ liệu (PagingSource hoặc RemoteMediator). Đối tượng CombinedLoadStates do trình nghe cung cấp cung cấp thông tin về trạng thái tải của tất cả tín hiệu này. Bạn có thể dùng thông tin chi tiết này để hiện các chỉ báo tải phù hợp cho người dùng.

Các trạng thái đang tải

Thư viện phân trang hiện trạng thái tải để sử dụng trong UI (giao diện người dùng) thông qua đối tượng LoadState. Các đối tượng LoadState có một trong ba dạng tuỳ thuộc vào trạng thái tải hiện tại:

  • Nếu không có hoạt động tải nào đang hoạt động và không có lỗi, thì LoadState là đối tượng LoadState.NotLoading. Lớp con này cũng bao gồm thuộc tính endOfPaginationReached, cho biết liệu đã đến cuối quá trình phân trang hay chưa.
  • Nếu có một hoạt động tải đang hoạt động, thì LoadState là đối tượng LoadState.Loading.
  • Nếu xảy ra lỗi thì LoadState là đối tượng LoadState.Error.

Truy cập vào các trạng thái này thông qua thuộc tính loadState của trình bao bọc LazyPagingItems. Bạn có thể sử dụng trạng thái này theo hai cách: xử lý chế độ hiển thị nội dung chính (như vòng quay làm mới toàn màn hình) hoặc chèn các mục đang tải trực tiếp vào luồng LazyColumn (như vòng quay chân trang).

Truy cập trạng thái đang tải bằng một trình nghe

Để theo dõi trạng thái tải trong giao diện người dùng, hãy sử dụng thuộc tính loadState do trình bao bọc LazyPagingItems cung cấp. Thao tác này sẽ trả về một đối tượng CombinedLoadStates cho phép bạn phản ứng với hành vi tải cho các sự kiện làm mới, thêm vào cuối hoặc thêm vào đầu.

Trong ví dụ sau, giao diện người dùng hiển thị vòng quay tải hoặc thông báo lỗi tuỳ thuộc vào trạng thái hiện tại của quá trình tải làm mới (ban đầu):

@Composable
fun UserListScreen(viewModel: UserViewModel) {
  val pagingItems = viewModel.flow.collectAsLazyPagingItems()

  Box(modifier = Modifier.fillMaxSize()) {
    // Show the list content
    LazyColumn {
      items(pagingItems.itemCount) { index ->
        UserItem(pagingItems[index])
      }
    }

    // Handle the loading state
    when (val state = pagingItems.loadState.refresh) {
      is LoadState.Loading -> {
        CircularProgressIndicator(modifier = Modifier.align(Alignment.Center))
      }
      is LoadState.Error -> {
        ErrorButton(
          message = state.error.message ?: "Unknown error",
          onClick = { pagingItems.retry() },
          modifier = Modifier.align(Alignment.Center)
        )
      }
      else -> {} // No separate view needed for success/not loading
    }
  }
}

Để biết thêm thông tin về LazyPagingItems, hãy xem phần Các tập dữ liệu lớn (phân trang).

Để hiển thị chỉ báo tải ở đầu hoặc cuối danh sách (đóng vai trò là tiêu đề hoặc chân trang), hãy thêm các khối mục dành riêng cho các trạng thái đó trong phạm vi LazyColumn của bạn.

Bạn có thể theo dõi trạng thái thêm vào đầu cho tiêu đề và trạng thái thêm vào cuối cho chân trang bằng đối tượng CombinedLoadStates.

Trong ví dụ sau, danh sách sẽ hiển thị thanh tiến trình hoặc nút thử lại ở cuối danh sách khi có thêm dữ liệu đang được tìm nạp:

@Composable
fun UserList(viewModel: UserViewModel) {
  val pagingItems = viewModel.pager.flow.collectAsLazyPagingItems()

  LazyColumn {
    // 1. Header (Prepend state)
    // Useful if you support bidirectional paging or jumping to the middle
    item {
      val prependState = pagingItems.loadState.prepend
      if (prependState is LoadState.Loading) {
        LoadingItem()
      } else if (prependState is LoadState.Error) {
        ErrorItem(
          message = prependState.error.message ?: "Error",
          onClick = { pagingItems.retry() }
        )
      }
    }

    // 2. Main Data
    items(pagingItems.itemCount) { index ->
      UserItem(pagingItems[index])
    }

    // 3. Footer (Append state)
    // Shows when the user scrolls to the bottom and more data is loading
    item {
      val appendState = pagingItems.loadState.append
      if (appendState is LoadState.Loading) {
        LoadingItem()
      } else if (appendState is LoadState.Error) {
        ErrorItem(
          message = appendState.error.message ?: "Error",
          onClick = { pagingItems.retry() }
        )
      }
    }
  }
}

@Composable
fun LoadingItem() {
  Box(modifier = Modifier.fillMaxWidth().padding(16.dp), contentAlignment = Alignment.Center) {
    CircularProgressIndicator()
  }
}

@Composable
fun ErrorItem(message: String, onClick: () -> Unit) {
  Column(
    modifier = Modifier.fillMaxWidth().padding(16.dp),
    horizontalAlignment = Alignment.CenterHorizontally
  ) {
    Text(text = message, color = Color.Red)
    Button(onClick = onClick) { Text("Retry") }
  }
}

Truy cập các thông tin bổ sung về trạng thái đang tải

Như trong các ví dụ trước, việc gọi pagingItems.loadState.refresh rất thuận tiện. Tuy nhiên, việc này sẽ che khuất sự khác biệt giữa việc tải từ cơ sở dữ liệu cục bộ (PagingSource) và mạng (RemoteMediator). Điều này có thể khiến giao diện người dùng hiển thị nhanh vòng quay tải ngay cả khi dữ liệu đã lưu vào bộ nhớ đệm có sẵn ngay lập tức.

Để kiểm soát chính xác, chẳng hạn như chỉ hiển thị vòng quay tải khi cơ sở dữ liệu cục bộ trống và quá trình đồng bộ hoá mạng đang hoạt động, hãy truy cập trực tiếp vào các thuộc tính source và mediator trong composable của bạn.

val loadState = pagingItems.loadState

val isSyncing = loadState.mediator?.refresh is LoadState.Loading

val isLocalEmpty = loadState.source.refresh is LoadState.NotLoading &&
                   pagingItems.itemSnapshotList.items.isEmpty()

if (isSyncing && isLocalEmpty) {
    FullScreenLoading()
} else {
    UserList(pagingItems)

    if (isSyncing) {
        TopOverlaySpinner()
    }
}

Vì pagingItems.loadState phát ra một đối tượng CombinedLoadStates mới bất cứ khi nào prepend hoặc append thay đổi trong quá trình cuộn, hãy gói quy trình kiểm tra làm mới trong derivedStateOf bằng remember(pagingItems). Điều này ngăn các bản cập nhật cạnh cuộn kết hợp lại một phạm vi mẹ chỉ bật/tắt chỉ báo làm mới toàn màn hình:

val showFullScreenLoading by remember(pagingItems) {
  derivedStateOf {
    // Avoid recomposing on prepend or append updates while scrolling, and
    // avoid covering existing items during a background refresh.
    pagingItems.loadState.source.refresh is LoadState.Loading &&
      pagingItems.itemCount == 0
  }
}

if (showFullScreenLoading) {
  Box(
    modifier = Modifier.fillMaxSize(),
    contentAlignment = Alignment.Center
  ) {
    CircularProgressIndicator()
  }
}

Phản hồi các thay đổi về trạng thái tải

Bạn có thể cần kích hoạt các tác dụng phụ một lần dựa trên các thay đổi về trạng thái tải, chẳng hạn như cuộn lên đầu danh sách hoặc hiển thị Snackbar khi quá trình làm mới hoàn tất hoặc không thành công.

Sử dụng snapshotFlow bên trong LaunchedEffect để quan sát các thay đổi về trạng thái dưới dạng một luồng. Điều này cho phép bạn áp dụng các toán tử Flow chuẩn như filter, distinctUntilChanged và distinctUntilChangedBy để tách riêng các sự kiện cụ thể.

val listState = rememberLazyListState()

LaunchedEffect(pagingItems) {
  // 1. Convert the state to a Flow
  snapshotFlow { pagingItems.loadState.refresh }
    // 2. Filter for the specific event (Refresh completed successfully)
    .distinctUntilChanged()
    .filter { it is LoadState.NotLoading }
    .collect {
      // 3. Trigger the side effect
      listState.animateScrollToItem(0)
    }
}

Tương tự, bạn có thể sử dụng distinctUntilChangedBy trên loadState để chỉ hiển thị lỗi Snackbar khi trạng thái refresh chuyển sang LoadState.Error:

val snackbarHostState = remember { SnackbarHostState() }

// Key on pagingItems rather than loadState so state updates do not restart the
// coroutine and reset distinctUntilChangedBy.
LaunchedEffect(pagingItems) {
  snapshotFlow { pagingItems.loadState }
    // Ignore prepend and append updates so scrolling does not re-trigger the
    // refresh error Snackbar.
    .distinctUntilChangedBy { it.refresh }
    .filter { it.refresh is LoadState.Error }
    .collect { loadState ->
      val error = (loadState.refresh as LoadState.Error).error
      val result = snackbarHostState.showSnackbar(
        message = "Data failed to load: ${error.localizedMessage ?: "Unknown error"}",
        actionLabel = "Retry"
      )
      if (result == SnackbarResult.ActionPerformed) {
        pagingItems.retry()
      }
    }
}

Tài nguyên khác

Để biết thêm thông tin về thư viện Phân trang và trạng thái tải, hãy tham khảo các tài nguyên sau.

Tài liệu

Nội dung lượt xem