Перейти на страницу 3

Paging 3 значительно отличается от предыдущих версий библиотеки Paging. Эта версия предоставляет расширенную функциональность и устраняет распространенные проблемы, возникающие при использовании Paging 2. Если ваше приложение уже использует более раннюю версию библиотеки Paging, прочтите эту страницу, чтобы узнать больше о переходе на Paging 3.

Если Paging 3 — это первая версия библиотеки Paging, которую вы используете в своем приложении, см. раздел «Загрузка и отображение постраничных данных» для получения основной информации об использовании.

Преимущества перехода на пейджинг 3

В Paging 3 добавлены следующие функции, отсутствовавшие в более ранних версиях библиотеки:

  • Первоклассная поддержка сопрограмм Kotlin и Flow.
  • Поддержка асинхронной загрузки с использованием примитивов RxJava Single или Guava ListenableFuture .
  • Встроенные сигналы состояния загрузки и ошибок для адаптивного дизайна пользовательского интерфейса, включая функции повторной попытки и обновления.
  • Улучшения в уровне репозитория, включая поддержку отмены и упрощенный интерфейс источника данных.
  • Улучшения в уровне представления, разделителях списков, пользовательских преобразованиях страниц, а также заголовках и нижних колонтитулах состояния загрузки.

Переведите ваше приложение на Paging 3.

Для полного перехода на систему пейджинга 3 необходимо перенести все три основных компонента из системы пейджинга 2:

  • Классы DataSource
  • PagedList
  • PagedListAdapter

Однако некоторые компоненты Paging 3 обратно совместимы с предыдущими версиями Paging. В частности, API PagingSource из Paging 3 может служить источником данных для LivePagedListBuilder и RxPagedListBuilder из более старых версий. Аналогично, API Pager может использовать более старые объекты DataSource с помощью метода asPagingSourceFactory() . Это означает, что у вас есть следующие варианты миграции:

  • Вы можете перенести свой DataSource в PagingSource , но оставить остальную часть реализации постраничной навигации без изменений.
  • Вы можете перенести PagedList и PagedListAdapter , но при этом продолжать использовать старый API DataSource .
  • Вы можете перенести всю реализацию постраничной навигации, чтобы полностью перевести ваше приложение на Paging 3.

В разделах этой страницы объясняется, как перенести компоненты постраничной навигации на каждый уровень вашего приложения.

Классы DataSource

В этом разделе описаны все необходимые изменения для миграции более старой реализации Paging на использование PagingSource .

Классы PageKeyedDataSource , PositionalDataSource и ItemKeyedDataSource из Paging 2 объединены в API PagingSource в Paging 3. Методы загрузки из всех старых классов API объединены в один метод load() в PagingSource . Это уменьшает дублирование кода, поскольку большая часть логики в методах загрузки в реализациях старых классов API часто идентична.

В Paging 3 все параметры метода загрузки заменены закрытым классом LoadParams , который включает подклассы для каждого типа загрузки. Если вам необходимо различать типы загрузки в методе load() , проверьте, какой подкласс LoadParams был передан: LoadParams.Refresh , LoadParams.Prepend или LoadParams.Append .

Чтобы узнать больше о реализации PagingSource , см. раздел «Определение источника данных» .

Клавиши обновления

Реализации PagingSource должны определять, как возобновляется обновление с середины загруженных постраничных данных. Для этого необходимо реализовать getRefreshKey() , который сопоставляет правильный начальный ключ, используя state.anchorPosition в качестве наиболее недавно использованного индекса.

Котлин 

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

Преобразования списков

В более старых версиях библиотеки Paging преобразование постраничных данных осуществляется с помощью следующих методов:

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

В Paging 3 все преобразования применяются как операторы к PagingData . Если вы используете какой-либо из методов из приведенного выше списка для преобразования вашего постраничного списка, вам необходимо перенести логику преобразования из DataSource в PagingData при создании Pager с использованием вашего нового PagingSource .

Чтобы узнать больше о применении преобразований к постраничным данным с помощью Paging 3, см. раздел «Преобразование потоков данных» .

PagedList

В этом разделе описаны все необходимые изменения для миграции более старой реализации Paging на использование Pager и PagingData в Paging 3.

Классы PagedListBuilder

PagingData заменяет существующий PagedList из Paging 2. Для перехода на PagingData необходимо обновить следующее:

  • Настройка пейджинга перенесена из PagedList.Config в файл PagingConfig .
  • LivePagedListBuilder и RxPagedListBuilder объединены в один класс Pager .
  • Pager предоставляет наблюдаемый объект Flow<PagingData> с его свойством .flow . Варианты RxJava и LiveData также доступны в качестве свойств расширения, которые вызываются из Java с помощью статических методов и предоставляются модулями paging-rxjava* и paging-runtime соответственно.

Котлин 

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

Чтобы узнать больше о настройке реактивного потока объектов PagingData с использованием Paging 3, см. раздел «Настройка потока PagingData» .

BoundaryCallback для обработки многоуровневых источников

В Paging 3 RemoteMediator заменяет PagedList.BoundaryCallback в качестве обработчика для постраничной навигации из сети и базы данных.

Чтобы узнать больше об использовании RemoteMediator для переадресации страниц из сети и базы данных в Paging 3, см. практическое руководство по Android Paging .

PagedListAdapter

В Paging 2 для привязки PagedList к RecyclerView используется PagedListAdapter . В Paging 3 PagingData заменяется PagedList . Если вы переводите свое приложение на использование Jetpack Compose для пользовательского интерфейса, вам не понадобится адаптер для отображения постраничных данных.

Вместо этого используйте артефакт paging-compose и его метод расширения collectAsLazyPagingItems для сбора элементов PagingData и их отображения в функциях @Composable , таких как LazyColumn .

Для получения дополнительной информации об использовании Paging 3 с Jetpack Compose см. раздел «Обзор Paging 3» .

Дополнительные ресурсы

Чтобы узнать больше о библиотеке пейджинга, ознакомьтесь со следующими дополнительными ресурсами:

Кодлабс

Образцы

{% verbatim %} {% endverbatim %} {% verbatim %} {% endverbatim %}