Wczytywanie i wyświetlanie danych z podziałem na strony

Biblioteka Paging zapewnia zaawansowane możliwości wczytywania i wyświetlania danych podzielonych na strony z większego zbioru danych. Z tego przewodnika dowiesz się, jak za pomocą biblioteki Paging skonfigurować strumień danych podzielonych na strony ze źródła danych sieciowych i wyświetlić go na liście leniwej.

Definiowanie źródła danych

Pierwszym krokiem jest zdefiniowanie implementacji PagingSource, aby zidentyfikować źródło danych. Klasa interfejsu API PagingSource zawiera metodę load, którą zastępujesz, aby wskazać, jak pobierać dane podzielone na strony z odpowiedniego źródła danych.

Użyj bezpośrednio klasy PagingSource, aby używać współprogramów Kotlin do asynchronicznego wczytywania.

Wybieranie typów kluczy i wartości

PagingSource<Key, Value> ma 2 parametry typu: Key i Value. Klucz definiuje identyfikator używany do wczytywania danych, a wartość to typ samych danych. Jeśli na przykład wczytujesz strony obiektów User z sieci, przekazując numery stron Int do Retrofit, wybierz Int jako typ Key i User jako typ Value.

Definiowanie klasy PagingSource

W tym przykładzie implementujemy klasę PagingSource, która wczytuje strony elementów według numeru strony. Typ Key to Int, a typ Value to User.

class ExamplePagingSource(
    val backend: ExampleBackendService,
    val query: String
) : PagingSource<Int, User>() {
  override suspend fun load(
    params: LoadParams<Int>
  ): LoadResult<Int, User> {

    init {
        // the data source is expected to be immutable
        // invalidate PagingSource if data source
        // has updated
        backEnd.addDatabaseOnChangedListener {
            invalidate()
        }
    }

    try {
      // Start refresh at page 1 if undefined.
      val nextPageNumber = params.key ?: 1
      val response = backend.searchUsers(query, nextPageNumber)
      return LoadResult.Page(
        data = response.users,
        prevKey = null, // Only paging forward.
        nextKey = nextPageNumber + 1
      )
    } catch (e: Exception) {
      // Handle errors in this block and return LoadResult.Error for
      // expected errors (such as a network failure).
    }
  }

  override fun getRefreshKey(state: PagingState<Int, User>): Int? {
    // Try to find the page key of the closest page to anchorPosition from
    // either the prevKey or the nextKey; you need to handle nullability
    // here.
    //  * prevKey == null -> anchorPage is the first page.
    //  * nextKey == null -> anchorPage is the last page.
    //  * both prevKey and nextKey are null -> anchorPage is the
    //    initial page, so return null.
    return state.anchorPosition?.let { anchorPosition ->
      val anchorPage = state.closestPageToPosition(anchorPosition)
      anchorPage?.prevKey?.plus(1) ?: anchorPage?.nextKey?.minus(1)
    }
  }
}

Typowa implementacja PagingSource przekazuje parametry podane w konstruktorze do metody load, aby wczytać odpowiednie dane dla zapytania. W przykładzie powyżej są to parametry:

  • backend: instancja usługi backendu, która dostarcza dane,
  • query: zapytanie, które ma zostać wysłane do usługi wskazanej przez backend.

Obiekt LoadParams zawiera informacje o operacji wczytywania, która ma zostać wykonana. Obejmuje to klucz do wczytania i liczbę elementów do wczytania. Aby odróżnić typy wczytywania w load, sprawdź, która podklasa LoadParams została przekazana: LoadParams.Refresh, LoadParams.Append lub LoadParams.Prepend.

Obiekt LoadResult zawiera wynik operacji wczytywania. LoadResult to zapieczętowana klasa, która przyjmuje jedną z 3 form w zależności od tego, czy wywołanie load się powiodło:

  • Jeśli wczytywanie się powiedzie, zwróć obiekt LoadResult.Page. Przekaż null dla nextKey lub prevKey, jeśli nie można wczytać więcej danych w tym kierunku.
  • Jeśli wczytywanie się nie powiedzie, zwróć obiekt LoadResult.Error.
  • Jeśli identyfikator PagingSource jest już nieprawidłowy, ponieważ zmieniły się dane źródłowe, zwróć obiekt LoadResult.Invalid.

Ilustracja poniżej pokazuje, jak funkcja load w tym przykładzie otrzymuje klucz dla każdego wczytania i udostępnia klucz dla kolejnego wczytania.

Przy każdym wywołaniu wczytywania ExamplePagingSource pobiera bieżący klucz i zwraca następny klucz do wczytania.
Rysunek 1. Diagram pokazujący, jak load używa klucza i go aktualizuje.

Implementacja PagingSource musi też zawierać metodę getRefreshKey, która przyjmuje obiekt PagingState jako parametr. Zwraca klucz, który należy przekazać do metody load, gdy dane są odświeżane lub unieważniane po początkowym wczytaniu. Biblioteka Paging wywołuje tę metodę automatycznie przy kolejnych odświeżeniach danych. W przypadku stronicowania opartego na przesunięciu, gdzie klucze reprezentują pozycje elementów, możesz obliczyć klucz odświeżania względem state.anchorPosition:

