Esegui la migrazione al cercatore 3

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

Se Paging 3 è la prima versione della libreria di paging che utilizzi nell'app, vedi Caricare e visualizzare dati di paging per informazioni di base sull'utilizzo.

Vantaggi della migrazione a Paging 3

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

  • Assistenza di alto livello per coroutine Kotlin e Flow.
  • Supporto per il caricamento asincrono utilizzando le primitive RxJava Single o Guava ListenableFuture.
  • Stato del caricamento e indicatori di errore integrati per il design adattabile dell'interfaccia utente, incluse la funzionalità di nuovo tentativo e aggiornamento.
  • Miglioramenti al livello di repository, tra cui il supporto della cancellazione e un'interfaccia semplificata dell'origine dati.
  • Miglioramenti a livello di presentazione, separatori di elenchi, trasformazioni di pagina personalizzate e intestazioni e piè di pagina relativi allo stato di caricamento.

Esegui la migrazione della tua app a Paging 3

Per eseguire la migrazione completa alla pagina 3, devi eseguire la migrazione di tutti e tre i componenti principali dalla pagina 2:

  • DataSource corso
  • PagedList
  • PagedListAdapter

Tuttavia, alcuni componenti di Paging 3 sono compatibili con le versioni precedenti di Paging 3. In particolare, l'API PagingSource di Paging 3 può essere un'origine dati per LivePagedListBuilder e RxPagedListBuilder da versioni precedenti. Analogamente, l'API Pager può utilizzare gli oggetti DataSource meno recenti con il metodo asPagingSourceFactory(). Ciò significa che sono disponibili le seguenti opzioni di migrazione:

  • Puoi eseguire la migrazione di DataSource a PagingSource, ma lasciare invariata l'implementazione rimanente.
  • 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 della tua app alla pagina 3.

Le sezioni di questa pagina spiegano come eseguire la migrazione dei componenti di Paging su ogni livello dell'app.

Classi DataSource

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

PageKeyedDataSource, PositionalDataSource e ItemKeyedDataSource della pagina 2 vengono combinati nell'API PagingSource nella pagina 3. I metodi di caricamento di tutte le precedenti classi API vengono combinati in un unico metodo load() in PagingSource. Questo riduce la duplicazione del codice poiché 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 nella pagina 3 con una classe sigillata LoadParams, che include le sottoclassi per ogni tipo di caricamento. Se devi differenziare i tipi di carico nel metodo load(), controlla quale sottoclasse di LoadParams è stata trasmessa: 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 la modalità di ripresa degli aggiornamenti dal centro dei dati impaginati caricati. A questo scopo, implementa getRefreshKey() per mappare la chiave iniziale corretta utilizzando state.anchorPosition come indice a cui si è eseguito l'accesso più di recente.

Kotlin

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

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

Java

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

  return state.getClosestItemToPosition(anchorPosition);
}

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

Java

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

  return state.getClosestItemToPosition(anchorPosition);
}

// Replacing PositionalDataSource.
@Nullable
@Override
Integer getRefreshKey(state: PagingState) {
  return state.anchorPosition;
}

Elenco trasformazioni

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

  • DataSource.map()
  • DataSource.mapByPage()
  • DataSource.Factory.map()
  • DataSource.Factory.mapByPage()

Nella pagina 3, tutte le trasformazioni vengono applicate come operatori su PagingData. Se utilizzi uno dei metodi dell'elenco precedente per trasformare il tuo elenco impaginato, devi spostare la logica di trasformazione da DataSource a PagingData quando crei il Pager utilizzando il nuovo PagingSource.

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

Elenco pagine

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

Classi PagedListBuilder

PagingData sostituisce il valore PagedList esistente della pagina 2. Per eseguire la migrazione a PagingData, devi aggiornare quanto segue:

  • La configurazione di paging è stata spostata da PagedList.Config a PagingConfig.
  • LivePagedListBuilder e RxPagedListBuilder sono state combinate in un singolo corso Pager.
  • Pager espone un oggetto Flow<PagingData> osservabile con la sua proprietà .flow. Le varianti RxJava e LiveData sono disponibili anche come proprietà delle estensioni, richiamabili da Java tramite metodi statici e fornite rispettivamente dai moduli paging-rxjava* e paging-runtime.

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 un flusso reattivo di oggetti PagingData utilizzando Pagina 3, consulta Configurare un flusso di PagingData.

Callback dei confini per le origini su più livelli

Nella pagina 3, RemoteMediator sostituisce PagedList.BoundaryCallback come gestore per il paging dalla rete e dal database.

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

Adattatore elenco pagina

Questa sezione descrive tutte le modifiche necessarie per eseguire la migrazione di un'implementazione precedente di Paging per utilizzare le classi PagingDataAdapter o AsyncPagingDataDiffer di Paging 3.

La pagina 3 fornisce PagingDataAdapter per gestire i nuovi flussi reattivi PagingData. In caso contrario, PagedListAdapter e PagingDataAdapter hanno la stessa interfaccia. Per eseguire la migrazione da PagedListAdapter a PagingDataAdapter, modifica l'implementazione di PagedListAdapter per estendere PagingDataAdapter.

Per scoprire di più su PagingDataAdapter, consulta Definire un adattatore RecyclerView.

DiffusoreAsyncPagedList

Se al momento utilizzi un'implementazione RecyclerView.Adapter personalizzata con AsyncPagedListDiffer, esegui la migrazione dell'implementazione per utilizzare invece il AsyncPagingDataDiffer fornito nella pagina 3:

Kotlin

AsyncPagingDataDiffer(diffCallback, listUpdateCallback)

Java

new AsyncPagingDataDiffer(diffCallback, listUpdateCallback);

Java

new AsyncPagingDataDiffer(diffCallback, listUpdateCallback);

Risorse aggiuntive

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

Codelab

Samples