סקירה כללית של ספריית Paging 2   בארגז הכלים Android Jetpack.

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

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

הגדרה

כדי לייבא רכיבי Paging לאפליקציה ל-Android, מוסיפים את יחסי התלות הבאים לקובץ build.gradle של האפליקציה:

Groovy

dependencies {
  def paging_version = "2.1.2"

  implementation "androidx.paging:paging-runtime:$paging_version" // For Kotlin use paging-runtime-ktx

  // alternatively - without Android dependencies for testing
  testImplementation "androidx.paging:paging-common:$paging_version" // For Kotlin use paging-common-ktx

  // optional - RxJava support
  implementation "androidx.paging:paging-rxjava2:$paging_version" // For Kotlin use paging-rxjava2-ktx
}

Kotlin

dependencies {
  val paging_version = "2.1.2"

  implementation("androidx.paging:paging-runtime:$paging_version") // For Kotlin use paging-runtime-ktx

  // alternatively - without Android dependencies for testing
  testImplementation("androidx.paging:paging-common:$paging_version") // For Kotlin use paging-common-ktx

  // optional - RxJava support
  implementation("androidx.paging:paging-rxjava2:$paging_version") // For Kotlin use paging-rxjava2-ktx
}

ארכיטקטורת הספרייה

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

PagedList

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

בקטע הקוד הבא אפשר לראות איך מגדירים את מודל התצוגה של האפליקציה כדי לטעון ולהציג נתונים באמצעות מאגר LiveData של אובייקטים מסוג PagedList:

Kotlin

class ConcertViewModel(concertDao: ConcertDao) : ViewModel() {
    val concertList: LiveData<PagedList<Concert>> =
            concertDao.concertsByDate().toLiveData(pageSize = 50)
}

Java

public class ConcertViewModel extends ViewModel {
    private ConcertDao concertDao;
    public final LiveData<PagedList<Concert>> concertList;

    // Creates a PagedList object with 50 items per page.
    public ConcertViewModel(ConcertDao concertDao) {
        this.concertDao = concertDao;
        concertList = new LivePagedListBuilder<>(
                concertDao.concertsByDate(), 50).build();
    }
}

נתונים

כל מכונה של PagedList טוענת תמונת מצב עדכנית של נתוני האפליקציה מהאובייקט DataSource התואם. הנתונים זורמים מה-backend או ממסד הנתונים של האפליקציה אל האובייקט PagedList.

בדוגמה הבאה נעשה שימוש בספריית Room persistence כדי לארגן את נתוני האפליקציה, אבל אם אתם רוצים לאחסן את הנתונים באמצעים אחרים, אתם יכולים גם לספק מפעל משלכם למקורות נתונים.

Kotlin

@Dao
interface ConcertDao {
    // The Int type parameter tells Room to use a PositionalDataSource object.
    @Query("SELECT * FROM concerts ORDER BY date DESC")
    fun concertsByDate(): DataSource.Factory<Int, Concert>
}

Java

@Dao
public interface ConcertDao {
    // The Integer type parameter tells Room to use a
    // PositionalDataSource object.
    @Query("SELECT * FROM concerts ORDER BY date DESC")
    DataSource.Factory<Integer, Concert> concertsByDate();
}

במדריך איך לטעון נתונים מדפים מוסבר איך לטעון נתונים לאובייקטים מסוג PagedList.

ממשק משתמש

הכיתה PagedList פועלת עם PagedListAdapter כדי לטעון פריטים ל-RecyclerView. המחלקות האלה פועלות יחד כדי לאחזר ולהציג תוכן בזמן שהוא נטען, לאחזר מראש תוכן שלא מוצג ולהוסיף אנימציה לשינויים בתוכן.

מידע נוסף זמין במדריך בנושא הצגת רשימות עם דפים.

תמיכה בארכיטקטורות שונות של נתונים

ספריית Paging תומכת בארכיטקטורות הנתונים הבאות:

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

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

זרימת נתונים בארכיטקטורות נתמכות של Paging Library
איור 1. איך הנתונים זורמים בכל אחת מהארכיטקטורות שספריית Paging תומכת בהן.

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

רשת בלבד

כדי להציג נתונים משרת בק-אנד, משתמשים בגרסה הסינכרונית של Retrofit API כדי לטעון מידע לתוך DataSource אובייקט מותאם אישית משלכם.

מסד נתונים בלבד

מגדירים את RecyclerView כך שיצפה באחסון המקומי, רצוי באמצעות ספריית Room persistence. כך, בכל פעם שנתונים מוכנסים או משתנים במסד הנתונים של האפליקציה, השינויים האלה משתקפים באופן אוטומטי ב-RecyclerView שמציג את הנתונים האלה.

רשת ומסד נתונים

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

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

