Zu Paging 3 migrieren

Paging 3 unterscheidet sich erheblich von früheren Versionen der Paging-Bibliothek. Diese Version bietet erweiterte Funktionen und behebt häufige Probleme bei der Verwendung von Paging 2. Wenn Ihre App bereits eine frühere Version der Paging-Bibliothek verwendet, lesen Sie diese Seite, um mehr über die Migration zu Paging 3 zu erfahren.

Wenn Paging 3 die erste Version der Paging-Bibliothek ist, die Sie in Ihrer App verwenden, finden Sie unter Paging-Daten laden und anzeigen grundlegende Informationen zur Verwendung.

Vorteile der Migration zu Paging 3

Paging 3 enthält die folgenden Funktionen, die in früheren Versionen der Bibliothek nicht vorhanden waren:

  • Erstklassige Unterstützung für Kotlin-Koroutinen und Flow.
  • Unterstützung für asynchrones Laden mit den RxJava-Primitiven Single oder Guava ListenableFuture.
  • Integrierte Ladezustands- und Fehlersignale für ein reaktionsschnelles UI-Design, einschließlich Funktionen für Wiederholungen und Aktualisierungen.
  • Verbesserungen an der Repository-Ebene, einschließlich Unterstützung für die Abbruchfunktion und einer vereinfachten Datenquellenoberfläche.
  • Verbesserungen an der Präsentationsebene, Listentrennzeichen, benutzerdefinierte Seitentransformationen sowie Kopf- und Fußzeilen für den Ladezustand.

App zu Paging 3 migrieren

Für eine vollständige Migration zu Paging 3 müssen Sie alle drei Hauptkomponenten von Paging 2 migrieren:

  • DataSource-Klassen
  • PagedList
  • PagedListAdapter

Einige Paging 3-Komponenten sind jedoch abwärtskompatibel mit früheren Versionen von Paging. Insbesondere kann die PagingSource-API von Paging 3 eine Datenquelle für LivePagedListBuilder und RxPagedListBuilder aus älteren Versionen sein. Ebenso kann die Pager API ältere DataSource Objekte mit der asPagingSourceFactory() Methode verwenden. Das bedeutet, dass Sie die folgenden Migrationsoptionen haben:

  • Sie können Ihre DataSource zu PagingSource migrieren, aber den Rest Ihrer Paging-Implementierung unverändert lassen.
  • Sie können Ihre PagedList und PagedListAdapter migrieren, aber weiterhin die ältere DataSource API verwenden.
  • Sie können die gesamte Paging-Implementierung migrieren, um Ihre App vollständig zu Paging 3 zu migrieren.

In den Abschnitten auf dieser Seite wird erläutert, wie Sie Paging-Komponenten auf jeder Ebene Ihrer App migrieren.

DataSource-Klassen

In diesem Abschnitt werden alle erforderlichen Änderungen beschrieben, um eine ältere Paging-Implementierung zu migrieren, damit PagingSource verwendet wird.

PageKeyedDataSource, PositionalDataSource und ItemKeyedDataSource aus Paging 2 werden in Paging 3 in der PagingSource-API kombiniert. Die Lademethoden aus allen alten API-Klassen werden in PagingSource in einer einzigen load()-Methode kombiniert. Dadurch wird die Codeduplizierung reduziert, da ein Großteil der Logik in den Lademethoden in Implementierungen der alten API-Klassen oft identisch ist.

Alle Parameter der Lademethode werden in Paging 3 durch eine versiegelte LoadParams-Klasse ersetzt, die Unterklassen für jeden Ladetyp enthält. Wenn Sie in Ihrer load()-Methode zwischen Ladetypen unterscheiden müssen, prüfen Sie, welche Unterklasse von LoadParams übergeben wurde: LoadParams.Refresh, LoadParams.Prepend oder LoadParams.Append.

Weitere Informationen zur Implementierung von PagingSource finden Sie unter Datenquelle definieren.

Aktualisierungsschlüssel

Implementierungen von PagingSource müssen definieren, wie Aktualisierungen in der Mitte der geladenen Paging-Daten fortgesetzt werden. Implementieren Sie dazu getRefreshKey() um den richtigen Anfangsschlüssel mit state.anchorPosition als zuletzt aufgerufenen Index zuzuordnen.

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

Listentransformationen

In älteren Versionen der Paging-Bibliothek hängt die Transformation der Paging-Daten von den folgenden Methoden ab:

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

In Paging 3 werden alle Transformationen als Operatoren auf PagingData angewendet. Wenn Sie eine der Methoden in der vorherigen Liste verwenden, um Ihre Paging-Liste zu transformieren, müssen Sie Ihre Transformationslogik von DataSource zu PagingData verschieben, wenn Sie Pager mit Ihrer neuen PagingSource erstellen.

Weitere Informationen zum Anwenden von Transformationen auf Paging-Daten mit Paging 3 finden Sie unter Datenstreams transformieren.

PagedList

In diesem Abschnitt werden alle erforderlichen Änderungen beschrieben, um eine ältere Paging-Implementierung zu migrieren, damit Pager und PagingData in Paging 3 verwendet werden.

PagedListBuilder-Klassen

PagingData ersetzt die vorhandene PagedList aus Paging 2. Für die Migration zu PagingData müssen Sie Folgendes aktualisieren:

  • Die Paging-Konfiguration wurde von PagedList.Config zu PagingConfig verschoben.
  • LivePagedListBuilder und RxPagedListBuilder wurden in einer einzigen Pager-Klasse kombiniert.
  • Pager stellt mit der Property .flow einen beobachtbaren Flow<PagingData> bereit. RxJava- und LiveData-Varianten sind auch als Erweiterungsproperties verfügbar, die über statische Methoden aus Java aufgerufen werden können und aus den Modulen paging-rxjava* bzw. paging-runtime bereitgestellt werden.

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

Weitere Informationen zum Einrichten eines reaktiven Streams von PagingData Objekten mit Paging 3 finden Sie unter Stream von PagingData einrichten.

BoundaryCallback für mehrschichtige Quellen

In Paging 3 ersetzt RemoteMediator die PagedList.BoundaryCallback als Handler für das Paging aus dem Netzwerk und der Datenbank.

Weitere Informationen zur Verwendung von RemoteMediator für das Paging aus dem Netzwerk und der Datenbank in Paging 3 finden Sie im Codelab zu Android Paging.

PagedListAdapter

In Paging 2 wird PagedListAdapter verwendet, um eine PagedList an eine RecyclerView zu binden. In Paging 3 ersetzt PagingData die PagedList. Wenn Sie Ihre App migrieren, um Jetpack Compose für die UI zu verwenden, benötigen Sie keinen Adapter, um Paging-Daten anzuzeigen.

Verwenden Sie stattdessen das paging-compose-Artefakt und die Erweiterungsmethode collectAsLazyPagingItems, um PagingData-Elemente zu erfassen und in @Composable-Funktionen wie LazyColumn anzuzeigen.

Zusätzliche Ressourcen

Weitere Informationen zur Paging-Bibliothek finden Sie in den folgenden zusätzlichen Ressourcen:

Codelabs

Produktproben