טעינה והצגה של נתונים בדפים

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

הגדרה של מקור נתונים

השלב הראשון הוא להגדיר הטמעה של PagingSource כדי לזהות את מקור הנתונים. המחלקה PagingSource API כוללת את ה-method load, שאותה אתם משנים כדי לציין איך לאחזר נתונים מחולקים לדפים ממקור הנתונים התואם.

כדי להשתמש ב-coroutines של Kotlin לטעינה אסינכרונית, צריך להשתמש ישירות במחלקה PagingSource.

בחירת סוגי מפתחות וערכים

ל-PagingSource<Key, Value> יש שני פרמטרים של סוג: Key ו-Value. המפתח מגדיר את המזהה שמשמש לטעינת הנתונים, והערך הוא סוג הנתונים עצמם. לדוגמה, אם טוענים דפים של אובייקטים מסוג User מהרשת על ידי העברת מספרי דפים מסוג Int אל Retrofit, בוחרים באפשרות Int בתור הסוג של Key ובאפשרות User בתור הסוג של Value.

הגדרת ה-PagingSource

בדוגמה הבאה מוטמע PagingSource שטוען דפים של פריטים לפי מספר הדף. הסוג של Key הוא Int והסוג של Value הוא User.

class ExamplePagingSource(
    val backend: ExampleBackendService,
    val query: String
) : PagingSource<Int, User>() {
  override suspend fun load(
    params: LoadParams<Int>
  ): LoadResult<Int, User> {

    init {
        // the data source is expected to be immutable
        // invalidate PagingSource if data source
        // has updated
        backEnd.addDatabaseOnChangedListener {
            invalidate()
        }
    }

    try {
      // Start refresh at page 1 if undefined.
      val nextPageNumber = params.key ?: 1
      val response = backend.searchUsers(query, nextPageNumber)
      return LoadResult.Page(
        data = response.users,
        prevKey = null, // Only paging forward.
        nextKey = nextPageNumber + 1
      )
    } catch (e: Exception) {
      // Handle errors in this block and return LoadResult.Error for
      // expected errors (such as a network failure).
    }
  }

  override fun getRefreshKey(state: PagingState<Int, User>): Int? {
    // Try to find the page key of the closest page to anchorPosition from
    // either the prevKey or the nextKey; you need to handle nullability
    // here.
    //  * prevKey == null -> anchorPage is the first page.
    //  * nextKey == null -> anchorPage is the last page.
    //  * both prevKey and nextKey are null -> anchorPage is the
    //    initial page, so return null.
    return state.anchorPosition?.let { anchorPosition ->
      val anchorPage = state.closestPageToPosition(anchorPosition)
      anchorPage?.prevKey?.plus(1) ?: anchorPage?.nextKey?.minus(1)
    }
  }
}

בהטמעה אופיינית של PagingSource, הפרמטרים שסופקו ב-constructor מועברים ל-method‏ load כדי לטעון את הנתונים המתאימים לשאילתה. בדוגמה שלמעלה, הפרמטרים האלה הם:

  • ‫backend: מכונה של שירות לקצה העורפי שמספק את הנתונים
  • ‫query: שאילתת החיפוש שתישלח לשירות שצוין ב-backend

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

האובייקט LoadResult מכיל את התוצאה של פעולת הטעינה. ‫LoadResult היא מחלקה אטומה שיכולה להיות באחת משלוש צורות, בהתאם להצלחה של הקריאה ל-load:

  • אם הטעינה מצליחה, מחזירים אובייקט LoadResult.Page. מעבירים את הערך null עבור nextKey או prevKey אם לא ניתן לטעון נתונים נוספים בכיוון הזה.
  • אם הטעינה נכשלת, מחזירים אובייקט LoadResult.Error.
  • אם ה-PagingSource כבר לא תקף כי הנתונים הבסיסיים השתנו, צריך להחזיר אובייקט LoadResult.Invalid.

באיור הבא אפשר לראות איך הפונקציה load בדוגמה הזו מקבלת את המפתח לכל טעינה ומספקת את המפתח לטעינה הבאה.

בכל קריאה לטעינה, ExamplePagingSource מקבל את המפתח הנוכחי ומחזיר את המפתח הבא לטעינה.
תרשים 1. תרשים שמראה איך load משתמש במפתח ומעדכן אותו.

ההטמעה של PagingSource צריכה להטמיע גם את ה-method‏ getRefreshKey שמקבלת אובייקט PagingState כפרמטר. היא מחזירה את המפתח שצריך להעביר ל-method‏ load כשהנתונים מתרעננים או מתבטלים אחרי הטעינה הראשונית. ספריית Paging קוראת לשיטה הזו באופן אוטומטי ברענונים הבאים של הנתונים. בדפדוף מבוסס-היסט שבו המפתחות מייצגים את מיקומי הפריטים, אפשר לחשב את מפתח הרענון ביחס ל-state.anchorPosition:

// Only for positional or offset PagingSources where Key is a 0-based item index
// rather than a page number.
override fun getRefreshKey(state: PagingState<Int, User>): Int? {
  // Center the refreshed load around the user's current viewport so the list
  // does not jump back to the top on invalidation.
  return state.anchorPosition?.let { anchorPosition ->
    (anchorPosition - state.config.initialLoadSize / 2).coerceAtLeast(0)
  }
}

