الانتقال إلى Paging 3 (طرق العرض)

المفاهيم وتنفيذ Jetpack Composearrow_forward

يختلف الإصدار 3 من مكتبة Paging بشكلٍ كبير عن الإصدارات السابقة. ويوفّر هذا الإصدار وظائف محسّنة ويعالج الصعوبات الشائعة عند استخدام الإصدار 2 من مكتبة Paging. إذا كان تطبيقك يستخدم إصدارًا سابقًا من مكتبة Paging، يُرجى قراءة هذه الصفحة لمعرفة المزيد عن النقل إلى الإصدار 3 من مكتبة Paging.

إذا كان الإصدار 3 من مكتبة Paging هو أول إصدار تستخدمه في تطبيقك، يُرجى الاطّلاع على مقالة تحميل البيانات المقسَّمة إلى صفحات وعرضها للحصول على معلومات أساسية عن الاستخدام.

مزايا النقل إلى الإصدار 3 من مكتبة Paging

يتضمّن الإصدار 3 من مكتبة Paging الميزات التالية التي لم تكن متوفّرة في الإصدارات السابقة من المكتبة:

• دعم كامل لـ Kotlin coroutines وFlow
• دعم التحميل غير المتزامن باستخدام RxJava Single أو Guava ListenableFuture
• حالات التحميل المضمّنة وإشارات الخطأ لتصميم واجهة مستخدم سريعة الاستجابة، بما في ذلك وظيفة إعادة المحاولة وإعادة التحميل
• تحسينات على طبقة المستودع، بما في ذلك دعم الإلغاء وواجهة مصدر بيانات مبسطة
• تحسينات على طبقة العرض، وفواصل القوائم، وعمليات تحويل الصفحات المخصّصة، ورؤوس وتذييلات حالة التحميل

نقل تطبيقك إلى الإصدار 3 من مكتبة Paging

للنقل بالكامل إلى الإصدار 3 من مكتبة Paging، عليك نقل جميع المكوّنات الرئيسية الثلاثة من الإصدار 2 من مكتبة Paging:

• فئات DataSource
• PagedList
• PagedListAdapter

ومع ذلك، تتوافق بعض مكوّنات الإصدار 3 من مكتبة Paging مع الإصدارات السابقة من مكتبة Paging. على وجه الخصوص، يمكن أن تكون واجهة برمجة التطبيقات PagingSource من الإصدار 3 من مكتبة Paging مصدر بيانات لـ LivePagedListBuilder وRxPagedListBuilder من الإصدارات الأقدم. وبالمثل، يمكن لواجهة برمجة التطبيقات Pager استخدام كائنات DataSource الأقدم من خلال طريقة asPagingSourceFactory. هذا يعني أنّ لديك خيارات النقل التالية:

• يمكنك نقل DataSource إلى PagingSource مع ترك بقية عملية تنفيذ Paging بدون تغيير.
• يمكنك نقل PagedList وPagedListAdapter مع الاستمرار في استخدام واجهة برمجة التطبيقات الأقدم DataSource.
• يمكنك نقل عملية تنفيذ Paging بالكامل لنقل تطبيقك بالكامل إلى الإصدار 3 من مكتبة Paging.

توضّح الأقسام في هذه الصفحة كيفية نقل مكوّنات Paging على كل طبقة من طبقات تطبيقك.

نظرة عامة على عملية النقل

للنقل بالكامل إلى الإصدار 3 من مكتبة Paging مع الاحتفاظ بعملية تنفيذ RecyclerView، عليك تعديل المكوّنات التالية:

فئات DataSource

يصف هذا القسم التغييرات اللازمة لنقل عملية تنفيذ Paging أقدم لاستخدام PagingSource.

يتم دمج PageKeyedDataSource, PositionalDataSource وItemKeyedDataSource من الإصدار 2 من مكتبة Paging في واجهة برمجة التطبيقات PagingSource في الإصدار 3 من مكتبة Paging. يتم دمج طرق التحميل من جميع فئات واجهة برمجة التطبيقات القديمة في طريقة load واحدة في PagingSource. يقلّل ذلك من تكرار الرموز البرمجية لأنّ الكثير من المنطق في طرق التحميل في عمليات تنفيذ فئات واجهة برمجة التطبيقات القديمة غالبًا ما يكون متطابقًا.

