Migrate to 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 primitives.
  • سیگنال‌های داخلی وضعیت بارگیری و خطا برای طراحی میانای کاربر واکنش‌گرا، ازجمله عملکرد بازآوری و امتحان مجدد.
  • بهبودهایی در لایه مخزن، ازجمله پشتیبانی از لغو و واسط منبع داده ساده‌شده.
  • بهبودهایی در لایه نمایش، جداکننده‌های فهرست، تبدیل‌های صفحه سفارشی، و سرصفحه‌ها و پاصفحه‌های وضعیت بارگیری.

انتقال دادن برنامه به Paging 3

برای انتقال کامل به Paging 3، باید هر سه مؤلفه اصلی را از Paging 2 منتقل کنید:

  • ‫DataSource کلاس
  • PagedList
  • PagedListAdapter

بااین‌حال، برخی‌از مؤلفه‌های Paging 3 با نسخه‌های قبلی Paging سازگار با نسخه قدیمی هستند. به‌ویژه، PagingSource API از Paging 3 می‌تواند منبع داده‌ای برای LivePagedListBuilder و RxPagedListBuilder از نسخه‌های قدیمی‌تر باشد. به‌طور مشابه، Pager API می‌تواند از اشیاء قدیمی‌تر DataSource با روش asPagingSourceFactory استفاده کند. این یعنی گزینه‌های انتقال زیر را دارید:

  • می‌توانید DataSource خود را به PagingSource منتقل کنید اما بقیه پیاده‌سازی صفحه‌بندی را بدون تغییر باقی بگذارید.
  • می‌توانید PagedList و PagedListAdapter را انتقال دهید اما همچنان از میانای برنامه‌سازی کاربردی DataSource قدیمی‌تر استفاده کنید.
  • می‌توانید کل پیاده‌سازی «صفحه‌بندی» را انتقال دهید تا برنامه‌تان را به‌طور کامل به «صفحه‌بندی ۳» انتقال دهید.

بخش‌های این صفحه نحوه انتقال مؤلفه‌های «صفحه‌بندی» را در هر لایه از برنامه‌تان توضیح می‌دهد.

نمای کلی انتقال

برای انتقال کامل به Paging 3 و درعین‌حال حفظ پیاده‌سازی RecyclerView، باید مؤلفه‌های زیر را به‌روز کنید:

Paging 2 Component

جایگزین صفحه‌بندی ۳

PageKeyedDataSource

PagingSource

PagedListAdapter

PagingDataAdapter

LivePagedListBuilder

Pager

BoundaryCallback

RemoteMediator

‫DataSource کلاس

این بخش تغییرات لازم برای انتقال پیاده‌سازی قدیمی‌تر «صفحه‌بندی» برای استفاده از PagingSource را شرح می‌دهد.

‫PageKeyedDataSource, PositionalDataSource و ItemKeyedDataSource از Paging 2 همگی در PagingSource API در Paging 3 ترکیب شده‌اند. روش‌های بار کردن از همه کلاس‌های API قدیمی در یک روش load در PagingSource ترکیب شده‌اند. این کار تکرار کد را کاهش می‌دهد زیرا بخش زیادی از منطق در روش‌های بار کردن در پیاده‌سازی‌های کلاس‌های قدیمی میانای برنامه‌سازی کاربردی اغلب یکسان است.

همه پارامترهای روش بارگیری در 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

این بخش همه تغییرات لازم برای انتقال پیاده‌سازی قدیمی‌تر «صفحه‌بندی» برای استفاده از Pager و PagingData در «صفحه‌بندی ۳» را شرح می‌دهد.

‫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

این بخش همه تغییرات لازم برای انتقال پیاده‌سازی قدیمی‌تر «صفحه‌بندی» را برای استفاده از کلاس‌های PagingDataAdapter یا AsyncPagingDataDiffer از «صفحه‌بندی ۳» شرح می‌دهد.

Paging 2 از PagedListAdapter برای متصل کردن PagedList به RecyclerView استفاده می‌کند. در Paging 3،‏ PagingData جایگزین PagedList می‌شود.

‫Paging 3 برای مدیریت جاری‌سازی‌های واکنشی جدید PagingData، PagingDataAdapter را ارائه می‌دهد. درغیراین‌صورت، PagedListAdapter و PagingDataAdapter واسط یکسانی دارند. برای انتقال از PagedListAdapter به PagingDataAdapter، پیاده‌سازی PagedListAdapter را تغییر دهید تا به‌جای آن PagingDataAdapter را گسترش دهد.

برای کسب اطلاعات بیشتر درباره PagingDataAdapter، به تعریف کردن آداپتور RecyclerView مراجعه کنید.

AsyncPagedListDiffer

اگر درحال‌حاضر از پیاده‌سازی سفارشی RecyclerView.Adapter با AsyncPagedListDiffer استفاده می‌کنید، پیاده‌سازی‌تان را به استفاده از AsyncPagingDataDiffer ارائه‌شده در Paging 3 منتقل کنید:

کاتلین

AsyncPagingDataDiffer(diffCallback, listUpdateCallback)

Java (RxJava)‎

new AsyncPagingDataDiffer(diffCallback, listUpdateCallback);

Java (Guava/LiveData)

new AsyncPagingDataDiffer(diffCallback, listUpdateCallback);