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

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

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

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

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

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

برنامه خود را به 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 خود را انتقال دهید اما همچنان از DataSource API قدیمی‌تر استفاده کنید.
  • می توانید کل پیاده سازی Paging را برای انتقال کامل برنامه خود به Paging 3 منتقل کنید.

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

کلاس های DataSource

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

PageKeyedDataSource ، PositionalDataSource و ItemKeyedDataSource از Paging 2 همگی در PagingSource API در PagingSource 3 ترکیب load() شوند. این باعث کاهش تکرار کد می شود زیرا بسیاری از منطق در روش های بارگذاری در پیاده سازی کلاس های API قدیمی اغلب یکسان است.

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

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

کلیدهای تازه کردن

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

کاتلین 

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

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

جاوا 

// Replaces ItemKeyedDataSource.
@Nullable
@Override
String getRefreshKey(state: PagingState) {
  Integer anchorPosition = state.anchorPosition;
  if (anchorPosition == null) {
    return null;
  }

  return state.getClosestItemToPosition(anchorPosition);
}

// Replaces PositionalDataSource.
@Nullable
@Override
Integer getRefreshKey(state: PagingState) {
  return state.anchorPosition;
}

جاوا 

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

  return state.getClosestItemToPosition(anchorPosition);
}

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

فهرست تبدیل ها

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

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

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

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

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، به نرم افزار Android Paging مراجعه کنید.

PagedListAdapter

این بخش تمام تغییرات لازم برای انتقال پیاده سازی Paging قدیمی برای استفاده از کلاس های PagingDataAdapter یا AsyncPagingDataDiffer از Paging 3 را توضیح می دهد.

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

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

AsyncPagedListDiffer

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

کاتلین 

AsyncPagingDataDiffer(diffCallback, listUpdateCallback)

جاوا 

new AsyncPagingDataDiffer(diffCallback, listUpdateCallback);

جاوا 

new AsyncPagingDataDiffer(diffCallback, listUpdateCallback);

منابع اضافی

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

Codelabs

نمونه ها

{% کلمه به کلمه %} {% آخر کلمه %} {% کلمه به کلمه %} {% آخر کلمه %}