يتم استبدال جميع مَعلمات طريقة التحميل في الإصدار 3 من مكتبة Paging بفئة LoadParams المحكمة الإغلاق، والتي تتضمّن فئات فرعية لكل نوع تحميل. إذا كنت بحاجة إلى التمييز بين أنواع التحميل في طريقة load، تحقَّق من الفئة الفرعية لـ LoadParams التي تم تمريرها: LoadParams.Refresh, LoadParams.Prepend أو LoadParams.Append.

لمزيد من المعلومات عن تنفيذ PagingSource، يُرجى الاطّلاع على مقالة تحديد مصدر بيانات.

مفاتيح إعادة التحميل

يجب أن تحدّد عمليات تنفيذ PagingSource كيفية استئناف عمليات إعادة التحميل من منتصف البيانات المقسَّمة إلى صفحات التي تم تحميلها. يمكنك إجراء ذلك من خلال تنفيذ getRefreshKey لربط المفتاح الأولي الصحيح باستخدام 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;
}

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

يصف هذا القسم جميع التغييرات اللازمة لنقل عملية تنفيذ Paging أقدم لاستخدام Pager وPagingData في الإصدار 3 من مكتبة Paging.

فئات PagedListBuilder

يحلّ PagingData محلّ PagedList الحالي من الإصدار 2 من مكتبة Paging. للنقل إلى PagingData، عليك تعديل ما يلي:

• تم نقل إعدادات Paging من PagedList.Config إلى PagingConfig.
• تم دمج LivePagedListBuilder وRxPagedListBuilder في فئة Pager واحدة.

• Pager تعرض عنصر Flow<PagingData> قابل للملاحظة مع .السمة flow. تتوفّر أيضًا متغيرات RxJava وLiveData كسمات إضافية، ويمكن استدعاؤها من Java من خلال طرق ثابتة ويتم توفيرها من وحدتَي paging-rxjava* وpaging-runtime على التوالي.

// 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 باستخدام الإصدار 3 من مكتبة Paging، يُرجى الاطّلاع على مقالة إعداد مصدر PagingData.

PagedListAdapter

يصف هذا القسم جميع التغييرات اللازمة لنقل عملية تنفيذ Paging أقدم لاستخدام فئتَي PagingDataAdapter أو AsyncPagingDataDiffer من الإصدار 3 من مكتبة Paging.

يستخدم الإصدار 2 من مكتبة Paging PagedListAdapter لربط PagedList بـ RecyclerView. في الإصدار 3 من مكتبة Paging، يحلّ PagingData محلّ PagedList.

يوفّر الإصدار 3 من مكتبة Paging PagingDataAdapter للتعامل مع المصادر التفاعلية الجديدة PagingData reactive streams. في ما عدا ذلك، تتطابق واجهة PagedListAdapter وPagingDataAdapter. للنقل من PagedListAdapter إلى PagingDataAdapter، غيِّر عملية تنفيذ PagedListAdapter لتوسيع PagingDataAdapter بدلاً من ذلك.

لمزيد من المعلومات عن PagingDataAdapter، يُرجى الاطّلاع على مقالة تحديد محوّل RecyclerView adapter.

AsyncPagedListDiffer

إذا كنت تستخدم حاليًا عملية تنفيذ مخصّصة لـ RecyclerView.Adapter مع AsyncPagedListDiffer، ننصحك بنقل عملية التنفيذ لاستخدام AsyncPagingDataDiffer المتوفّر في الإصدار 3 من مكتبة Paging بدلاً من ذلك:

AsyncPagingDataDiffer(diffCallback, listUpdateCallback)

new AsyncPagingDataDiffer(diffCallback, listUpdateCallback);

new AsyncPagingDataDiffer(diffCallback, listUpdateCallback);