העברה לדפים 3

‫Paging 3 שונה באופן משמעותי מגרסאות קודמות של ספריית Paging. הגרסה הזו מספקת פונקציונליות משופרת, תמיכה ברמה גבוהה ב-Kotlin שגרות המשך (coroutine) וב-Flow, ושילוב חלק עם Jetpack פיתוח נייטיב.

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

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

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

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

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

• ‫DataSource כיתות
• PagedList
• שכבת ההצגה (עד LazyPagingItems)

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

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

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

DataSource כיתות

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

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

כל הפרמטרים של שיטת הטעינה מוחלפים ב-Paging 3 במחלקה LoadParams sealed, שכוללת מחלקות משנה לכל סוג טעינה. אם אתם צריכים להבחין בין סוגי טעינה בשיטה 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, צריך לעדכן את הפרטים הבאים:

• ההגדרה של החלוקה לדפים הועברה מ-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 זמין ב-Android Paging codelab.

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?

מאמרי עזרה

• סקירה כללית של ספריית Paging

צפייה בתוכן

• העברה ל-Paging 3 (Views)