نقل البيانات إلى التنقل في الصفحات رقم 3

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

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

مزايا الانتقال إلى الصفحة 3

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

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

نقل تطبيقك إلى الانتقال إلى الصفحة 3

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

  • صفان (DataSource)
  • PagedList
  • PagedListAdapter

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

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

تشرح الأقسام في هذه الصفحة كيفية ترحيل مكونات الانتقال إلى كل طبقة من طبقات تطبيقك.

فئات DataSource

يوضِّح هذا القسم جميع التغييرات اللازمة لنقل بيانات تنفيذ قديمة لـ "تسجيل الصفحات" من أجل استخدام PagingSource.

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

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

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

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

يجب أن تحدّد عمليات تنفيذ PagingSource كيفية استئناف عمليات إعادة التحميل من منتصف البيانات المقسّمة على صفحات. ويمكنك إجراء ذلك من خلال تنفيذ getRefreshKey() لربط المفتاح الأولي الصحيح باستخدام state.anchorPosition كأحدث فهرس تم الوصول إليه.

Kotlin

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

Java

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

Java

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

إدراج التحويلات

في الإصدارات القديمة من مكتبة تسجيل الصفحات، يعتمد تحويل البيانات المقسّمة على صفحات على الطرق التالية:

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

في الصفحة 3، يتم تطبيق جميع عمليات التحويل كعوامل تشغيل على PagingData. إذا كنت تستخدم أيًّا من الطرق الواردة في القائمة السابقة لتحويل القائمة المقسَّمة إلى صفحات، يجب نقل منطق التحويل من DataSource إلى PagingData عند إنشاء Pager باستخدام PagingSource الجديدة.

للاطّلاع على مزيد من المعلومات حول تطبيق عمليات التحويل على البيانات المقسّمة على صفحات باستخدام الصفحة 3، اطّلِع على مقالة تحويل مصادر البيانات.

قائمة صفحات

يوضِّح هذا القسم جميع التغييرات اللازمة لنقل طريقة تنفيذ قديمة لـ "نقل البيانات" لاستخدام Pager وPagingData في عملية نقل البيانات 3.

صفوف PagedListBuilder

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

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

Kotlin

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)

Java

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

// 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"، يمكنك الاطّلاع على إعداد مصدر بيانات PagingData.

BoundaryCallback للمصادر ذات الطبقات

في التقسيم 3، يتم استبدال RemoteMediator بالرمز PagedList.BoundaryCallback كمعالج لنقل البيانات من الشبكة وقاعدة البيانات.

لمعرفة المزيد من المعلومات حول استخدام RemoteMediator للصفحة من الشبكة وقاعدة البيانات في التقسيم 3، يمكنك الاطّلاع على الدرس التطبيقي حول ترميز ترتيب الصفحات في Android.

محوِّل PagedListAdapter

يوضِّح هذا القسم جميع التغييرات اللازمة لنقل طريقة تنفيذ قديمة لـ "نقل البيانات" لاستخدام فئات PagingDataAdapter أو AsyncPagingDataDiffer من صفحة "تسجيل الصفحات 3".

توفّر عملية الترتيب في الصفحة 3 PagingDataAdapter للتعامل مع مجموعات البث التفاعلية PagingData الجديدة. وبخلاف ذلك، لدى PagedListAdapter وPagingDataAdapter الواجهة نفسها. لنقل البيانات من PagedListAdapter إلى PagingDataAdapter، عليك تغيير عملية تنفيذ PagedListAdapter لتمديد PagingDataAdapter بدلاً من ذلك.

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

AsyncPagedListDiffer

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

Kotlin

AsyncPagingDataDiffer(diffCallback, listUpdateCallback)

Java

new AsyncPagingDataDiffer(diffCallback, listUpdateCallback);

Java

new AsyncPagingDataDiffer(diffCallback, listUpdateCallback);

مراجع إضافية

لمعرفة المزيد من المعلومات حول مكتبة تسجيل الصفحات، اطّلِع على المراجع الإضافية التالية:

الدروس التطبيقية حول الترميز

عيّنات