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

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

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

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

• التخزين المؤقت في الذاكرة للبيانات المقسَّمة إلى صفحات يساعد ذلك في ضمان استخدام تطبيقك لموارد النظام بكفاءة أثناء التعامل مع البيانات المقسَّمة إلى صفحات.
• إزالة الطلبات المكرّرة تلقائيًا، ما يساعد في ضمان استخدام تطبيقك لنطاق الشبكة الترددي وموارد النظام بكفاءة
• دعم ممتاز لـ Kotlin coroutines وKotlin Flows
• دعم مدمج لمعالجة الأخطاء، بما في ذلك إمكانات إعادة التحميل وإعادة المحاولة

الإعداد

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

dependencies {
  val paging_version = "3.4.2"

  implementation("androidx.paging:paging-common:$paging_version")

  // Jetpack Compose integration
  implementation("androidx.paging:paging-compose:$paging_version")
}

dependencies {
  def paging_version = "3.4.2"

  implementation "androidx.paging:paging-common:$paging_version"

  // Jetpack Compose integration
  implementation "androidx.paging:paging-compose:$paging_version"
}

بنية المكتبة

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

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

يصف هذا القسم مكوّنات مكتبة 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()
            }
        }
    }
}
LazyListSnippets.kt

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