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, finden Sie auf dieser Seite weitere Informationen zur Migration zu Paging 3.

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

Vorteile der Migration zu Paging 3

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

  • Erstklassige Unterstützung für Kotlin-Coroutinen und Flow.
  • Unterstützung für das asynchrone Laden mit RxJava- Single- oder Guava-ListenableFuture-Primitiven.
  • Integrierte Ladezustands- und Fehlersignale für ein responsives UI-Design, einschließlich Wiederholungs- und Aktualisierungsfunktionen.
  • Verbesserungen an der Repository-Ebene, einschließlich Unterstützung für die Abbrechen-Funktion und einer vereinfachten Datenquellen-Schnittstelle.
  • Verbesserungen an der Darstellungsebene, Listentrennzeichen, benutzerdefinierten Seitentransformationen sowie Kopf- und Fußzeilen für den Ladestatus.

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 Kurse
  • PagedList
  • PagedListAdapter

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

  • Sie können DataSource zu PagingSource migrieren, ohne die restliche Paging-Implementierung zu ändern.
  • 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 beschrieben, wie Sie Paging-Komponenten auf jeder Ebene Ihrer App migrieren.

DataSource Kurse

In diesem Abschnitt werden alle erforderlichen Änderungen beschrieben, die für die Migration einer älteren Paging-Implementierung zur Verwendung von PagingSource erforderlich sind.

Die PageKeyedDataSource-, PositionalDataSource- und ItemKeyedDataSource-Elemente aus Paging 2 sind alle in der PagingSource-API in Paging 3 enthalten. Die Lademethoden aus allen alten API-Klassen werden in einer einzigen load()-Methode in PagingSource zusammengefasst. 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 Klasse LoadParams ersetzt, die Unterklassen für jeden Ladetyp enthält. Wenn Sie in Ihrer load()-Methode zwischen verschiedenen Ladetypen unterscheiden müssen, prüfen Sie, welche Unterklasse von LoadParams übergeben wurde: LoadParams.Refresh, LoadParams.Prepend oder LoadParams.Append.

Weitere Informationen zum Implementieren von PagingSource

Schlüssel aktualisieren

Bei Implementierungen von PagingSource muss definiert werden, wie Aktualisierungen in der Mitte der geladenen Seiteninhalte fortgesetzt werden. Implementieren Sie dazu getRefreshKey(), um den richtigen anfänglichen Schlü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;
}

Transformationen auflisten

In niedrigeren Versionen der Paging-Bibliothek basiert die Transformation der paginierten Daten auf den folgenden Methoden:

  • 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 paginierte Liste zu transformieren, müssen Sie die Transformationslogik beim Erstellen von Pager mit Ihrem neuen PagingSource von DataSource nach PagingData verschieben.

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

PagedList

In diesem Abschnitt werden alle erforderlichen Änderungen beschrieben, die für die Migration einer älteren Paging-Implementierung zur Verwendung von Pager und PagingData in Paging 3 erforderlich sind.

PagedListBuilder Kurse

PagingData ersetzt die vorhandene PagedList aus Paging 2. Wenn Sie zu PagingData migrieren möchten, müssen Sie Folgendes aktualisieren:

  • Die Paging-Konfiguration wurde von PagedList.Config nach PagingConfig verschoben.
  • LivePagedListBuilder und RxPagedListBuilder wurden in einer einzigen Pager-Klasse zusammengefasst.
  • Pager macht über die .flow-Property ein beobachtbares Flow<PagingData> verfügbar. RxJava- und LiveData-Varianten sind auch als Erweiterungseigenschaften 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 geschichtete Quellen

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

Weitere Informationen zur Verwendung von RemoteMediator zum Paging aus dem Netzwerk und der Datenbank in Paging 3 finden Sie im Android Paging-Codelab.

PagedListAdapter

Bei Paging 2 wird PagedListAdapter verwendet, um ein PagedList an ein RecyclerView zu binden. In Paging 3 ersetzt PagingData PagedList. Wenn Sie Ihre App so migrieren, dass Jetpack Compose für die Benutzeroberfläche verwendet wird, benötigen Sie keinen Adapter, um seitenweise Daten anzuzeigen.

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

Weitere Informationen zur Verwendung von Paging 3 mit Jetpack Compose finden Sie unter Paging 3 – Übersicht.

Zusätzliche Ressourcen

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

Codelabs

Produktproben