העברה לדפים 3

‫Paging 3 שונה באופן משמעותי מגרסאות קודמות של ספריית Paging. הגרסה הזו מספקת פונקציונליות משופרת ונותנת מענה לקשיים נפוצים בשימוש ב-Paging 2. אם האפליקציה שלכם כבר משתמשת בגרסה מוקדמת יותר של ספריית Paging, כדאי לקרוא את הדף הזה כדי לקבל מידע נוסף על מעבר ל-Paging 3.

אם Paging 3 היא הגרסה הראשונה של ספריית Paging שבה אתם משתמשים באפליקציה, תוכלו לקרוא את המאמר טעינה והצגה של נתונים עם חלוקה לדפים כדי לקבל מידע בסיסי על השימוש.

היתרונות של מעבר ל-Paging 3

‫Paging 3 כולל את התכונות הבאות שלא היו קיימות בגרסאות קודמות של הספרייה:

  • תמיכה ברמה גבוהה בשגרות המשנה של Kotlin וב-Flow.
  • תמיכה בטעינה אסינכרונית באמצעות פרימיטיבים של RxJava‏ Single או Guava‏ ListenableFuture.
  • מצב טעינה מובנה ואותות שגיאה לעיצוב ממשק משתמש רספונסיבי, כולל פונקציונליות של ניסיון חוזר ורענון.
  • שיפורים בשכבת המאגר, כולל תמיכה בביטול וממשק פשוט יותר למקורות נתונים.
  • שיפורים בשכבת ההצגה, במפרידי הרשימות, בהמרות של דפים בהתאמה אישית ובכותרות העליונות והתחתונות של מצב הטעינה.

העברת האפליקציה ל-Paging 3

כדי לעבור באופן מלא ל-Paging 3, צריך להעביר את כל שלושת הרכיבים העיקריים מ-Paging 2:

  • DataSource כיתות
  • PagedList
  • PagedListAdapter

עם זאת, חלק מהרכיבים של Paging 3 תואמים לאחור לגרסאות קודמות של Paging. בפרט, ה-API‏ PagingSource מ-Paging 3 יכול להיות מקור נתונים ל-LivePagedListBuilder ול-RxPagedListBuilder מגרסאות ישנות יותר. באופן דומה, אפשר להשתמש ב-API‏ Pager כדי לעבוד עם אובייקטים ישנים יותר של DataSource באמצעות השיטה asPagingSourceFactory(). כלומר, יש לכם את האפשרויות הבאות להעברה:

  • אתם יכולים להעביר את DataSource ל-PagingSource אבל להשאיר את שאר ההטמעה של הפונקציה Paging ללא שינוי.
  • אפשר להעביר את PagedList וPagedListAdapter אבל עדיין להשתמש ב-API הישן יותר DataSource.
  • אתם יכולים להעביר את כל ההטמעה של Paging כדי להעביר את האפליקציה שלכם באופן מלא ל-Paging 3.

בקטעים שבדף הזה מוסבר איך להעביר רכיבי עימוד בכל שכבה של האפליקציה.

DataSource כיתות

בקטע הזה מתוארים כל השינויים הנדרשים כדי להעביר הטמעה ישנה של פונקציית הדפדוף לשימוש ב-PagingSource.

ה-API‏ PageKeyedDataSource, PositionalDataSource ו-ItemKeyedDataSource מ-Paging 2 משולבים כולם ב-API‏ PagingSource ב-Paging 3. שיטות הטעינה מכל המחלקות הישנות של ה-API משולבות בשיטה אחת של load() ב-PagingSource. השימוש בשיטה הזו מפחית את הכפילות בקוד, כי הרבה מהלוגיקה בשיטות הטעינה בהטמעות של מחלקות ה-API הישנות זהה.

כל הפרמטרים של שיטת הטעינה מוחלפים ב-Paging 3 במחלקה LoadParams sealed, שכוללת מחלקות משנה לכל סוג טעינה. אם אתם צריכים להבחין בין סוגי הטעינה בשיטה load(), בדקו איזו מחלקת משנה של LoadParams הועברה: LoadParams.Refresh,‏ LoadParams.Prepend או LoadParams.Append.

מידע נוסף על הגדרת מקור נתוניםPagingSource

רענון המקשים

בהטמעות של PagingSource צריך להגדיר איך הרענונים מתחדשים באמצע הנתונים שנטענו בדפים. כדי לעשות זאת, מטמיעים את התג getRefreshKey() כדי למפות את המפתח ההתחלתי הנכון באמצעות state.anchorPosition בתור האינדקס האחרון שאליו הייתה גישה.

Kotlin

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

Java

// Replaces ItemKeyedDataSource.
@Nullable
@Override
String getRefreshKey(state: PagingState<String, User>) {
  Integer anchorPosition = state.anchorPosition;
  if (anchorPosition == null) {
    return null;
  }

  return state.getClosestItemToPosition(anchorPosition);
}

// Replaces PositionalDataSource.
@Nullable
@Override
Integer getRefreshKey(state: PagingState<Integer, User>) {
  return state.anchorPosition;
}

Java

// Replacing ItemKeyedDataSource.
@Nullable
@Override
String getRefreshKey(state: PagingState<String, User>) {
  Integer anchorPosition = state.anchorPosition;
  if (anchorPosition == null) {
    return null;
  }

  return state.getClosestItemToPosition(anchorPosition);
}

// Replacing PositionalDataSource.
@Nullable
@Override
Integer getRefreshKey(state: PagingState<Integer, User>) {
  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, צריך לעדכן את הפרטים הבאים:

  • ההגדרה של החלוקה לדפים הועברה מ-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 באמצעות Paging 3 זמין במאמר הגדרת מקור נתונים של PagingData.

‫BoundaryCallback למקורות בשכבות

בספרייה Paging 3, ‏ RemoteMediator מחליף את PagedList.BoundaryCallback כרכיב לטיפול בהחלפה בין דפים מרשת וממסד נתונים.

מידע נוסף על שימוש ב-RemoteMediator כדי להעביר נתונים מרשת וממסד נתונים ב-Paging 3 זמין ב-Android Paging codelab.

PagedListAdapter

ב-Paging 2 נעשה שימוש ב-PagedListAdapter כדי לקשר PagedList ל-RecyclerView. ב-Paging 3, ‏ PagingData מחליף את PagedList. אם אתם מעבירים את האפליקציה לשימוש ב-Jetpack פיתוח נייטיב לממשק המשתמש שלה, אתם לא צריכים מתאם כדי להציג נתונים עם החלפה בין דפים.

במקום זאת, אפשר להשתמש בארטיפקט paging-compose ובשיטת ההרחבה collectAsLazyPagingItems שלו כדי לאסוף פריטים מסוג PagingData ולהציג אותם בפונקציות @Composable כמו LazyColumn.

מידע נוסף על שימוש ב-Paging 3 עם Jetpack פיתוח נייטיב זמין במאמר סקירה כללית על Paging 3.

מקורות מידע נוספים

איפה אפשר למצוא מידע נוסף על ספריית Paging?

Codelabs

דוגמיות