Переход на Paging 3 (Views)

Основные понятия и реализация Jetpack Compose

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

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

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

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

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

Как перенести приложение в Paging 3

Чтобы полностью перейти на Paging 3, необходимо перенести все три основных компонента из Paging 2:

  • DataSource курс
  • PagedList
  • PagedListAdapter

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

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

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

Общие сведения о переходе

Чтобы полностью перейти на Paging 3, сохранив реализацию RecyclerView, необходимо обновить следующие компоненты:

Компонент Paging 2

Замена Paging 3

PageKeyedDataSource

PagingSource

PagedListAdapter

PagingDataAdapter

LivePagedListBuilder

Pager

BoundaryCallback

RemoteMediator

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 в качестве последнего индекса, к которому осуществлялся доступ.

Java (RxJava)

// 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 (Guava/LiveData)

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

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 соответственно.

Java (RxJava)

// 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 (Guava/LiveData)

// 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.

PagedListAdapter

В этом разделе описываются все изменения, необходимые для переноса старой реализации Paging на использование классов PagingDataAdapter или AsyncPagingDataDiffer из Paging 3.

В Paging 2 для привязки PagedList к RecyclerView используется PagedListAdapter. В Paging 3 PagingData заменяет PagedList.

Paging 3 предоставляет PagingDataAdapter для обработки новых реактивных потоков PagingData. В остальном интерфейсы PagedListAdapter и PagingDataAdapter одинаковы. Чтобы перейти с PagedListAdapter на PagingDataAdapter, измените реализацию PagedListAdapter, чтобы расширить PagingDataAdapter.

Чтобы узнать больше о PagingDataAdapter, прочитайте статью Define a RecyclerView adapter (Определение адаптера RecyclerView).

AsyncPagedListDiffer

Если вы используете собственную реализацию RecyclerView.Adapter с AsyncPagedListDiffer, перейдите на AsyncPagingDataDiffer из Paging 3:

Kotlin

AsyncPagingDataDiffer(diffCallback, listUpdateCallback)

Java (RxJava)

new AsyncPagingDataDiffer(diffCallback, listUpdateCallback);

Java (Guava/LiveData)

new AsyncPagingDataDiffer(diffCallback, listUpdateCallback);