نمایش فهرست‌های صفحه‌بندی‌شده

این راهنما براساس نمای کلی کتابخانه صفحه‌بندی ساخته شده است و توضیح می‌دهد که چگونه می‌توانید فهرست‌های اطلاعات را در میانای کاربر برنامه‌تان به کاربران ارائه دهید، به‌ویژه زمانی که این اطلاعات تغییر می‌کند.

رابط کاربری‌تان را به مدل نمای خود متصل کنید

می‌توانید نمونه‌ای از LiveData<PagedList> را به PagedListAdapter متصل کنید، همان‌طور که در تکه‌کد زیر نشان داده شده است:

کاتلین

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

جاوا

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 شما فقط باید به یک مورد ارائه‌شده خاص متصل شود:

کاتلین

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

جاوا

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 مدیریت می‌کند. As the user scrolls, the PagedListAdapter calls PagedList.loadAround() to provide hints to the underlying PagedList as to which items it should fetch from the DataSource.

پیاده‌سازی فراخوانی تفاوت‌ها

نمونه زیر پیاده‌سازی دستی areContentsTheSame() را نشان می‌دهد که فیلدهای شیء مربوطه را مقایسه می‌کند:

کاتلین

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
}

جاوا

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 ارث‌بری نکنید—مثلاً وقتی از کتابخانه‌ای استفاده می‌کنید که آداپتور خودش را ارائه می‌دهد—همچنان می‌توانید با کار کردن مستقیم با شیء AsyncPagedListDiffer از عملکرد تفاضل آداپتور «کتابخانه صفحه‌بندی» استفاده کنید.

ارائه جای‌بان در واسط کاربر

در مواردی که می‌خواهید واسط کاربری شما فهرستی را قبل‌از اینکه برنامه‌تان واکشی داده‌ها را تمام کند نمایش دهد، می‌توانید موارد فهرست جای‌بان را به کاربران نشان دهید. PagedList این مورد را با ارائه داده‌های مورد فهرست به‌عنوان null تا زمانی که داده‌ها بارگیری شوند، مدیریت می‌کند.

جای‌بان‌ها مزایای زیر را دارند:

  • پشتیبانی از نوارهای پیمایش: PagedList تعداد موارد فهرست را به PagedListAdapter ارائه می‌دهد. این اطلاعات به آداپتور اجازه می‌دهد نوار پیمایشی را ترسیم کند که اندازه کامل فهرست را نشان می‌دهد. با بار شدن صفحه‌های جدید، نوار پیمایش نمی‌پرد چون اندازه فهرستتان تغییر نمی‌کند.
  • نیازی به نشانگر چرخان بار کردن نیست: چون اندازه فهرست ازقبل مشخص است، نیازی نیست به کاربران هشدار داده شود که موارد بیشتری درحال بار شدن است. جای‌بان‌ها خودشان این اطلاعات را منتقل می‌کنند.

اما قبل‌از افزودن پشتیبانی برای جای‌بان‌ها، پیش‌شرط‌های زیر را درنظر داشته باشید:

  • به مجموعه داده‌های قابل‌شمارش نیاز دارد: نمونه‌های DataSource از کتابخانه پایداری Room می‌توانند به‌طور کارآمدی موارد خود را بشمارند. اما اگر از راهکار ذخیره‌سازی محلی سفارشی یا معماری داده فقط شبکه‌ای استفاده می‌کنید، تعیین تعداد مواردی که مجموعه داده‌هایتان را تشکیل می‌دهند ممکن است پرهزینه یا حتی غیرممکن باشد.
  • به آداپتور برای درنظر گرفتن موارد بارنشده نیاز دارد: آداپتور یا سازوکار ارائه‌ای که برای آماده‌سازی فهرست برای تورم استفاده می‌کنید باید موارد فهرست تهی را مدیریت کند. برای مثال، هنگام اتصال داده به ViewHolder، باید مقادیر پیش‌فرضی برای نمایش داده‌های بارنشده ارائه دهید.
  • به نماهای مورد هم‌اندازه نیاز دارد: اگر اندازه موارد فهرست براساس محتوایشان تغییر کند، مثلاً به‌روزرسانی‌های شبکه‌های اجتماعی، محو تدریجی متقاطع بین موارد ظاهر خوبی نخواهد داشت. اکیداً توصیه می‌کنیم در این مورد، جای‌بان‌ها را غیرفعال کنید.

ارائه کردن بازخورد

بازخورد و ایده‌هایتان را ازطریق این منابع با ما هم‌رسانی کنید:

ردیاب مشکل
مشکلات را گزارش کنید تا بتوانیم اشکالات را برطرف کنیم.

منابع بیشتر

برای کسب اطلاعات بیشتر درباره «کتابخانه صفحه‌بندی»، به منابع زیر مراجعه کنید.

نمونه‌ها

Codelabs

ویدیوها