כשמשתמשים ברשת כדי לאחזר או להציג בדפים את הנתונים שמוצגים באמצעות ספריית הדפדוף, חשוב לא להתייחס לרשת כ"זמינה" או "לא זמינה" כל הזמן, כי הרבה חיבורים הם לסירוגין או לא יציבים:

  • יכול להיות ששרת מסוים לא יגיב לבקשה לאחזור מהרשת.
  • יכול להיות שהמכשיר מחובר לרשת איטית או חלשה.

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

עדכון של אפליקציה קיימת

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

פתרונות כריזה בהתאמה אישית

אם אתם משתמשים בפונקציונליות מותאמת אישית כדי לטעון קבוצות משנה קטנות של נתונים ממקור הנתונים של האפליקציה, אתם יכולים להחליף את הלוגיקה הזו בלוגיקה מהמחלקה PagedList. מופעים של PagedList מציעים חיבורים מובְנים למקורות נתונים נפוצים. המופעים האלה מספקים גם מתאמים לאובייקטים מסוג RecyclerView שאפשר לכלול בממשק המשתמש של האפליקציה.

הנתונים נטענים באמצעות רשימות במקום דפים

אם אתם משתמשים ברשימה בזיכרון כמבנה הנתונים לגיבוי של המתאם של ממשק המשתמש, כדאי להשתמש במחלקה PagedList כדי לעקוב אחרי עדכוני הנתונים אם מספר הפריטים ברשימה יכול להיות גדול. מופעים של PagedList יכולים להשתמש ב-LiveData<PagedList> או ב-Observable<List> כדי להעביר עדכוני נתונים לממשק המשתמש של האפליקציה, וכך לצמצם את זמני הטעינה ואת השימוש בזיכרון. יתרה מכך, החלפת אובייקט List באובייקט PagedList באפליקציה לא דורשת שינויים במבנה של ממשק המשתמש או בלוגיקה של עדכון הנתונים באפליקציה.

שיוך סמן נתונים לתצוגת רשימה באמצעות CursorAdapter

יכול להיות שהאפליקציה שלכם משתמשת ב-CursorAdapter כדי לשייך נתונים מ-Cursor ל-ListView. במקרה כזה, בדרך כלל צריך להעביר את האפליקציה מ-ListView ל-RecyclerView בתור מאגר ממשק המשתמש של הרשימה, ואז להחליף את הרכיב Cursor ב-Room או ב-PositionalDataSource, בהתאם לשאלה אם מופעים של Cursor ניגשים למסד נתונים של SQLite.

במצבים מסוימים, כמו כשעובדים עם מכונות של Spinner, צריך לספק רק את המתאם עצמו. לאחר מכן, ספרייה מקבלת את הנתונים שנטענו למתאם הזה ומציגה לכם אותם. במצבים כאלה, צריך לשנות את סוג הנתונים של המתאם ל-LiveData<PagedList>, ואז לעטוף את הרשימה הזו באובייקט ArrayAdapter לפני שמנסים להשתמש במחלקת ספרייה כדי להרחיב את הפריטים האלה בממשק משתמש.

טעינת תוכן באופן אסינכרוני באמצעות AsyncListUtil

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

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

דוגמאות למסדי נתונים

בקטעי הקוד הבאים מוצגות כמה דרכים אפשריות לשילוב בין כל החלקים.

צפייה בנתונים בדפים באמצעות LiveData

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

Kotlin

@Dao
interface ConcertDao {
    // The Int type parameter tells Room to use a PositionalDataSource
    // object, with position-based loading under the hood.
    @Query("SELECT * FROM concerts ORDER BY date DESC")
    fun concertsByDate(): DataSource.Factory<Int, Concert>
}

class ConcertViewModel(concertDao: ConcertDao) : ViewModel() {
    val concertList: LiveData<PagedList<Concert>> =
            concertDao.concertsByDate().toLiveData(pageSize = 50)
}

class ConcertActivity : AppCompatActivity() {
    public override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        // Use the 'by viewModels()' Kotlin property delegate
        // from the activity-ktx artifact
        val viewModel: ConcertViewModel by viewModels()
        val recyclerView = findViewById(R.id.concert_list)
        val adapter = ConcertAdapter()
        viewModel.concertList.observe(this, PagedList(adapter::submitList))
        recyclerView.setAdapter(adapter)
    }
}

class ConcertAdapter() :
        PagedListAdapter<Concert, ConcertViewHolder>(DIFF_CALLBACK) {
    fun onBindViewHolder(holder: ConcertViewHolder, position: Int) {
        val concert: Concert? = getItem(position)

        // Note that "concert" is a placeholder if it's null.
        holder.bindTo(concert)
    }

    companion object {
        private val DIFF_CALLBACK = object :
                DiffUtil.ItemCallback<Concert>() {
            // Concert details may have changed if reloaded from the database,
            // but ID is fixed.
            override fun areItemsTheSame(oldConcert: Concert,
                    newConcert: Concert) = oldConcert.id == newConcert.id

            override fun areContentsTheSame(oldConcert: Concert,
                    newConcert: Concert) = oldConcert == newConcert
        }
    }
}

Java

