Migrate to Paging 3 (Migracja do strony 3)

Biblioteka Paging 3 znacznie różni się od wcześniejszych wersji biblioteki Paging. Ta wersja zapewnia ulepszoną funkcjonalność i rozwiązuje typowe problemy z używaniem biblioteki Paging 2. Jeśli Twoja aplikacja korzysta już z wcześniejszej wersji biblioteki Paging, na tej stronie znajdziesz więcej informacji o migracji do biblioteki Paging 3.

Jeśli Paging 3 to pierwsza wersja biblioteki Paging, której używasz w aplikacji, podstawowe informacje o jej użyciu znajdziesz w artykule Wczytywanie i wyświetlanie danych podzielonych na strony.

Korzyści z przejścia na bibliotekę Paging 3

Biblioteka Paging 3 zawiera te funkcje, które nie były dostępne we wcześniejszych wersjach:

  • Pełna obsługa korutyn i Flow w Kotlinie.
  • Obsługa ładowania asynchronicznego za pomocą elementów pierwotnych RxJavaSingle lub GuavaListenableFuture.
  • Wbudowane sygnały stanu wczytywania i błędów do projektowania responsywnego interfejsu, w tym funkcje ponawiania i odświeżania.
  • Ulepszenia warstwy repozytorium, w tym obsługa anulowania i uproszczony interfejs źródła danych.
  • Ulepszenia warstwy prezentacji, separatorów list, niestandardowych przekształceń stron oraz nagłówków i stopek stanu wczytywania.

Przenoszenie aplikacji do biblioteki Paging 3

Aby w pełni przejść na bibliotekę Paging 3, musisz przenieść wszystkie 3 główne komponenty z biblioteki Paging 2:

  • Zajęcia: DataSource
  • PagedList
  • PagedListAdapter

Niektóre komponenty biblioteki Paging 3 są jednak wstecznie zgodne z poprzednimi wersjami biblioteki Paging. W szczególności interfejs PagingSource API z biblioteki Paging 3 może być źródłem danych dla interfejsów LivePagedListBuilder i RxPagedListBuilder ze starszych wersji. Podobnie interfejs Pager API może używać starszych obiektów DataSource z metodą asPagingSourceFactory(). Oznacza to, że masz do wyboru te opcje migracji:

  • Możesz przenieść DataSource do PagingSource, ale resztę implementacji stronicowania pozostawić bez zmian.
  • Możesz przenieść PagedList i PagedListAdapter, ale nadal korzystać ze starszego interfejsu DataSource API.
  • Możesz przenieść całą implementację biblioteki Paging, aby w pełni zmigrować aplikację do biblioteki Paging 3.

W sekcjach na tej stronie znajdziesz informacje o tym, jak migrować komponenty biblioteki Paging w poszczególnych warstwach aplikacji.

Zajęcia: DataSource

W tej sekcji opisano wszystkie niezbędne zmiany, które należy wprowadzić, aby przenieść starszą implementację stronicowania na PagingSource.

Interfejsy PageKeyedDataSource, PositionalDataSource i ItemKeyedDataSource z biblioteki Paging 2 zostały połączone w interfejs PagingSource w bibliotece Paging 3. Metody wczytywania ze wszystkich starych klas interfejsu API są połączone w jedną metodę load() w klasie PagingSource. Zmniejsza to duplikowanie kodu, ponieważ większość logiki w metodach wczytywania w implementacjach starych klas interfejsu API jest często identyczna.

W bibliotece Paging 3 wszystkie parametry metody ładowania zostały zastąpione LoadParamsklasą zamkniętą, która zawiera podklasy dla każdego typu ładowania. Jeśli chcesz rozróżniać typy wczytywania w metodzie load(), sprawdź, która podklasa LoadParams została przekazana: LoadParams.Refresh, LoadParams.Prepend lub LoadParams.Append.

Więcej informacji o implementacji PagingSource znajdziesz w artykule Definiowanie źródła danych.

Odśwież klucze

Implementacje PagingSource muszą określać, jak odświeżanie ma być wznawiane od środka załadowanych danych strony. Aby to zrobić, zaimplementuj getRefreshKey() w celu zmapowania prawidłowego klucza początkowego przy użyciu state.anchorPosition jako ostatnio użytego indeksu.

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

Wyświetlanie listy przekształceń

W starszych wersjach biblioteki Paging przekształcanie danych podzielonych na strony opiera się na tych metodach:

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

W bibliotece Paging 3 wszystkie przekształcenia są stosowane jako operatory na obiekcie PagingData. Jeśli do przekształcenia listy podzielonej na strony używasz którejkolwiek z metod z powyższej listy, musisz przenieść logikę przekształcania z DataSource do PagingData podczas tworzenia Pager za pomocą nowego PagingSource.

Więcej informacji o stosowaniu przekształceń do danych podzielonych na strony za pomocą biblioteki Paging 3 znajdziesz w artykule Przekształcanie strumieni danych.

PagedList

W tej sekcji opisujemy wszystkie niezbędne zmiany, które należy wprowadzić, aby przenieść starszą implementację biblioteki Paging na Paging 3, w której używane są adnotacje Pager i PagingData.

Zajęcia: PagedListBuilder

PagingData zastępuje dotychczasowy interfejs PagedList z Paging 2. Aby przejść na PagingData, musisz zaktualizować te elementy:

  • Konfiguracja stronicowania została przeniesiona z PagedList.Config do PagingConfig.
  • LivePagedListBuilder i RxPagedListBuilder zostały połączone w jedne zajęcia Pager.
  • Pager udostępnia obserwowalną właściwość Flow<PagingData> z jej właściwością .flow. Warianty RxJava i LiveData są też dostępne jako właściwości rozszerzenia, które można wywoływać z Javy za pomocą metod statycznych i które są udostępniane odpowiednio przez moduły paging-rxjava* i 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);

Więcej informacji o konfigurowaniu reaktywnego strumienia obiektów PagingData za pomocą biblioteki Paging 3 znajdziesz w artykule Konfigurowanie strumienia PagingData.

BoundaryCallback w przypadku źródeł warstwowych

W bibliotece Paging 3 interfejs RemoteMediator zastępuje interfejs PagedList.BoundaryCallback jako moduł obsługi stronicowania z sieci i bazy danych.

Więcej informacji o używaniu RemoteMediator do stronicowania z sieci i bazy danych w bibliotece Paging 3 znajdziesz w ćwiczeniach z programowania dotyczących stronicowania na Androidzie.

PagedListAdapter

Paging 2 używa PagedListAdapter do powiązania PagedList z RecyclerView. W bibliotece Paging 3 PagingData zastępuje PagedList. Jeśli przenosisz aplikację na interfejs Jetpack Compose, nie potrzebujesz adaptera do wyświetlania danych podzielonych na strony.

Zamiast tego użyj artefaktu paging-compose i jego metody rozszerzenia collectAsLazyPagingItems, aby zbierać elementy PagingData i wyświetlać je w funkcjach @Composable, takich jak LazyColumn.

Więcej informacji o korzystaniu z biblioteki Paging 3 w Jetpack Compose znajdziesz w Przeglądzie biblioteki Paging 3.

Dodatkowe materiały

Więcej informacji o bibliotece Paging znajdziesz w tych materiałach:

Codelabs

Próbki