טיפול בשגיאות

בקשות לטעינת נתונים יכולות להיכשל מכמה סיבות, במיוחד כשמדובר בטעינה דרך רשת. כדי לדווח על שגיאות שנתקלתם בהן במהלך הטעינה, צריך להחזיר אובייקט LoadResult.Error מהשיטה load.

לדוגמה, אפשר לתפוס ולדווח על שגיאות טעינה ב-ExamplePagingSource מהדוגמה הקודמת על ידי הוספת הקוד הבא ל-method‏ load:

catch (e: IOException) {
  // IOException for network failures.
  return LoadResult.Error(e)
} catch (e: HttpException) {
  // HttpException for any non-2xx HTTP status codes.
  return LoadResult.Error(e)
}

מידע נוסף על טיפול בשגיאות Retrofit זמין בדוגמאות שבמאמרי העזרה של ה-API של PagingSource.

‫PagingSource אוסף אובייקטים מסוג LoadResult.Error ומעביר אותם לממשק המשתמש כדי שתוכלו לפעול לגביהם. למידע נוסף על חשיפת מצב הטעינה בממשק המשתמש, ראו ניהול והצגה של מצבי טעינה.

הגדרת זרם של PagingData

בשלב הבא, צריך מקור של נתונים מחולקים לדפים מההטמעה של PagingSource. מגדירים את מקור הנתונים ב-ViewModel. המחלקה Pager מספקת שיטות שחושפות זרם תגובתי של אובייקטים מסוג PagingData מ-PagingSource. ספריית Paging חושפת את זרם הנתונים בתור Flow.

כשיוצרים מכונה של Pager כדי להגדיר את ה-reactive stream, צריך לספק למכונה אובייקט הגדרה של PagingConfig ופונקציה שמציינת ל-Pager איך לקבל מכונה של ההטמעה של PagingSource. אפשר גם לציין initialKey אופציונלי, כמו 1 למספרי דפים שמבוססים על 1 או 0 לדפים שמבוססים על היסט. ב-PagingConfig, אפשר להגדיר את pageSize,‏ initialLoadSize,‏ prefetchDistance ו-enablePlaceholders. המאפיין prefetchDistance מגדיר כמה פריטים מכל קצה של תוכן שנטען מפעילים את השליפה הבאה.

class UserViewModel(
    private val backend: ExampleBackendService,
    private val query: String
) : ViewModel() {

    val userPagingFlow: Flow<PagingData<User>> = Pager(
        config = PagingConfig(
            pageSize = 20,
            // Load 3 pages initially so the user can scroll immediately without
            // hitting a loading state.
            initialLoadSize = 60,
            // Fetch the next page far enough ahead of the scroll position to
            // avoid visible pauses.
            prefetchDistance = 20,
            enablePlaceholders = true
        ),
        initialKey = 1,
        pagingSourceFactory = {
            ExamplePagingSource(backend, query)
        }
    )
    .flow
    .cachedIn(viewModelScope)
}

האופרטור cachedIn מאפשר לשתף את מקור הנתונים ושומר במטמון את הנתונים שנטענו באמצעות ה-CoroutineScope שסופק. בלי cachedIn, אי אפשר להיזכר בPagingData. בדוגמה הזו נעשה שימוש ב-viewModelScope שסופק על ידי פריט המידע שנוצר בתהליך הפיתוח (Artifact) של מחזור החיים lifecycle-viewmodel-ktx.

האובייקט Pager קורא ל-method‏ load מהאובייקט PagingSource, מספק לו את האובייקט LoadParams ומקבל בתמורה את האובייקט LoadResult.

איסוף הנתונים והצגה שלהם בממשק המשתמש

כדי לחבר את ה-stream של הדפים לממשק המשתמש, מקבלים את ה-flow מה-ViewModel ומעבירים אותו לפונקציה הקומפוזבילית של הרשימה.

@Composable
fun UserScreen(viewModel: UserViewModel = viewModel()) {
    val userFlow = viewModel.userPagingFlow
    UserList(flow = userFlow)
}

משתמשים ב-collectAsLazyPagingItems כדי להמיר את התהליך של PagingData ל-LazyPagingItems. לאחר מכן, משתמשים ב-API של items בתוך LazyColumn כדי לפרוס כל פריט.

חשוב לספק מזהה ייחודי וקבוע לכל פריט באמצעות itemKey. בדוגמה הבאה נעשה שימוש ב-it.id (הפניה למאפיין User.id) כי הוא נשאר יציב במכונה של User בעדכוני נתונים.

@Composable
fun UserList(flow: Flow<PagingData<User>>) {
    val lazyPagingItems = flow.collectAsLazyPagingItems()
    LazyColumn {
        items(
            lazyPagingItems.itemCount,
            key = lazyPagingItems.itemKey { it.id }
        ) { index ->
            val user = lazyPagingItems[index]
            if (user != null) {
                UserRow(user)
            } else {
                UserPlaceholder()
            }
        }
    }
}

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

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

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

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

תיעוד

צפייה בתוכן