הצגת רשימות עמודים

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

חיבור ממשק המשתמש למודל התצוגה

אפשר לחבר מופע של LiveData<PagedList> ל-PagedListAdapter, כמו בקטע הקוד הבא:

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()

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState);
        viewModel.concerts.observe(this, Observer { adapter.submitList(it) })
    }
}

Java

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

    @Override
    public void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        viewModel = new ViewModelProvider(this).get(ConcertViewModel.class);
        viewModel.concertList.observe(this, adapter::submitList);
    }
}

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

Kotlin

class ConcertAdapter() :
        PagedListAdapter<Concert, ConcertViewHolder>(DIFF_CALLBACK) {
    override 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 = ... // See Implement the diffing callback section.
    }
}

Java

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);

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

    private static DiffUtil.ItemCallback<Concert> DIFF_CALLBACK
            = ... // See Implement the diffing callback section.
}

ה-PagedListAdapter מטפל באירועים של טעינת דף באמצעות אובייקט PagedList.Callback. כשהמשתמש גולל, ה-PagedListAdapter קורא ל-PagedList.loadAround() כדי לספק רמזים ל-PagedList הבסיסי לגבי הפריטים שהוא צריך לאחזר מה-DataSource.

הטמעת הקריאה החוזרת (callback) להשוואה

בדוגמה הבאה מוצגת הטמעה ידנית של areContentsTheSame(), שמשווה בין שדות אובייקטים רלוונטיים:

Kotlin

private val DIFF_CALLBACK = object : DiffUtil.ItemCallback<Concert>() {
    // The ID property identifies when items are the same.
    override fun areItemsTheSame(oldItem: Concert, newItem: Concert) =
            oldItem.id == newItem.id

    // If you use the "==" operator, make sure that the object implements
    // .equals(). Alternatively, write custom data comparison logic here.
    override fun areContentsTheSame(
            oldItem: Concert, newItem: Concert) = oldItem == newItem
}

Java

private static DiffUtil.ItemCallback<Concert> DIFF_CALLBACK =
        new DiffUtil.ItemCallback<Concert>() {

    @Override
    public boolean areItemsTheSame(Concert oldItem, Concert newItem) {
        // The ID property identifies when items are the same.
        return oldItem.getId() == newItem.getId();
    }

    @Override
    public boolean areContentsTheSame(Concert oldItem, Concert newItem) {
        // Don't use the "==" operator here. Either implement and use .equals(),
        // or write custom data comparison logic here.
        return oldItem.equals(newItem);
    }
};

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

השוואה באמצעות סוג מתאם אחר

אם אתם בוחרים לא לרשת מ-PagedListAdapter – למשל כשאתם משתמשים בספרייה שמספקת מתאם משלה – אתם עדיין יכולים להשתמש בפונקציונליות ההשוואה של מתאם ספריית Paging, על ידי עבודה ישירות עם אובייקט AsyncPagedListDiffer.

הוספת פלייסהולדרים בממשק המשתמש

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

היתרונות של פלייסהולדרים:

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

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

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

שליחת משוב

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

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

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

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

דוגמאות

Codelabs

סרטונים