Migrate to Paging 3 (Migracja do strony 3)

Paging 3 znacznie różni się od wcześniejszych wersji biblioteki stronicowania. Ta wersja udostępnia rozszerzone funkcje i rozwiązuje typowe problemy problemy z używaniem strony Paging 2. Jeśli Twoja aplikacja używa już wcześniejszego biblioteki stronicowania, przeczytaj tę stronę, aby dowiedzieć się więcej o migracji do Strzelanie 3.

Jeśli strona Paging 3 jest pierwszą wersją biblioteki stronicowania, której używasz aplikacji, zapoznaj się z sekcją Wczytywanie i wyświetlanie stron dane do podstawowego wykorzystania i informacjami o nich.

Zalety przejścia na stronę Paging 3

Strona 3 zawiera funkcje, które nie były wcześniej dostępne różnych wersji biblioteki:

  • Pierwsza klasa obsługa współprogramów Kotlin i Flow.
  • Obsługa ładowania asynchronicznego przy użyciu kodu RxJava Single lub Guava ListenableFuture elementów podstawowych.
  • Wbudowane sygnały stanu wczytywania i błędów do projektowania elastycznego interfejsu użytkownika, w tym: ponowienie próby i odświeżenie.
  • Ulepszenia warstwy repozytorium, w tym obsługa anulowania uproszczony interfejs źródła danych.
  • Ulepszenia warstwy prezentacji, separatorów list i strony niestandardowej przekształcania oraz wczytywania nagłówków i stopek stanów.

Migracja aplikacji do Paging 3

Aby w pełni przejść na stronę Paging 3, musisz przenieść wszystkie 3 główne komponenty. ze strony 2:

  • DataSource zajęć
  • PagedList
  • PagedListAdapter

Niektóre komponenty stronicowania 3 są jednak zgodne wstecznie z poprzednimi elementami. stronicowania. W szczególności Interfejs API PagingSource ze stronicowania 3 może być źródłem danych dla: LivePagedListBuilder i RxPagedListBuilder ze starszych wersji. Interfejs API Pager może też korzystać ze starszych wersji DataSource obiektów z asPagingSourceFactory(). Oznacza to, że masz: opcje migracji:

  • Możesz przenieść swoją subskrypcję DataSource do PagingSource, ale pozostawić resztę Implementacja stron bez zmian.
  • Możesz przenieść PagedList i PagedListAdapter, ale nadal korzystać z starszą wersję interfejsu API DataSource.
  • Możesz przeprowadzić migrację całej implementacji stronicowania, aby w pełni przenieść aplikację do Strzelanie 3.

W sekcjach na tej stronie dowiesz się, jak przenieść komponenty stronicowania z każdej warstwy Twojej aplikacji.

Klasy DataSource

W tej sekcji opisano wszystkie zmiany niezbędne do przeniesienia starszych stron do użycia interfejsu PagingSource.

PageKeyedDataSource, PositionalDataSource i ItemKeyedDataSource ze strony Paging 2 są połączone w interfejs API PagingSource w Pingowanie 3. metody wczytywania ze wszystkich starych klas interfejsu API są łączone w jedną, Metoda load() w PagingSource. Pozwala to ograniczyć duplikowanie kodu, ponieważ wiele logikę obejmującą metody wczytywania w implementacjach starych klas interfejsu API często są identyczne.

Wszystkie parametry metody wczytywania są zastępowane w narzędziu Strona 3 za pomocą parametru LoadParams klasa Sealed, która zawiera podklasy dla każdego typu obciążenia. W razie potrzeby rozróżnić typy wczytywania w metodzie load(), sprawdź, które podklasa klasy LoadParams została przekazana w: LoadParams.Refresh, LoadParams.Prepend, czy LoadParams.Append.

Więcej informacji o implementowaniu funkcji PagingSource znajdziesz w artykule Definiowanie danych source.

Odśwież klawisze

Implementacje klucza PagingSource muszą określać, jak odświeżanie ma być wznawiane między wczytywanymi danymi stron. Zrób to, implementując getRefreshKey() aby zmapować poprawny klucz początkowy, używając state.anchorPosition jako najnowszego uzyskano indeks.

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

Wyświetlenie listy przekształceń

W starszych wersjach biblioteki stronicowania przekształcanie danych z podziałem na strony w przypadku tych metod:

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

W stronicowaniu 3 wszystkie przekształcenia są stosowane jako operatory w elemencie PagingData. Jeśli użyjesz dowolnej z metod z poprzedniej listy do przekształcenia listy stronicowanej, musisz przenieść logikę transformacji z instancji DataSource do PagingData podczas tworzenia Pager za pomocą nowego PagingSource.

Aby dowiedzieć się więcej o stosowaniu przekształceń do danych stronicowanych za pomocą strony 3, przeczytaj artykuł Przekształcanie strumieni danych –

Lista z podziałem na strony

W tej sekcji opisano wszystkie zmiany niezbędne do przeniesienia starszych stron jak używać Pager i PagingData na stronie Paging 3.

Klasy PagedListBuilder

PagingData zastępuje istniejącą instancję PagedList ze strony Paging 2. Migracja do PagingData, musisz zaktualizować te informacje:

  • Konfiguracja stron została przeniesiona z PagedList.Config do PagingConfig.
  • LivePagedListBuilder i RxPagedListBuilder zostały połączone w pojedyncze zajęcia Pager.
  • Funkcja Pager udostępnia dostrzegalny element Flow<PagingData> z właściwością .flow. Dostępne są też wersje RxJava i LiveData jako właściwości rozszerzeń, są wywoływane z Javy za pomocą metod statycznych i są dostarczane z metody 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);

Aby dowiedzieć się więcej o konfigurowaniu strumienia reaktywnego obiektów PagingData za pomocą Strona 3, patrz Konfigurowanie strumienia Dane stron.

Funkcja BoundaryCallback dla źródeł warstwowych

W przypadku strony 3 Zamieniono: RemoteMediator PagedList.BoundaryCallback jako moduł obsługi stronicowania z sieci i bazy danych.

Aby dowiedzieć się więcej o użyciu RemoteMediator do strony z sieci i bazy danych w Paging 3, zobacz Android Paging ćwiczenie w Codelabs.

PagedListAdapter

W tej sekcji opisano wszystkie zmiany niezbędne do przeniesienia starszych stron implementacja, aby używać klas PagingDataAdapter lub AsyncPagingDataDiffer ze strony 3.

Strona 3 zapewnia właściwość PagingDataAdapter do obsługi nowej odpowiedzi reaktywnej PagingData strumienie. W przeciwnym razie PagedListAdapter i PagingDataAdapter mają takie same wartości za pomocą prostego interfejsu online. Aby przeprowadzić migrację z PagedListAdapter do PagingDataAdapter, zmień implementacja PagedListAdapter, aby w zamian rozszerzenie PagingDataAdapter.

Aby dowiedzieć się więcej o PagingDataAdapter, zapoznaj się z artykułem Definiowanie widoku RecyclerView .

AsyncPagedListDiffer

Jeśli obecnie używasz niestandardowej implementacji RecyclerView.Adapter z parametrami AsyncPagedListDiffer, przenieś swoją implementację, aby korzystała z Zamiast tego podano AsyncPagingDataDiffer w funkcji Paging 3:

Kotlin

AsyncPagingDataDiffer(diffCallback, listUpdateCallback)

Java

new AsyncPagingDataDiffer(diffCallback, listUpdateCallback);

Java

new AsyncPagingDataDiffer(diffCallback, listUpdateCallback);

Dodatkowe materiały

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

Ćwiczenia z programowania

Próbki

. .