Biblioteka stronnicza zapewnia zaawansowane możliwości wczytywania i wyświetlania
z większego zbioru danych. Ten przewodnik pokazuje, jak korzystać ze stronicowania
do konfigurowania strumienia danych stronicowanych z sieciowego źródła danych
go w RecyclerView
.
Zdefiniuj źródło danych
Pierwszym krokiem jest zdefiniowanie
Wdrożenie PagingSource
do zidentyfikowania źródła danych. Klasa interfejsu API PagingSource
zawiera
load()
.
, którą zmieniasz, aby wskazać sposób pobierania danych stronicowanych z
odpowiadającemu źródłu danych.
Używaj bezpośrednio klasy PagingSource
do używania współrzędnych Kotlina na potrzeby asynchronicznego
wczytuję. Biblioteka stronnicza zawiera też klasy obsługujące inne asynchroniczne
platformy:
- Aby korzystać z RxJava, zaimplementuj
RxPagingSource
. - Aby użyć dodatku
ListenableFuture
z Guawy, zaimplementujListenableFuturePagingSource
. .
Wybierz typy kluczy i wartości
Funkcja PagingSource<Key, Value>
ma 2 parametry typu: Key
i Value
. Klucz
określa identyfikator używany do wczytywania danych, a wartością jest typ
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 źródła strony
W poniższym przykładzie zastosowano model
PagingSource
, który się wczytuje
stron elementów według numeru strony. Typ Key
to Int
, a typ Value
to
User
Kotlin
class ExamplePagingSource( val backend: ExampleBackendService, val query: String ) : PagingSource<Int, User>() { override suspend fun load( params: LoadParams<Int> ): LoadResult<Int, User> { 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 = response.nextPageNumber ) } 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) } } }
Java
class ExamplePagingSource extends RxPagingSource<Integer, User> { @NonNull private ExampleBackendService mBackend; @NonNull private String mQuery; ExamplePagingSource(@NonNull ExampleBackendService backend, @NonNull String query) { mBackend = backend; mQuery = query; } @NotNull @Override public Single<LoadResult<Integer, User>> loadSingle( @NotNull LoadParams<Integer> params) { // Start refresh at page 1 if undefined. Integer nextPageNumber = params.getKey(); if (nextPageNumber == null) { nextPageNumber = 1; } return mBackend.searchUsers(mQuery, nextPageNumber) .subscribeOn(Schedulers.io()) .map(this::toLoadResult) .onErrorReturn(LoadResult.Error::new); } private LoadResult<Integer, User> toLoadResult( @NonNull SearchUserResponse response) { return new LoadResult.Page<>( response.getUsers(), null, // Only paging forward. response.getNextPageNumber(), LoadResult.Page.COUNT_UNDEFINED, LoadResult.Page.COUNT_UNDEFINED); } @Nullable @Override public Integer getRefreshKey(@NotNull PagingState<Integer, User> state) { // 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. Integer anchorPosition = state.getAnchorPosition(); if (anchorPosition == null) { return null; } LoadResult.Page<Integer, User> anchorPage = state.closestPageToPosition(anchorPosition); if (anchorPage == null) { return null; } Integer prevKey = anchorPage.getPrevKey(); if (prevKey != null) { return prevKey + 1; } Integer nextKey = anchorPage.getNextKey(); if (nextKey != null) { return nextKey - 1; } return null; } }
Java
class ExamplePagingSource extends ListenableFuturePagingSource<Integer, User> { @NonNull private ExampleBackendService mBackend; @NonNull private String mQuery; @NonNull private Executor mBgExecutor; ExamplePagingSource( @NonNull ExampleBackendService backend, @NonNull String query, @NonNull Executor bgExecutor) { mBackend = backend; mQuery = query; mBgExecutor = bgExecutor; } @NotNull @Override public ListenableFuture<LoadResult<Integer, User>> loadFuture(@NotNull LoadParams<Integer> params) { // Start refresh at page 1 if undefined. Integer nextPageNumber = params.getKey(); if (nextPageNumber == null) { nextPageNumber = 1; } ListenableFuture<LoadResult<Integer, User>> pageFuture = Futures.transform(mBackend.searchUsers(mQuery, nextPageNumber), this::toLoadResult, mBgExecutor); ListenableFuture<LoadResult<Integer, User>> partialLoadResultFuture = Futures.catching(pageFuture, HttpException.class, LoadResult.Error::new, mBgExecutor); return Futures.catching(partialLoadResultFuture, IOException.class, LoadResult.Error::new, mBgExecutor); } private LoadResult<Integer, User> toLoadResult(@NonNull SearchUserResponse response) { return new LoadResult.Page<>(response.getUsers(), null, // Only paging forward. response.getNextPageNumber(), LoadResult.Page.COUNT_UNDEFINED, LoadResult.Page.COUNT_UNDEFINED); } @Nullable @Override public Integer getRefreshKey(@NotNull PagingState<Integer, User> state) { // 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. Integer anchorPosition = state.getAnchorPosition(); if (anchorPosition == null) { return null; } LoadResult.Page<Integer, User> anchorPage = state.closestPageToPosition(anchorPosition); if (anchorPage == null) { return null; } Integer prevKey = anchorPage.getPrevKey(); if (prevKey != null) { return prevKey + 1; } Integer nextKey = anchorPage.getNextKey(); if (nextKey != null) { return nextKey - 1; } return null; } }
Typowa implementacja PagingSource
przekazuje parametry podane w
do metody load()
, aby wczytać dane odpowiednie dla zapytania. W
te parametry to:
backend
: instancja usługi backendu, która dostarcza danequery
: zapytanie, które ma zostać wysłane do usługi wskazywanej przez parametrbackend
.
LoadParams
zawiera informacje o operacji wczytywania, która ma zostać wykonana. Ten
zawiera klucz do załadowania oraz liczbę elementów do załadowania.
LoadResult
zawiera wynik operacji wczytywania. LoadResult
to zapleczona klasa
który ma jedną z dwóch form, w zależności od tego, czy wywołanie load()
zakończyło się sukcesem:
- Jeśli wczytywanie się uda, zwróć obiekt
LoadResult.Page
. - Jeśli wczytywanie się nie powiedzie, zwróć obiekt
LoadResult.Error
.
Poniższy rysunek pokazuje, jak funkcja load()
w tym przykładzie
odbiera klucz przy każdym obciążeniu i dostarcza go na potrzeby kolejnego wczytywania.
load()
wykorzystuje i aktualizuje klucz.
Implementacja PagingSource
musi też implementować
getRefreshKey()
.
która pobiera
PagingState
jako
. Zwraca klucz przekazywany do metody load()
, gdy dane są
odświeżony lub unieważniony po początkowym wczytaniu. Biblioteka stron internetowych nazywa tę funkcję
przy kolejnych odświeżeniach danych.
Obsługa błędów
Żądania wczytania danych mogą zakończyć się niepowodzeniem z różnych powodów, zwłaszcza podczas wczytywania
w sieci. Zgłoś błędy napotkane podczas wczytywania przez zwrócenie
Obiekt LoadResult.Error
z metody load()
.
Możesz na przykład wychwytywać i zgłaszać błędy wczytywania w programie ExamplePagingSource
z poprzedniego przykładu, dodając do metody load()
ten kod:
Kotlin
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) }
Java
return backend.searchUsers(searchTerm, nextPageNumber) .subscribeOn(Schedulers.io()) .map(this::toLoadResult) .onErrorReturn(LoadResult.Error::new);
Java
ListenableFuture<LoadResult<Integer, User>> pageFuture = Futures.transform( backend.searchUsers(query, nextPageNumber), this::toLoadResult, bgExecutor); ListenableFuture<LoadResult<Integer, User>> partialLoadResultFuture = Futures.catching( pageFuture, HttpException.class, LoadResult.Error::new, bgExecutor); return Futures.catching(partialLoadResultFuture, IOException.class, LoadResult.Error::new, bgExecutor);
Więcej informacji o postępowaniu w przypadku błędów Retrofit znajdziesz w przykładach w
Dokumentacja API PagingSource
.
PagingSource
zbiera i dostarcza LoadResult.Error
obiekty do UI,
co możesz zrobić. Więcej informacji o ujawnianiu stanu wczytywania
w interfejsie, przeczytaj artykuł Zarządzanie wczytywaniem i prezentowanie go
.
Konfigurowanie strumienia PagingData
Następnie potrzebny będzie strumień danych z podziałem na strony z implementacji PagingSource
.
Skonfiguruj strumień danych w narzędziu ViewModel
.
Klasa Pager
udostępnia metody, które
ujawnimy w reakcji strumień
PagingData
obiektów z
PagingSource
Biblioteka stron docelowych obsługuje kilka typów strumieni:
w tym Flow
, LiveData
oraz typy Flowable
i Observable
z
RxJava.
Gdy utworzysz instancję Pager
, aby skonfigurować strumień reaktywny, musisz
udostępnia instancji
Konfiguracja PagingConfig
i funkcję, która informuje Pager
, jak pobrać wystąpienie Twojego
Implementacja PagingSource
:
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);
Operator cachedIn()
umożliwia udostępnianie strumienia danych i zapisuje wczytywany strumień w pamięci podręcznej
za pomocą podanej metody CoroutineScope
. W tym przykładzie użyto atrybutu viewModelScope
dostarczone przez artefakt cyklu życia lifecycle-viewmodel-ktx
.
Obiekt Pager
wywołuje metodę load()
z obiektu PagingSource
,
i udostępnianiu
LoadParams
obiekt
i otrzymujesz
Obiekt LoadResult
w zamian.
Definiowanie adaptera RecyclerView
Musisz też skonfigurować adapter, aby odbierać dane na urządzeniu RecyclerView
z listy. Biblioteka stron internetowych udostępnia klasę PagingDataAdapter
do tego celu
cel.
Zdefiniuj klasę, która rozszerza zakres PagingDataAdapter
. W tym przykładzie
UserAdapter
wydłuża okres PagingDataAdapter
o RecyclerView
adapter dla elementów listy typu User
i korzystania z UserViewHolder
jako widoku
posiadacz:
Kotlin
class UserAdapter(diffCallback: DiffUtil.ItemCallback<User>) : PagingDataAdapter<User, UserViewHolder>(diffCallback) { override fun onCreateViewHolder( parent: ViewGroup, viewType: Int ): UserViewHolder { return UserViewHolder(parent) } override fun onBindViewHolder(holder: UserViewHolder, position: Int) { val item = getItem(position) // Note that item can be null. ViewHolder must support binding a // null item as a placeholder. holder.bind(item) } }
Java
class UserAdapter extends PagingDataAdapter<User, UserViewHolder> { UserAdapter(@NotNull DiffUtil.ItemCallback<User> diffCallback) { super(diffCallback); } @NonNull @Override public UserViewHolder onCreateViewHolder(@NonNull ViewGroup parent, int viewType) { return new UserViewHolder(parent); } @Override public void onBindViewHolder(@NonNull UserViewHolder holder, int position) { User item = getItem(position); // Note that item can be null. ViewHolder must support binding a // null item as a placeholder. holder.bind(item); } }
Java
class UserAdapter extends PagingDataAdapter<User, UserViewHolder> { UserAdapter(@NotNull DiffUtil.ItemCallback<User> diffCallback) { super(diffCallback); } @NonNull @Override public UserViewHolder onCreateViewHolder(@NonNull ViewGroup parent, int viewType) { return new UserViewHolder(parent); } @Override public void onBindViewHolder(@NonNull UserViewHolder holder, int position) { User item = getItem(position); // Note that item can be null. ViewHolder must support binding a // null item as a placeholder. holder.bind(item); } }
Przejściówka musi również określać onCreateViewHolder()
i
onBindViewHolder()
i określ
DiffUtil.ItemCallback
.
Działa to tak samo jak podczas definiowania listy RecyclerView
adaptery:
Kotlin
object UserComparator : DiffUtil.ItemCallback<User>() { override fun areItemsTheSame(oldItem: User, newItem: User): Boolean { // Id is unique. return oldItem.id == newItem.id } override fun areContentsTheSame(oldItem: User, newItem: User): Boolean { return oldItem == newItem } }
Java
class UserComparator extends DiffUtil.ItemCallback<User> { @Override public boolean areItemsTheSame(@NonNull User oldItem, @NonNull User newItem) { // Id is unique. return oldItem.id.equals(newItem.id); } @Override public boolean areContentsTheSame(@NonNull User oldItem, @NonNull User newItem) { return oldItem.equals(newItem); } }
Java
class UserComparator extends DiffUtil.ItemCallback<User> { @Override public boolean areItemsTheSame(@NonNull User oldItem, @NonNull User newItem) { // Id is unique. return oldItem.id.equals(newItem.id); } @Override public boolean areContentsTheSame(@NonNull User oldItem, @NonNull User newItem) { return oldItem.equals(newItem); } }
Wyświetlanie danych stronicowanych w interfejsie
Zdefiniowano już PagingSource
, a teraz aplikacja może
a generowany jest strumień o wartości PagingData
i definiowany jest PagingDataAdapter
, jesteś
aby połączyć te elementy i wyświetlić dane stron
działania.
Wykonaj te czynności w onCreate
lub we fragmencie aktywności
Metoda onViewCreated
:
- Utwórz instancję klasy
PagingDataAdapter
. - Przekaż instancję
PagingDataAdapter
doRecyclerView
. na której mają być wyświetlane dane stronicowane. - Obserwuj strumień
PagingData
i przekazuj każdą wygenerowaną wartość do swojego metodysubmitData()
adaptera.
Kotlin
val viewModel by viewModels<ExampleViewModel>() val pagingAdapter = UserAdapter(UserComparator) val recyclerView = findViewById<RecyclerView>(R.id.recycler_view) recyclerView.adapter = pagingAdapter // Activities can use lifecycleScope directly; fragments use // viewLifecycleOwner.lifecycleScope. lifecycleScope.launch { viewModel.flow.collectLatest { pagingData -> pagingAdapter.submitData(pagingData) } }
Java
ExampleViewModel viewModel = new ViewModelProvider(this) .get(ExampleViewModel.class); UserAdapter pagingAdapter = new UserAdapter(new UserComparator()); RecyclerView recyclerView = findViewById<RecyclerView>( R.id.recycler_view); recyclerView.adapter = pagingAdapter viewModel.flowable // Using AutoDispose to handle subscription lifecycle. // See: https://github.com/uber/AutoDispose. .to(autoDisposable(AndroidLifecycleScopeProvider.from(this))) .subscribe(pagingData -> pagingAdapter.submitData(lifecycle, pagingData));
Java
ExampleViewModel viewModel = new ViewModelProvider(this) .get(ExampleViewModel.class); UserAdapter pagingAdapter = new UserAdapter(new UserComparator()); RecyclerView recyclerView = findViewById<RecyclerView>( R.id.recycler_view); recyclerView.adapter = pagingAdapter // Activities can use getLifecycle() directly; fragments use // getViewLifecycleOwner().getLifecycle(). viewModel.liveData.observe(this, pagingData -> pagingAdapter.submitData(getLifecycle(), pagingData));
Na liście RecyclerView
są teraz wyświetlane dane stronicowane ze źródła danych oraz
w razie potrzeby automatycznie wczytuje inną stronę.
Dodatkowe materiały
Więcej informacji o bibliotece stronicowania znajdziesz w tych dodatkowych materiałach:
Ćwiczenia z programowania
Próbki
- Tworzenie stron dla komponentów architektury Androida fragment
- Tworzenie stron dla komponentów architektury Androida z użyciem sieci fragment
Polecane dla Ciebie
- Uwaga: tekst linku wyświetla się, gdy JavaScript jest wyłączony
- Strona z sieci i bazy danych
- Migracja do Paging 3
- Omówienie biblioteki AMP