管理和顯示載入狀態

分頁程式庫會追蹤分頁資料的載入要求狀態，並透過 LoadState 類別公開資料。

針對每個 LoadType 和資料來源類型 (PagingSource 或 RemoteMediator) 會提供獨立的 LoadState 信號。此事件監聽器提供的 CombinedLoadStates 物件會提供所有信號的載入狀態資訊。您可以使用此詳細資訊，向使用者顯示適用的載入指標。

載入狀態

Paging 程式庫會透過 LoadState 物件公開使用者介面中的載入狀態。根據目前的載入狀態，LoadState 物件採用下列其中一種格式：

透過 LazyPagingItems 包裝函式的 loadState 屬性存取這些狀態。您可以透過兩種方式使用這個狀態：處理主要內容的顯示狀態 (例如全螢幕重新整理旋轉圖示)，或直接將載入項目插入 LazyColumn 串流 (例如頁尾旋轉圖示)。

透過事件監聽器存取載入狀態

如要在使用者介面中監控載入狀態，請使用 LazyPagingItems 包裝函式提供的 loadState 屬性。這會傳回 CombinedLoadStates 物件，讓您對重新整理、附加或前置事件的載入行為做出反應。

在下列範例中，UI 會根據重新整理 (初始) 載入的目前狀態，顯示載入中的旋轉圖示或錯誤訊息：

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

如要進一步瞭解 LazyPagingItems，請參閱大型資料集 (分頁)。

如要在清單開頭或結尾顯示載入指標 (做為標題或頁尾)，請在 LazyColumn 範圍內新增專為這些狀態設計的項目區塊。

您可以使用 CombinedLoadStates 物件監控標頭的預先附加狀態和頁尾的附加狀態。

在下列範例中，當系統擷取更多資料時，清單底部會顯示進度列或重試按鈕：

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

存取其他載入狀態資訊

如先前的範例所示，呼叫 pagingItems.loadState.refresh 很方便。不過，這會模糊從本機資料庫 (PagingSource) 和網路 (RemoteMediator) 載入資料之間的差異。即使快取資料可立即使用，這也可能導致 UI 短暫顯示載入旋轉圖示。

如要精確控制，例如只在本機資料庫空白且網路同步處理處於啟用狀態時顯示載入微調器，請直接在可組合函式中存取 source 和 mediator 屬性。

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

回應載入狀態變更

您可能需要根據載入狀態變化觸發一次性副作用，例如在重新整理完成時捲動至清單頂端或顯示 Snackbar。

在 LaunchedEffect 內使用 snapshotFlow，以串流形式觀察狀態變化。您可以使用標準 Flow 運算子 (例如 filter 和 distinctUntilChanged) 篩選特定事件。

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

其他資源

如要進一步瞭解 Paging 程式庫和載入狀態，請參閱下列資源。

說明文件

Views content