Esegui la migrazione al cercatore 3

Paging 3 è molto diverso dalle versioni precedenti della libreria Paging. Questa versione offre funzionalità avanzate, supporto di prima classe per le coroutine Kotlin e Flow e integrazione perfetta con Jetpack Compose.

Vantaggi della migrazione a Paging 3

Paging 3 include le seguenti funzionalità che non erano presenti nelle versioni precedenti della libreria:

  • Supporto di prima classe per le coroutine Kotlin e Flow.
  • Stati di caricamento e segnali di errore integrati per la progettazione di UI reattive, tra cui funzionalità di riprova e aggiornamento.
  • Miglioramenti al livello del repository, tra cui il supporto per l'annullamento e un'interfaccia dell'origine dati semplificata.
  • Miglioramenti al livello di presentazione, ai separatori di elenchi, alle trasformazioni personalizzate delle pagine, alle intestazioni e ai piè di pagina e agli elementi dello stato di caricamento per gli elenchi pigri.

Esegui la migrazione della tua app a Paging 3

Per eseguire la migrazione completa a Paging 3, devi eseguire la migrazione di questi componenti principali da Paging 2:

  • DataSource corsi
  • PagedList
  • Livello di presentazione (a LazyPagingItems)

Tuttavia, alcuni componenti di Paging 3 sono compatibili con le versioni precedenti di Paging. In particolare, l'API Pager può utilizzare oggetti DataSource precedenti con il metodo asPagingSourceFactory. Ciò significa che hai a disposizione le seguenti opzioni di migrazione:

  • Puoi eseguire la migrazione di DataSource a PagingSource, ma lasciare invariato il resto dell'implementazione della paginazione.
  • Puoi eseguire la migrazione dell'intera implementazione di Paging per eseguire la migrazione completa dell'app a Paging 3.

Le sezioni di questa pagina spiegano come eseguire la migrazione dei componenti di impaginazione su ogni livello della tua app.

DataSource corsi

Questa sezione descrive tutte le modifiche necessarie per eseguire la migrazione di un'implementazione di Paging precedente in modo da utilizzare PagingSource.

PageKeyedDataSource, PositionalDataSource e ItemKeyedDataSource di Paging 2 sono tutti combinati nell'API PagingSource in Paging 3. I metodi di caricamento di tutte le classi API precedenti sono combinati in un unico metodo load in PagingSource. Ciò riduce la duplicazione del codice perché gran parte della logica nei metodi di caricamento nelle implementazioni delle vecchie classi API è spesso identica.

Tutti i parametri del metodo di caricamento vengono sostituiti in Paging 3 con una classe sigillata LoadParams, che include sottoclassi per ogni tipo di caricamento. Se devi distinguere i tipi di caricamento nel metodo load, controlla quale sottoclasse di LoadParams è stata passata: LoadParams.Refresh, LoadParams.Prepend o LoadParams.Append.

Per scoprire di più sull'implementazione di PagingSource, consulta Definire un'origine dati.

Aggiorna chiavi

Le implementazioni di PagingSource devono definire come riprendere gli aggiornamenti dalla metà dei dati della pagina caricata. Per farlo, implementa getRefreshKey per mappare la chiave iniziale corretta utilizzando state.anchorPosition come indice a cui è stato eseguito l'accesso più di recente.

// Replaces ItemKeyedDataSource.
override fun getRefreshKey(state: PagingState<String, User>): String? {
  return state.anchorPosition?.let { anchorPosition ->
    state.getClosestItemToPosition(anchorPosition)?.id
  }
}

// Replacing PositionalDataSource.
override fun getRefreshKey(state: PagingState<Int, User>): Int? {
  return state.anchorPosition
}

Elenco trasformazioni

Nelle versioni precedenti della libreria Paging, la trasformazione dei dati paginati si basa sui seguenti metodi:

  • DataSource.map
  • DataSource.mapByPage
  • DataSource.Factory.map
  • DataSource.Factory.mapByPage

In Paging 3, tutte le trasformazioni vengono applicate come operatori su PagingData. Se utilizzi uno dei metodi nell'elenco precedente per trasformare l'elenco impaginato, devi spostare la logica di trasformazione da DataSource a PagingData durante la creazione di Pager utilizzando il nuovo PagingSource.

