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

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

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

می‌توانید نمونه‌ای از 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 مدیریت می‌کند. وقتی کاربر پیمایش می‌کند، PagedListAdapter PagedList.loadAround() را فرامی‌خواند تا نکاتی را به PagedList اصلی ارائه دهد که کدام موارد را باید از 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 شما راه‌اندازی می‌کند.

Diffing using a different adapter type

اگر انتخاب کنید که از PagedListAdapter ارث‌بری نکنید—مثلاً وقتی‌که از کتابخانه‌ای استفاده می‌کنید که آداپتور خودش را ارائه می‌دهد—همچنان می‌توانید با کار کردن مستقیم با شیء AsyncPagedListDiffer از عملکرد تفاضل‌گیری آداپتور «کتابخانه صفحه‌بندی» استفاده کنید.

ارائه جای‌بان در میانای کاربر

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

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

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

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

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

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

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

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

منابع بیشتر

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

نمونه‌ها

Codelabs

ویدیوها