Zu Paging 3 migrieren

Die Paginierung 3 unterscheidet sich erheblich von früheren Versionen der Paginierungsbibliothek. Diese Version bietet erweiterte Funktionen und behebt häufige Probleme bei der Verwendung von Paging 2. Wenn Ihre Anwendung bereits eine frühere Version der Paging-Bibliothek verwendet, lesen Sie diese Seite mit weiteren Informationen zur Migration zu Paging 3.

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

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 -Ablauf
  • Unterstützung für asynchrones Laden mit RxJava-Primitiven Single oder Guava ListenableFuture.
  • Integrierter Ladestatus und Fehlersignale für responsives UI-Design, einschließlich Wiederholungs- und Aktualisierungsfunktion.
  • Verbesserungen auf der Repository-Ebene, einschließlich Unterstützung für Kündigungen und eine vereinfachte Schnittstelle der Datenquelle.
  • Verbesserungen an Darstellungsebene, Listentrennzeichen, benutzerdefinierten Seitentransformationen sowie Kopf- und Fußzeilen für den Ladestatus.

Anwendung 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 Komponenten von Paging 3 sind jedoch abwärtskompatibel mit früheren Seitenversionen. Insbesondere die PagingSource API aus Paging 3 kann eine Datenquelle für LivePagedListBuilder und RxPagedListBuilder aus älteren Versionen sein. In ähnlicher Weise kann die Pager API ältere DataSource-Objekte mit der Methode asPagingSourceFactory() verwenden. Für Sie bedeutet das, dass Sie folgende Migrationsoptionen haben:

  • Sie können Ihr DataSource zu PagingSource migrieren, aber die restliche 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 Anwendung vollständig zu Paging 3 zu migrieren.

In den Abschnitten auf dieser Seite wird erläutert, wie Sie Paging-Komponenten auf den einzelnen Ebenen Ihrer Anwendung migrieren.

DataSource-Klassen

In diesem Abschnitt werden alle Änderungen beschrieben, die erforderlich sind, um eine ältere Paging-Implementierung zur Verwendung von PagingSource zu migrieren.

Die PageKeyedDataSource, PositionalDataSource und ItemKeyedDataSource aus Paging 2 werden alle in der PagingSource API in Paging 3 zusammengefasst. Die Lademethoden aller alten API-Klassen werden in einer einzigen load()-Methode in PagingSource zusammengefasst. Dies reduziert die Codeduplizierung, da ein Großteil der Logik unter den Lademethoden in Implementierungen der alten API-Klassen häufig identisch ist.

Alle Lademethodenparameter 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 den 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 finden Sie unter Datenquelle definieren.

Aktualisierungsschlüssel

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

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

Transformationen auflisten

In älteren Versionen der Paging-Bibliothek stützt sich die Transformation der ausgelagerten Daten auf die 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 zum Transformieren der ausgelagerten Liste verwenden, müssen Sie beim Erstellen der Pager mit dem neuen PagingSource die Transformationslogik von DataSource in PagingData verschieben.

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

Seitenliste

In diesem Abschnitt werden alle Änderungen beschrieben, die erforderlich sind, um eine ältere Paging-Implementierung zur Verwendung von Pager und PagingData in Paging 3 zu migrieren.

PagedListBuilder-Klassen

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

  • Die Seitenkonfiguration wurde von PagedList.Config nach PagingConfig verschoben.
  • LivePagedListBuilder und RxPagedListBuilder wurden zu einer einzigen Pager-Klasse zusammengefasst.
  • Pager stellt eine beobachtbare Flow<PagingData> mit ihrer .flow-Eigenschaft bereit. RxJava- und LiveData-Varianten sind auch als Erweiterungsattribute verfügbar, die von Java über statische Methoden 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 Stroms von PagingData-Objekten mit Paging 3 finden Sie unter Stream von PagingData einrichten.

BoundaryCallback für Quellen mit mehreren Ebenen

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 für den Ausstieg aus einem Netzwerk und einer Datenbank in Paging 3 finden Sie im Android-Codelab zum Ausbreiten von Seiten.

PagedListAdapter (PagedListAdapter)

In diesem Abschnitt werden alle Änderungen beschrieben, die erforderlich sind, um eine ältere Paging-Implementierung zur Verwendung der Klassen PagingDataAdapter oder AsyncPagingDataDiffer aus Paging 3 zu migrieren.

Paging 3 stellt PagingDataAdapter für die Verarbeitung der neuen reaktiven PagingData-Streams bereit. Andernfalls haben PagedListAdapter und PagingDataAdapter dieselbe Schnittstelle. Wenn Sie von PagedListAdapter zu PagingDataAdapter migrieren möchten, ändern Sie Ihre Implementierung von PagedListAdapter, um stattdessen PagingDataAdapter zu erweitern.

Weitere Informationen zu PagingDataAdapter finden Sie unter RecyclerView-Adapter definieren.

AsyncPagedListDiffer

Wenn Sie derzeit eine benutzerdefinierte RecyclerView.Adapter-Implementierung mit AsyncPagedListDiffer verwenden, migrieren Sie Ihre Implementierung, um stattdessen die in Paging 3 angegebene AsyncPagingDataDiffer zu verwenden:

Kotlin

AsyncPagingDataDiffer(diffCallback, listUpdateCallback)

Java

new AsyncPagingDataDiffer(diffCallback, listUpdateCallback);

Java

new AsyncPagingDataDiffer(diffCallback, listUpdateCallback);

Weitere Informationen

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

Codelabs

Produktproben