نظرة عامة على مكتبة تسجيل الصفحات جزء من Android Jetpack.

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

مزايا استخدام مكتبة تسجيل الصفحات

تتضمن مكتبة تسجيل الصفحات الميزات التالية:

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

تقديم ملاحظات

تساعدنا ملاحظاتك في تحسين Jetpack. يُرجى إخبارنا إذا اكتشفت مشاكل جديدة أو كانت لديك أفكار لتحسين هذه المكتبة. يُرجى التحقّق من المشاكل الحالية في هذه المكتبة قبل إنشاء مكتبة جديدة. يمكنك إضافة تصويتك إلى مشكلة حالية من خلال النقر على زر النجمة.

إنشاء عدد جديد

راجع وثائق أداة تتبع المشكلات للحصول على مزيد من المعلومات حول إرسال التعليقات.

ضبط إعدادات

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

Groovy

dependencies {
  def paging_version = "3.3.2"

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

  // alternatively - without Android dependencies for tests
  testImplementation "androidx.paging:paging-common:$paging_version"

  // optional - RxJava2 support
  implementation "androidx.paging:paging-rxjava2:$paging_version"

  // optional - RxJava3 support
  implementation "androidx.paging:paging-rxjava3:$paging_version"

  // optional - Guava ListenableFuture support
  implementation "androidx.paging:paging-guava:$paging_version"

  // optional - Jetpack Compose integration
  implementation "androidx.paging:paging-compose:3.3.2"
}

Kotlin

dependencies {
  val paging_version = "3.3.2"

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

  // alternatively - without Android dependencies for tests
  testImplementation("androidx.paging:paging-common:$paging_version")

  // optional - RxJava2 support
  implementation("androidx.paging:paging-rxjava2:$paging_version")

  // optional - RxJava3 support
  implementation("androidx.paging:paging-rxjava3:$paging_version")

  // optional - Guava ListenableFuture support
  implementation("androidx.paging:paging-guava:$paging_version")

  // optional - Jetpack Compose integration
  implementation("androidx.paging:paging-compose:3.3.2")
}

هندسة المكتبة

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

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

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

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

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

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

طبقة عرضالنموذج

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

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

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

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

يمكنك بدلاً من ذلك استخدام المكوِّن AsyncPagingDataDiffer المضمّن لإنشاء محوِّل مخصّص.

مراجع إضافية

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

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

عيّنات