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 oggettoLoadState.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 oggettoLoadState.Loading. - Se si verifica un errore,
LoadStateè un oggettoLoadState.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).
Aggiungi intestazioni e piè di pagina di caricamento
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
Consigliati per te
- Nota: il testo del link viene visualizzato quando JavaScript è disattivato
- Panoramica della libreria Paging