Esegui la migrazione al cercatore 3

Paging 3 è molto diverso dalle versioni precedenti della libreria Paging. Questa versione offre funzionalità avanzate e risolve le difficoltà comuni nell'utilizzo di Paging 2. Se la tua app utilizza già una versione precedente della libreria Paging, leggi questa pagina per scoprire di più sulla migrazione a Paging 3.

Se Paging 3 è la prima versione della libreria Paging che utilizzi nella tua app, consulta Caricare e visualizzare dati paginati per informazioni di base sull'utilizzo.

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 e Flow di Kotlin.
  • Supporto per il caricamento asincrono utilizzando le primitive RxJava Single o Guava ListenableFuture.
  • Stato di caricamento e indicatori 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 e ai piè di pagina e alle intestazioni dello stato di caricamento.

Esegui la migrazione della tua app a Paging 3

Per eseguire completamente la migrazione a Paging 3, devi eseguire la migrazione di tutti e tre i componenti principali da Paging 2:

  • DataSource corsi
  • PagedList
  • PagedListAdapter

Tuttavia, alcuni componenti di Paging 3 sono compatibili con le versioni precedenti di Paging. In particolare, l'API PagingSource di Paging 3 può essere un'origine dati per LivePagedListBuilder e RxPagedListBuilder delle versioni precedenti. Allo stesso modo, l'API Pager può utilizzare oggetti DataSource precedenti con il metodo asPagingSourceFactory(). Ciò significa che hai 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 di PagedList e PagedListAdapter, ma continuare a utilizzare l'API DataSource precedente.
  • 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. In questo modo si 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.

Kotlin

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

Java

// Replaces ItemKeyedDataSource.
@Nullable
@Override
String getRefreshKey(state: PagingState<String, User>) {
  Integer anchorPosition = state.anchorPosition;
  if (anchorPosition == null) {
    return null;
  }

  return state.getClosestItemToPosition(anchorPosition);
}

// Replaces PositionalDataSource.
@Nullable
@Override
Integer getRefreshKey(state: PagingState<Integer, User>) {
  return state.anchorPosition;
}

Java

// Replacing ItemKeyedDataSource.
@Nullable
@Override
String getRefreshKey(state: PagingState<String, User>) {
  Integer anchorPosition = state.anchorPosition;
  if (anchorPosition == null) {
    return null;
  }

  return state.getClosestItemToPosition(anchorPosition);
}

// Replacing PositionalDataSource.
@Nullable
@Override
Integer getRefreshKey(state: PagingState<Integer, User>) {
  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 Paging 2. Per eseguire la migrazione a PagingData, devi aggiornare quanto segue:

  • La configurazione della paginazione è stata spostata da PagedList.Config a PagingConfig.
  • LivePagedListBuilder e RxPagedListBuilder sono stati combinati in un unico corso Pager.
  • Pager espone un elemento osservabile Flow<PagingData> con la relativa proprietà .flow. Le varianti RxJava e LiveData sono disponibili anche come proprietà di estensione, che possono essere chiamate da Java utilizzando metodi statici e sono fornite dai moduli paging-rxjava* e paging-runtime rispettivamente.

Kotlin

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)

Java

// CoroutineScope helper provided by the lifecycle-viewmodel-ktx artifact.
CoroutineScope viewModelScope = ViewModelKt.getViewModelScope(viewModel);
Pager<Integer, User> pager = Pager<>(
  new PagingConfig(/* pageSize = */ 20),
  () -> ExamplePagingSource(backend, query));

Flowable<PagingData<User>> flowable = PagingRx.getFlowable(pager);
PagingRx.cachedIn(flowable, viewModelScope);

Java

// CoroutineScope helper provided by the lifecycle-viewmodel-ktx artifact.
CoroutineScope viewModelScope = ViewModelKt.getViewModelScope(viewModel);
Pager<Integer, User> pager = Pager<>(
  new PagingConfig(/* pageSize = */ 20),
  () -> ExamplePagingSource(backend, query));

PagingLiveData.cachedIn(PagingLiveData.getLiveData(pager), 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 su Android Paging.

PagedListAdapter

Paging 2 utilizza PagedListAdapter per associare un PagedList a un RecyclerView. In Paging 3, PagingData sostituisce PagedList. Se esegui la migrazione dell'app per utilizzare Jetpack Compose per la relativa UI, non hai bisogno di un adattatore per visualizzare i dati impaginati.

Utilizza invece l'artefatto paging-compose e il relativo metodo di estensione collectAsLazyPagingItems per raccogliere gli elementi PagingData e visualizzarli nelle funzioni @Composable come LazyColumn.

Per saperne di più sull'utilizzo di Paging 3 con Jetpack Compose, consulta la panoramica di Paging 3.

Risorse aggiuntive

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

Codelab

Campioni