// Only for positional or offset PagingSources where Key is a 0-based item index
// rather than a page number.
override fun getRefreshKey(state: PagingState<Int, User>): Int? {
  // Center the refreshed load around the user's current viewport so the list
  // does not jump back to the top on invalidation.
  return state.anchorPosition?.let { anchorPosition ->
    (anchorPosition - state.config.initialLoadSize / 2).coerceAtLeast(0)
  }
}

Obsługuj błędy

Żądania wczytania danych mogą się nie powieść z różnych powodów, zwłaszcza podczas wczytywania przez sieć. Zgłaszaj błędy napotkane podczas wczytywania, zwracając obiekt LoadResult.Error z metody load.

Możesz na przykład przechwytywać i zgłaszać błędy wczytywania w ExamplePagingSource z poprzedniego przykładu, dodając do metody load ten kod:

catch (e: IOException) {
  // IOException for network failures.
  return LoadResult.Error(e)
} catch (e: HttpException) {
  // HttpException for any non-2xx HTTP status codes.
  return LoadResult.Error(e)
}

Więcej informacji o obsłudze błędów Retrofit znajdziesz w przykładach w dokumentacji interfejsu API PagingSource.

PagingSource zbiera i dostarcza obiekty LoadResult.Error do interfejsu, aby można było wykonywać na nich działania. Więcej informacji o wyświetlaniu stanu wczytywania w interfejsie znajdziesz w artykule Zarządzanie stanami wczytywania i ich prezentowanie.

Konfigurowanie strumienia PagingData

Następnie potrzebujesz strumienia danych ze stron z implementacji PagingSource. Skonfiguruj strumień danych w ViewModel. Klasa Pager udostępnia metody, które ujawniają strumień reaktywny obiektów PagingData z PagingSource. Biblioteka Paging udostępnia strumień danych jako Flow.

Gdy tworzysz instancję Pager, aby skonfigurować strumień reaktywny, musisz podać obiekt konfiguracji PagingConfig i funkcję, która informuje Pager, jak uzyskać instancję implementacji PagingSource. Możesz też określić opcjonalny parametr initialKey, np. 1 w przypadku numerów stron zaczynających się od 1 lub 0 w przypadku stronicowania opartego na przesunięciu. W PagingConfig możesz skonfigurować pageSize, initialLoadSize, prefetchDistance i enablePlaceholders. Właściwość prefetchDistance określa, ile elementów od krawędzi załadowanej treści wywołuje kolejne pobranie.

class UserViewModel(
    private val backend: ExampleBackendService,
    private val query: String
) : ViewModel() {

    val userPagingFlow: Flow<PagingData<User>> = Pager(
        config = PagingConfig(
            pageSize = 20,
            // Load 3 pages initially so the user can scroll immediately without
            // hitting a loading state.
            initialLoadSize = 60,
            // Fetch the next page far enough ahead of the scroll position to
            // avoid visible pauses.
            prefetchDistance = 20,
            enablePlaceholders = true
        ),
        initialKey = 1,
        pagingSourceFactory = {
            ExamplePagingSource(backend, query)
        }
    )
    .flow
    .cachedIn(viewModelScope)
}

Operator cachedIn umożliwia udostępnianie strumienia danych i buforuje wczytane dane za pomocą podanego CoroutineScope. Bez cachedIn nie można odzyskać PagingData. W tym przykładzie używamy viewModelScope dostarczanego przez artefakt cyklu życia lifecycle-viewmodel-ktx.

Obiekt Pager wywołuje metodę load z obiektu PagingSource, przekazując mu obiekt LoadParams i otrzymując w zamian obiekt LoadResult.

Zbieranie i wyświetlanie danych w interfejsie

Aby połączyć strumień z podziałem na strony z interfejsem, pobierz przepływ z ViewModel i przekaż go do funkcji kompozycyjnej listy.

@Composable
fun UserScreen(viewModel: UserViewModel = viewModel()) {
    val userFlow = viewModel.userPagingFlow
    UserList(flow = userFlow)
}

Użyj collectAsLazyPagingItems, aby przekształcić przepływ PagingData w LazyPagingItems. Następnie użyj interfejsu API items w ramach LazyColumn, aby rozmieścić poszczególne elementy.

Pamiętaj, aby podać unikalny, stały identyfikator każdego produktu za pomocą atrybutu itemKey. W poniższym przykładzie użyto it.id (odwołującego się do właściwości User.id), ponieważ pozostaje on stabilny dla instancji User podczas aktualizacji danych.

@Composable
fun UserList(flow: Flow<PagingData<User>>) {
    val lazyPagingItems = flow.collectAsLazyPagingItems()
    LazyColumn {
        items(
            lazyPagingItems.itemCount,
            key = lazyPagingItems.itemKey { it.id }
        ) { index ->
            val user = lazyPagingItems[index]
            if (user != null) {
                UserRow(user)
            } else {
                UserPlaceholder()
            }
        }
    }
}

Biblioteka stronicowania używa wartości null dla obiektów zastępczych podczas wczytywania strony, więc jeśli masz włączone obiekty zastępcze, musisz obsługiwać wartości null w bloku treści.

Teraz lista wyświetla dane podzielone na strony, a biblioteka stronicowania wczytuje dodatkowe strony, gdy użytkownik przewija ekran.

Dodatkowe materiały

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

Dokumentacja

Wyświetla treści