مهاجرت به صفحه 3

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 منتقل شود.

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

کلاس‌های 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 به عنوان آخرین اندیس دسترسی‌شده انجام دهید.

کاتلین 

// Replaces ItemKeyedDataSource.
override fun getRefreshKey(state: PagingState<String, User>): String? {
  return state.anchorPosition?.let { anchorPosition ->
    state.getClosestItemToPosition(anchorPosition)?.id
  }
}

// Replacing PositionalDataSource.
override fun getRefreshKey(state: PagingState<Int, User>): Int? {
  return state.anchorPosition
}

جاوا 

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

جاوا 

// Replacing ItemKeyedDataSource.
@Nullable
@Override
String getRefreshKey(state: PagingState<String, User>) {
  Integer anchorPosition = state.anchorPosition;
  if (anchorPosition == null) {
    return null;
  }

  return state.getClosestItemToPosition(anchorPosition);
}

// Replacing PositionalDataSource.
@Nullable
@Override
Integer getRefreshKey(state: PagingState<Integer, User>) {
  return state.anchorPosition;
}

تبدیل‌های لیست

در نسخه‌های پایین‌تر کتابخانه Paging، تبدیل داده‌های صفحه‌بندی‌شده به روش‌های زیر متکی است:

  • DataSource.map()
  • DataSource.mapByPage()
  • DataSource.Factory.map()
  • DataSource.Factory.mapByPage()

در صفحه‌بندی ۳، تمام تبدیل‌ها به عنوان عملگرها روی PagingData اعمال می‌شوند. اگر از هر یک از روش‌های موجود در لیست قبلی برای تبدیل لیست صفحه‌بندی شده خود استفاده می‌کنید، باید هنگام ساخت Pager با استفاده از PagingSource جدید خود، منطق تبدیل خود را از DataSource به PagingData منتقل کنید.

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

PagedList

این بخش تمام تغییرات لازم برای مهاجرت یک پیاده‌سازی قدیمی‌تر 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 ارائه می‌شوند.

کاتلین 

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)

جاوا 

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

جاوا 

// 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 مراجعه کنید.

BoundaryCallback برای منابع لایه‌ای

در Paging 3، RemoteMediator جایگزین PagedList.BoundaryCallback به عنوان یک هندلر برای صفحه‌بندی از شبکه و پایگاه داده می‌شود.

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

PagedListAdapter

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

در عوض، از مصنوع paging-compose و متد الحاقی collectAsLazyPagingItems آن برای جمع‌آوری آیتم‌های PagingData و نمایش آنها در توابع @Composable مانند LazyColumn استفاده کنید.

برای اطلاعات بیشتر در مورد استفاده از Paging 3 با Jetpack Compose، به «مروری بر Paging 3» مراجعه کنید.

منابع اضافی

برای کسب اطلاعات بیشتر در مورد کتابخانه Paging، به منابع اضافی زیر مراجعه کنید:

کدلبز

نمونه‌ها

{% کلمه به کلمه %} {% فعل کمکی %} {% کلمه به کلمه %} {% فعل کمکی %}