Gestire e presentare gli stati di caricamento

La libreria Paging monitora lo stato delle richieste di caricamento per i dati impaginati e lo espone tramite la classe LoadState.

Viene fornito un indicatore LoadState separato per ogni LoadType e tipo di origine dati (PagingSource o RemoteMediator). L'oggetto CombinedLoadStates fornito dal listener fornisce informazioni sullo stato di caricamento da tutti questi indicatori. Puoi utilizzare queste informazioni dettagliate per mostrare gli indicatori di caricamento appropriati agli utenti.

Caricamento degli stati in corso…

La libreria Paging espone lo stato di caricamento per l'utilizzo nell'interfaccia utente tramite l'oggetto LoadState. Gli oggetti LoadState assumono una delle tre forme a seconda dello stato di caricamento corrente:

  • Se non è presente un'operazione di caricamento attiva e non si verifica alcun errore, LoadState è un oggetto LoadState.NotLoading. Questa sottoclasse include anche la proprietà endOfPaginationReached, che indica se è stata raggiunta la fine della paginazione.
  • Se è presente un'operazione di caricamento attiva, LoadState è un oggetto LoadState.Loading.
  • Se si verifica un errore, LoadState è un oggetto LoadState.Error.

Accedi a questi stati tramite la proprietà loadState del wrapper LazyPagingItems. Puoi utilizzare questo stato in due modi: gestendo la visibilità dei contenuti principali (ad esempio uno spinner di aggiornamento a schermo intero) o inserendo elementi di caricamento direttamente nello stream LazyColumn (ad esempio uno spinner nel piè di pagina).

Accedi allo stato di caricamento con un listener

Per monitorare lo stato di caricamento nella UI, utilizza la proprietà loadState fornita dal wrapper LazyPagingItems. Viene restituito un oggetto CombinedLoadStates che ti consente di reagire al comportamento di caricamento per gli eventi di aggiornamento, aggiunta o anteposizione.

Nell'esempio seguente, l'UI mostra una rotellina di caricamento o un messaggio di errore a seconda dello stato corrente del caricamento di aggiornamento (iniziale):

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

Per saperne di più su LazyPagingItems, consulta Set di dati di grandi dimensioni (paginazione).

Per visualizzare gli indicatori di caricamento all'inizio o alla fine dell'elenco (che fungono da intestazioni o piè di pagina), aggiungi blocchi di elementi dedicati specificamente a questi stati nell'ambito di LazyColumn.

Puoi monitorare lo stato di aggiunta all'inizio per l'intestazione e lo stato di aggiunta alla fine per il piè di pagina utilizzando l'oggetto CombinedLoadStates.

Nell'esempio seguente, l'elenco mostra una barra di avanzamento o un pulsante Riprova nella parte inferiore dell'elenco quando vengono recuperati altri dati:

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

Accedi a ulteriori informazioni sullo stato di caricamento

Come mostrato negli esempi precedenti, chiamare pagingItems.loadState.refresh è comodo. Tuttavia, nasconde la differenza tra il caricamento dal database locale (PagingSource) e dalla rete (RemoteMediator). Ciò può far sì che la UI mostri brevemente un'icona di caricamento anche quando i dati memorizzati nella cache sono immediatamente disponibili.

Per un controllo preciso, ad esempio per mostrare un indicatore di caricamento solo quando il database locale è vuoto e una sincronizzazione di rete è attiva, accedi alle proprietà source e mediator direttamente all'interno del composable.

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

Poiché pagingItems.loadState genera un nuovo oggetto CombinedLoadStates ogni volta che prepend o append cambia durante lo scorrimento, racchiudi il controllo di aggiornamento in derivedStateOf con remember(pagingItems). In questo modo, gli aggiornamenti dei bordi di scorrimento non ricompongono uno scope principale che attiva/disattiva solo un indicatore di aggiornamento a schermo intero:

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

Reagisci alle modifiche dello stato di caricamento

Potresti dover attivare effetti collaterali una tantum in base alle modifiche dello stato di caricamento, ad esempio scorrere fino all'inizio di un elenco o mostrare un Snackbar quando un aggiornamento viene completato o non va a buon fine.

Utilizza snapshotFlow all'interno di un LaunchedEffect per osservare le modifiche di stato come flusso. In questo modo puoi applicare operatori Flow standard come filter, distinctUntilChanged e distinctUntilChangedBy per isolare eventi specifici.

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

Analogamente, puoi utilizzare distinctUntilChangedBy su loadState per visualizzare un errore Snackbar solo quando lo stato refresh passa a 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()
      }
    }
}

Risorse aggiuntive

Per ulteriori informazioni sulla libreria Paging e sugli stati di caricamento, consulta le seguenti risorse.

Documentazione

Visualizza contenuti