Per scoprire di più sull'applicazione delle trasformazioni ai dati impaginati utilizzando Paging 3, consulta Trasformare i flussi di dati.

PagedList

Questa sezione descrive tutte le modifiche necessarie per eseguire la migrazione di un'implementazione di Paging precedente in modo da utilizzare Pager e PagingData in Paging 3.

PagedListBuilder corsi

PagingData sostituisce PagedList esistente di Paginazione 2. Per eseguire la migrazione a PagingData, devi aggiornare quanto segue:

  • La configurazione della paginazione è stata spostata da PagedList.Config a PagingConfig.
  • Le classi del generatore precedenti sono state combinate in una singola classe Pager.
  • Pager espone un elemento osservabile Flow<PagingData> con la relativa proprietà .flow.
val flow = Pager(
  // Configure how data is loaded by passing additional properties to
  // PagingConfig, such as prefetchDistance.
  PagingConfig(pageSize = 20)
) {
  ExamplePagingSource(backend, query)
}.flow
  .cachedIn(viewModelScope)

Per scoprire di più sulla configurazione di uno stream reattivo di oggetti PagingData utilizzando Paging 3, consulta Configurare uno stream di PagingData.

BoundaryCallback per le origini a livelli

In Paging 3, RemoteMediator sostituisce PagedList.BoundaryCallback come gestore della paginazione dalla rete e dal database.

Per scoprire di più sull'utilizzo di RemoteMediator per eseguire il paging dalla rete e dal database in Paging 3, consulta il codelab di Android Paging.

LazyPagingItems

Questa sezione descrive tutte le modifiche necessarie per eseguire la migrazione di un'implementazione di Paging precedente in modo da utilizzare LazyPagingItems da Paging 3.

Paging 3 fornisce collectAsLazyPagingItems per gestire il nuovo flusso PagingData. Per eseguire la migrazione del livello di presentazione, utilizza l'artefatto paging-compose e collectAsLazyPagingItems per raccogliere gli elementi PagingData e visualizzarli nelle funzioni @Composable.

Per saperne di più su LazyPagingItems, consulta la sezione Caricare e visualizzare dati impaginati.

Differenze e aggiornamenti degli elenchi

Se al momento utilizzi una logica di differenziazione personalizzata degli elenchi, esegui la migrazione dell'implementazione per utilizzare LazyPagingItems fornito in Paging 3. Per assicurarti che il confronto avvenga correttamente, specifica una chiave dell'elemento nell'elenco pigro:

@Composable
fun UserScreen(viewModel: UserViewModel) {
    // Collects the Flow into a LazyPagingItems object
    val lazyPagingItems = viewModel.pager.flow.collectAsLazyPagingItems()

    UserList(lazyPagingItems)
}

@Composable
fun UserScreen(viewModel: UserViewModel) {
    val lazyPagingItems = viewModel.pager.flow.collectAsLazyPagingItems()

    UserList(lazyPagingItems)
}

@Composable
fun UserList(lazyPagingItems: LazyPagingItems<User>) {
    LazyColumn {
        items(
            count = lazyPagingItems.itemCount,
            // Provide a stable key for each item, similar to DiffUtil in Views
            key = lazyPagingItems.itemKey { user -> user.id } 
        ) { index ->
            val user = lazyPagingItems[index]
            if (user != null) {
                UserRow(user = user)
            }
        }
    }
}

Per maggiori informazioni sulle chiavi degli elementi, vedi Chiavi degli elementi.

Caricamento stati in corso…

In Paging 3, non è necessario un adattatore separato per visualizzare intestazioni o piè di pagina per gli stati di caricamento. L'oggetto LazyPagingItems espone una proprietà loadState che puoi controllare direttamente all'interno di LazyColumn.

LazyColumn {
    // ... items(lazyPagingItems) go here ...

    // Show loading spinner at bottom of list when appending data
    if (lazyPagingItems.loadState.append is LoadState.Loading) {
        item {
            CircularProgressIndicator(modifier = Modifier.fillMaxWidth())
        }
    }
}

Risorse aggiuntive

Per saperne di più sulla libreria Paging, consulta le seguenti risorse aggiuntive:

Documentazione

Visualizza contenuti