نظرة عامة على مكتبة Paging   جزء من Android Jetpack

تساعدك مكتبة Paging في تحميل وعرض صفحات البيانات من مجموعة بيانات أكبر من مساحة التخزين المحلية أو عبر شبكة. يتيح هذا الأسلوب لتطبيقك استخدام كل من النطاق الترددي للشبكة وموارد النظام بكفاءة أكبر. تم تصميم مكوّنات مكتبة Paging لتتلاءم مع بنية تطبيقات Android المقترَحة، وتتكامل بسلاسة مع مكوّنات Jetpack الأخرى، وتوفّر دعمًا من الدرجة الأولى للغة Kotlin.

مزايا استخدام مكتبة Paging

تتضمّن مكتبة Paging الميزات التالية:

  • التخزين المؤقت في الذاكرة للبيانات المقسّمة إلى صفحات يساعد ذلك في ضمان استخدام تطبيقك لموارد النظام بكفاءة أثناء العمل مع البيانات المقسّمة إلى صفحات.
  • إزالة الطلبات المكرّرة المضمّنة، ما يساعد في التأكّد من أنّ تطبيقك يستخدم معدل نقل البيانات في الشبكة وموارد النظام بكفاءة
  • دعم مدمج لعمليات Kotlin coroutines وKotlin flows وJetpack Compose
  • دعم مدمج لمعالجة الأخطاء، بما في ذلك إمكانات إعادة التحميل وإعادة المحاولة
  • أدوات اختبار مخصّصة، مثل TestPager وasSnapshot، للتحقّق من مصادر التنقّل بين الصفحات وعمليات تحويل البيانات

الإعداد

لاستيراد مكوّنات Paging إلى تطبيق Android، أضِف التبعيات التالية إلى ملف build.gradle في تطبيقك:

Kotlin

dependencies {
  val paging_version = "3.5.3"

  // Needed for Android Views and LiveData. Optional if only using
  // paging-compose
  implementation("androidx.paging:paging-runtime:$paging_version")

  // Needed to collect PagingData flows in Jetpack Compose
  implementation("androidx.paging:paging-compose:$paging_version")

  // Needed to test PagingSource and PagingData transformations in isolation
  testImplementation("androidx.paging:paging-testing:$paging_version")
}

أنيق

dependencies {
  def paging_version = "3.5.3"

  // Needed for Android Views and LiveData. Optional if only using
  // paging-compose
  implementation "androidx.paging:paging-runtime:$paging_version"

  // Needed to collect PagingData flows in Jetpack Compose
  implementation "androidx.paging:paging-compose:$paging_version"

  // Needed to test PagingSource and PagingData transformations in isolation
  testImplementation "androidx.paging:paging-testing:$paging_version"
}

بنية المكتبة

تعمل مكوّنات مكتبة Paging في ثلاث طبقات من تطبيقك:

  • طبقة المستودع
  • طبقة ViewModel
  • طبقة واجهة المستخدم
صورة تعرض تدفقات البيانات المقسّمة إلى صفحات من مكوّنات PagingSource أو RemoteMediator في طبقة المستودع إلى مكوّن Pager في طبقة ViewModel. بعد ذلك، يعرض مكوّن التنقّل بين الصفحات تدفقًا من PagingData لمكوّنات التنسيق الكسول في طبقة واجهة المستخدم.
الشكل 1: مثال على كيفية دمج مكتبة Paging في بنية تطبيقك

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

طبقة المستودع

مكوّن مكتبة Paging الأساسي في طبقة المستودع هو PagingSource. يحدّد كل عنصر PagingSource مصدرًا للبيانات وكيفية استرداد البيانات من ذلك المصدر. يمكن لكائن PagingSource تحميل البيانات من أي مصدر واحد، بما في ذلك مصادر الشبكة وقواعد البيانات المحلية.

من مكوّنات مكتبة Paging الأخرى التي يمكنك استخدامها RemoteMediator. يتولّى عنصر RemoteMediator معالجة التنقّل بين الصفحات من مصدر بيانات ذي طبقات، مثل مصدر بيانات الشبكة مع ذاكرة تخزين مؤقت لقاعدة بيانات محلية.

طبقة ViewModel

يوفّر مكوّن Pager واجهة برمجة تطبيقات عامة لإنشاء نُسخ من PagingData يتم عرضها في عمليات البث التفاعلية، استنادًا إلى عنصر PagingSource وعنصر إعداد PagingConfig.

المكوّن الذي يربط طبقة ViewModel بواجهة المستخدم هو PagingData. عنصر PagingData هو حاوية للقطة من البيانات المقسّمة إلى صفحات. يستعلم عن كائن PagingSource ويخزن النتيجة.

طبقة واجهة المستخدم

واجهة برمجة التطبيقات الأساسية لواجهة مستخدم Paging هي collectAsLazyPagingItems(). وتعرض العناصر المقسّمة إلى صفحات كقائمة بيانات يمكن استخدامها بسهولة من خلال مكوّنات التنسيق الكسول في Compose، مثل LazyColumn وLazyRow.

أضِف مكتبة androidx.paging:paging-compose لاستخدام واجهات برمجة التطبيقات المتوافقة مع Compose التي تتيح لواجهة المستخدم التفاعل تلقائيًا مع عمليات تحميل البيانات والتحديثات والأخطاء بدون الحاجة إلى محوّلات أو منطق مقارنة. استخدِم دالة الإضافة collectAsLazyPagingItems() في Flow<PagingData> لتمرير LazyPagingItems الذي تم عرضه إلى items() في LazyColumn.

@Composable
fun MessageList(pager: Pager<Int, Message>) {
    val lazyPagingItems = pager.flow.collectAsLazyPagingItems()

    LazyColumn {
        items(
            lazyPagingItems.itemCount,
            key = lazyPagingItems.itemKey { it.id }
        ) { index ->
            val message = lazyPagingItems[index]
            if (message != null) {
                MessageRow(message)
            } else {
                MessagePlaceholder()
            }
        }
    }
}

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