@Dao
public interface ConcertDao {
    // The Integer type parameter tells Room to use a PositionalDataSource
    // object, with position-based loading under the hood.
    @Query("SELECT * FROM concerts ORDER BY date DESC")
    DataSource.Factory<Integer, Concert> concertsByDate();
}

public class ConcertViewModel extends ViewModel {
    private ConcertDao concertDao;
    public final LiveData<PagedList<Concert>> concertList;

    public ConcertViewModel(ConcertDao concertDao) {
        this.concertDao = concertDao;
        concertList = new LivePagedListBuilder<>(
            concertDao.concertsByDate(), /* page size */ 50).build();
    }
}

public class ConcertActivity extends AppCompatActivity {
    @Override
    public void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        ConcertViewModel viewModel =
                new ViewModelProvider(this).get(ConcertViewModel.class);
        RecyclerView recyclerView = findViewById(R.id.concert_list);
        ConcertAdapter adapter = new ConcertAdapter();
        viewModel.concertList.observe(this, adapter::submitList);
        recyclerView.setAdapter(adapter);
    }
}

public class ConcertAdapter
        extends PagedListAdapter<Concert, ConcertViewHolder> {
    protected ConcertAdapter() {
        super(DIFF_CALLBACK);
    }

    @Override
    public void onBindViewHolder(@NonNull ConcertViewHolder holder,
            int position) {
        Concert concert = getItem(position);
        if (concert != null) {
            holder.bindTo(concert);
        } else {
            // Null defines a placeholder item - PagedListAdapter automatically
            // invalidates this row when the actual object is loaded from the
            // database.
            holder.clear();
        }
    }

    private static DiffUtil.ItemCallback<Concert> DIFF_CALLBACK =
            new DiffUtil.ItemCallback<Concert>() {
        // Concert details may have changed if reloaded from the database,
        // but ID is fixed.
        @Override
        public boolean areItemsTheSame(Concert oldConcert, Concert newConcert) {
            return oldConcert.getId() == newConcert.getId();
        }

        @Override
        public boolean areContentsTheSame(Concert oldConcert,
                Concert newConcert) {
            return oldConcert.equals(newConcert);
        }
    };
}

צפייה בנתונים בדפים באמצעות RxJava2

אם אתם מעדיפים להשתמש ב-RxJava2 במקום ב-LiveData, אתם יכולים ליצור אובייקט Observable או Flowable:

Kotlin

class ConcertViewModel(concertDao: ConcertDao) : ViewModel() {
    val concertList: Observable<PagedList<Concert>> =
            concertDao.concertsByDate().toObservable(pageSize = 50)
}

Java

public class ConcertViewModel extends ViewModel {
    private ConcertDao concertDao;
    public final Observable<PagedList<Concert>> concertList;

    public ConcertViewModel(ConcertDao concertDao) {
        this.concertDao = concertDao;

        concertList = new RxPagedListBuilder<>(
                concertDao.concertsByDate(), /* page size */ 50)
                        .buildObservable();
    }
}

אחרי זה, אפשר להתחיל ולהפסיק את המעקב אחרי הנתונים באמצעות הקוד בקטע הקוד הבא:

Kotlin

class ConcertActivity : AppCompatActivity() {
    private val adapter = ConcertAdapter()

    // Use the 'by viewModels()' Kotlin property delegate
    // from the activity-ktx artifact
    private val viewModel: ConcertViewModel by viewModels()

    private val disposable = CompositeDisposable()

    public override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        val recyclerView = findViewById(R.id.concert_list)
        recyclerView.setAdapter(adapter)
    }

    override fun onStart() {
        super.onStart()
        disposable.add(viewModel.concertList
                .subscribe(adapter::submitList)))
    }

    override fun onStop() {
        super.onStop()
        disposable.clear()
    }
}

Java

public class ConcertActivity extends AppCompatActivity {
    private ConcertAdapter adapter = new ConcertAdapter();
    private ConcertViewModel viewModel;

    private CompositeDisposable disposable = new CompositeDisposable();

    @Override
    public void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        RecyclerView recyclerView = findViewById(R.id.concert_list);

        viewModel = new ViewModelProvider(this).get(ConcertViewModel.class);
        recyclerView.setAdapter(adapter);
    }

    @Override
    protected void onStart() {
        super.onStart();
        disposable.add(viewModel.concertList
                .subscribe(adapter.submitList(flowableList)
        ));
    }

    @Override
    protected void onStop() {
        super.onStop();
        disposable.clear();
    }
}

הקוד של ConcertDao ו-ConcertAdapter זהה בפתרון שמבוסס על RxJava2 ובפתרון שמבוסס על LiveData.

שליחת משוב

נשמח לקבל ממך משוב ורעיונות באמצעות המשאבים הבאים:

Issue tracker
דווחו על בעיות כדי שנוכל לתקן באגים.

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

מידע נוסף על ספריית העימוד זמין במקורות המידע הבאים.

דוגמאות

סרטונים