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

تختلف مكتبة Paging 3 بشكل كبير عن الإصدارات السابقة من مكتبة Paging. يوفّر هذا الإصدار وظائف محسّنة ودعمًا ممتازًا لروتينات Kotlin الفرعية وFlow، بالإضافة إلى إمكانية الدمج بسلاسة مع Jetpack Compose.

مزايا نقل البيانات إلى Paging 3

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

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

نقل تطبيقك إلى Paging 3

لنقل البيانات بالكامل إلى Paging 3، عليك نقل هذه المكوّنات الرئيسية من Paging 2:

  • فئات DataSource
  • PagedList
  • طبقة العرض (إلى LazyPagingItems)

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

  • يمكنك نقل DataSource إلى PagingSource مع ترك بقية عملية تنفيذ Paging بدون تغيير.
  • يمكنك نقل عملية تنفيذ Paging بالكامل لنقل تطبيقك بالكامل إلى Paging 3.

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

فئات DataSource

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

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

يتم استبدال جميع مَعلمات طريقة التحميل في Paging 3 بفئة 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
}

عمليات تحويل القوائم

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

  • DataSource.map
  • DataSource.mapByPage
  • DataSource.Factory.map
  • DataSource.Factory.mapByPage

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

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

PagedList

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

فئات PagedListBuilder

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

  • تم نقل إعدادات Paging من PagedList.Config إلى PagingConfig.
  • تم دمج فئات أداة الإنشاء الأقدم في فئة Pager واحدة.
  • Pager تعرض عنصر Flow<PagingData> قابل للمراقبة باستخدام السمة .flow.
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)

لمزيد من المعلومات حول إعداد مصدر تفاعلي لكائنات PagingData باستخدام Paging 3، يُرجى الاطّلاع على إعداد مصدر PagingData.

BoundaryCallback للمصادر متعددة الطبقات

في Paging 3، يحلّ RemoteMediator محلّ PagedList.BoundaryCallback كـ معالج للتقسيم إلى صفحات من الشبكة وقاعدة البيانات.

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

LazyPagingItems

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

توفّر Paging 3 طريقة collectAsLazyPagingItems لمعالجة مصدر PagingData الجديد. لنقل طبقة العرض، استخدِم العنصر paging-compose وطريقة collectAsLazyPagingItems لجمع عناصر PagingData وعرضها في دوال @Composable.

لمزيد من المعلومات حول LazyPagingItems، يُرجى الاطّلاع على تحميل البيانات المقسّمة إلى صفحات وعرضها.

مقارنة القوائم وتعديلها

إذا كنت تستخدم حاليًا منطقًا مخصّصًا لمقارنة القوائم، ننصحك بنقل عملية التنفيذ لاستخدام LazyPagingItems المتوفّرة في Paging 3 بدلاً من ذلك. للتأكّد من إجراء المقارنة بشكل صحيح، حدِّد مفتاح عنصر في قائمتك الكسولة:

@Composable
fun UserScreen(viewModel: UserViewModel) {
    // Collects the Flow into a LazyPagingItems object
    val lazyPagingItems = viewModel.pager.flow.collectAsLazyPagingItems()

    UserList(lazyPagingItems)
}

@Composable
fun UserScreen(viewModel: UserViewModel) {
    val lazyPagingItems = viewModel.pager.flow.collectAsLazyPagingItems()

    UserList(lazyPagingItems)
}

@Composable
fun UserList(lazyPagingItems: LazyPagingItems<User>) {
    LazyColumn {
        items(
            count = lazyPagingItems.itemCount,
            // Provide a stable key for each item, similar to DiffUtil in Views
            key = lazyPagingItems.itemKey { user -> user.id } 
        ) { index ->
            val user = lazyPagingItems[index]
            if (user != null) {
                UserRow(user = user)
            }
        }
    }
}

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

حالات التحميل

في Paging 3، لست بحاجة إلى محوّل منفصل لعرض الرؤوس أو التذييلات لحالات التحميل. يعرض الكائن LazyPagingItems سمة loadState يمكنك التحقّق منها مباشرةً ضمن LazyColumn.

LazyColumn {
    // ... items(lazyPagingItems) go here ...

    // Show loading spinner at bottom of list when appending data
    if (lazyPagingItems.loadState.append is LoadState.Loading) {
        item {
            CircularProgressIndicator(modifier = Modifier.fillMaxWidth())
        }
    }
}

مراجع إضافية

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

الوثائق

عرض المحتوى