مهاجرت به صفحه‌بندی ۳ (Views)

مفاهیم و پیاده‌سازی Jetpack Compose

Paging 3 تفاوت قابل توجهی با نسخه‌های قبلی کتابخانه Paging دارد. این نسخه قابلیت‌های پیشرفته‌تری را ارائه می‌دهد و مشکلات رایج استفاده از Paging 2 را برطرف می‌کند. اگر برنامه شما از قبل از نسخه قبلی کتابخانه Paging استفاده می‌کند، برای کسب اطلاعات بیشتر در مورد مهاجرت به Paging 3، این صفحه را مطالعه کنید.

اگر Paging 3 اولین نسخه از کتابخانه Paging است که در برنامه خود استفاده می‌کنید، برای اطلاعات اولیه استفاده، به بخش بارگذاری و نمایش داده‌های صفحه‌بندی شده مراجعه کنید.

مزایای مهاجرت به صفحه‌بندی ۳

صفحه‌بندی ۳ شامل ویژگی‌های زیر است که در نسخه‌های قبلی کتابخانه وجود نداشتند:

  • پشتیبانی درجه یک از کوروتین‌های کاتلین و Flow.
  • پشتیبانی از بارگذاری ناهمگام با استفاده از RxJava Single یا Guava ListenableFuture primitives.
  • سیگنال‌های وضعیت بارگذاری و خطای داخلی برای طراحی رابط کاربری واکنش‌گرا، شامل قابلیت تلاش مجدد و به‌روزرسانی.
  • بهبودهایی در لایه مخزن، از جمله پشتیبانی از لغو و رابط کاربری ساده‌شده منبع داده.
  • بهبودهایی در لایه ارائه، جداکننده‌های لیست، تبدیل‌های سفارشی صفحه و بارگذاری هدرها و فوترهای حالت.

برنامه خود را به 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 3 در عین حفظ پیاده‌سازی RecyclerView ، باید اجزای زیر را به‌روزرسانی کنید:

کامپوننت صفحه‌بندی ۲

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

PageKeyedDataSource

PagingSource

PagedListAdapter

PagingDataAdapter

LivePagedListBuilder

Pager

BoundaryCallback

RemoteMediator

کلاس‌های DataSource

این بخش تغییرات لازم برای مهاجرت یک پیاده‌سازی قدیمی‌تر Paging به استفاده از PagingSource را شرح می‌دهد.

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

تمام پارامترهای متد بارگذاری در صفحه‌بندی ۳ با یک کلاس مهر و موم شده LoadParams جایگزین شده‌اند که شامل زیرکلاس‌هایی برای هر نوع بارگذاری است. اگر نیاز دارید بین انواع بارگذاری در متد load خود تمایز قائل شوید، بررسی کنید که کدام زیرکلاس LoadParams ارسال شده است: LoadParams.Refresh, LoadParams.Prepend یا LoadParams.Append .

برای کسب اطلاعات بیشتر در مورد پیاده‌سازی PagingSource ، به بخش تعریف منبع داده مراجعه کنید.

کلیدهای تازه‌سازی

پیاده‌سازی‌های PagingSource باید نحوه‌ی از سرگیری به‌روزرسانی‌ها از اواسط داده‌های صفحه‌بندی‌شده‌ی بارگذاری‌شده را تعریف کنند. این کار را با پیاده‌سازی getRefreshKey برای نگاشت کلید اولیه‌ی صحیح با استفاده از state.anchorPosition به عنوان آخرین اندیس دسترسی‌شده انجام دهید.

جاوا (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;
}

جاوا (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;
}

فهرست صفحه‌ای

این بخش تمام تغییرات لازم برای مهاجرت یک پیاده‌سازی قدیمی‌تر Paging به استفاده از Pager و PagingData در Paging 3 را شرح می‌دهد.

کلاس‌های PagedListBuilder

PagingData جایگزین PagedList موجود از Paging 2 می‌شود. برای مهاجرت به PagingData ، باید موارد زیر را به‌روزرسانی کنید:

  • پیکربندی صفحه‌بندی از PagedList.Config به PagingConfig منتقل شده است.
  • LivePagedListBuilder و RxPagedListBuilder در یک کلاس Pager واحد ترکیب شده‌اند.

  • Pager یک Flow<PagingData> قابل مشاهده را با ویژگی flow خود در معرض نمایش قرار می‌دهد. انواع RxJava و LiveData نیز به عنوان ویژگی‌های افزونه در دسترس هستند که از طریق متدهای استاتیک از جاوا قابل فراخوانی هستند و به ترتیب از ماژول‌های paging-rxjava* و paging-runtime ارائه می‌شوند.

جاوا (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);

جاوا (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 را شرح می‌دهد.

صفحه‌بندی ۲ PagedListAdapter برای اتصال یک PagedList به یک RecyclerView استفاده می‌کند. در صفحه‌بندی ۳، PagingData جایگزین PagedList می‌شود.

صفحه‌بندی ۳، PagingDataAdapter را برای مدیریت جریان‌های واکنشی جدید PagingData فراهم می‌کند. در غیر این صورت، PagedListAdapter و PagingDataAdapter رابط یکسانی دارند. برای مهاجرت از PagedListAdapter به PagingDataAdapter ، پیاده‌سازی PagedListAdapter خود را تغییر دهید تا PagingDataAdapter به ارث ببرد.

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

AsyncPagedListDiffer

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

کاتلین 

AsyncPagingDataDiffer(diffCallback, listUpdateCallback)

جاوا (RxJava) 

new AsyncPagingDataDiffer(diffCallback, listUpdateCallback);

جاوا (Guava/LiveData) 

new AsyncPagingDataDiffer(diffCallback, listUpdateCallback);