مهاجرت به صفحه 3

Paging 3 تفاوت قابل توجهی با نسخه‌های قبلی کتابخانه Paging دارد. این نسخه قابلیت‌های پیشرفته، پشتیبانی درجه یک از کوروتین‌های کاتلین و Flow و ادغام یکپارچه با Jetpack Compose را ارائه می‌دهد.

مزایای مهاجرت به صفحه‌بندی ۳

صفحه‌بندی ۳ شامل ویژگی‌های زیر است که در نسخه‌های قبلی کتابخانه وجود نداشتند:

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

برنامه خود را به Paging 3 منتقل کنید

برای مهاجرت کامل به Paging 3، باید این اجزای اصلی را از Paging 2 منتقل کنید:

  • کلاس‌های DataSource
  • PagedList
  • لایه ارائه (به LazyPagingItems )

با این حال، برخی از اجزای Paging 3 با نسخه‌های قبلی Paging سازگار هستند. به طور خاص، Pager API می‌تواند از اشیاء DataSource قدیمی‌تر با متد asPagingSourceFactory استفاده کند. این بدان معناست که شما گزینه‌های مهاجرت زیر را دارید:

  • شما می‌توانید DataSource خود را به PagingSource منتقل کنید، اما بقیه‌ی پیاده‌سازی Paging خود را بدون تغییر باقی بگذارید.
  • شما می‌توانید کل پیاده‌سازی Paging را منتقل کنید تا برنامه‌تان به‌طور کامل به Paging 3 منتقل شود.

بخش‌های این صفحه نحوه‌ی انتقال کامپوننت‌های صفحه‌بندی در هر لایه از برنامه‌ی شما را توضیح می‌دهند.

کلاس‌های DataSource

این بخش تمام تغییرات لازم برای مهاجرت یک پیاده‌سازی قدیمی‌تر Paging به استفاده از PagingSource را شرح می‌دهد.

PageKeyedDataSource ، PositionalDataSource و ItemKeyedDataSource از Paging 2 همگی در PagingSource API در Paging 3 ترکیب شده‌اند. متدهای بارگذاری از تمام کلاس‌های API قدیمی در یک متد load واحد در PagingSource ترکیب شده‌اند. این امر باعث کاهش تکرار کد می‌شود زیرا بسیاری از منطق‌های موجود در متدهای بارگذاری در پیاده‌سازی‌های کلاس‌های API قدیمی اغلب یکسان است.

تمام پارامترهای متد بارگذاری در صفحه‌بندی ۳ با یک کلاس مهر و موم شده LoadParams جایگزین شده‌اند که شامل زیرکلاس‌هایی برای هر نوع بارگذاری است. اگر نیاز دارید بین انواع بارگذاری در متد load خود تمایز قائل شوید، بررسی کنید که کدام زیرکلاس LoadParams ارسال شده است: LoadParams.Refresh ، LoadParams.Prepend یا LoadParams.Append .

برای کسب اطلاعات بیشتر در مورد پیاده‌سازی PagingSource ، به بخش تعریف منبع داده مراجعه کنید.

کلیدهای تازه‌سازی

پیاده‌سازی‌های PagingSource باید نحوه‌ی از سرگیری به‌روزرسانی‌ها از اواسط داده‌های صفحه‌بندی‌شده‌ی بارگذاری‌شده را تعریف کنند. این کار را با پیاده‌سازی getRefreshKey برای نگاشت کلید اولیه‌ی صحیح با استفاده از state.anchorPosition به عنوان آخرین اندیس دسترسی‌شده انجام دهید.

// Replaces ItemKeyedDataSource.
override fun getRefreshKey(state: PagingState<String, User>): String? {
  return state.anchorPosition?.let { anchorPosition ->
    state.getClosestItemToPosition(anchorPosition)?.id
  }
}

// Replacing PositionalDataSource.
override fun getRefreshKey(state: PagingState<Int, User>): Int? {
  return state.anchorPosition
}

تبدیل‌های لیست

در نسخه‌های پایین‌تر کتابخانه Paging، تبدیل داده‌های صفحه‌بندی‌شده به روش‌های زیر متکی است:

  • DataSource.map
  • DataSource.mapByPage
  • DataSource.Factory.map
  • DataSource.Factory.mapByPage

در صفحه‌بندی ۳، تمام تبدیل‌ها به عنوان عملگرها روی PagingData اعمال می‌شوند. اگر از هر یک از روش‌های موجود در لیست قبلی برای تبدیل لیست صفحه‌بندی شده خود استفاده می‌کنید، باید هنگام ساخت Pager با استفاده از PagingSource جدید خود، منطق تبدیل خود را از DataSource به PagingData منتقل کنید.

برای کسب اطلاعات بیشتر در مورد اعمال تبدیلات به داده‌های صفحه‌بندی شده با استفاده از Paging 3، به Transform data streams مراجعه کنید.

PagedList

این بخش تمام تغییرات لازم برای مهاجرت یک پیاده‌سازی قدیمی‌تر Paging به استفاده از Pager و PagingData در Paging 3 را شرح می‌دهد.

کلاس‌های PagedListBuilder

PagingData جایگزین PagedList موجود از Paging 2 می‌شود. برای مهاجرت به PagingData ، باید موارد زیر را به‌روزرسانی کنید:

  • پیکربندی صفحه‌بندی از PagedList.Config به PagingConfig منتقل شده است.
  • کلاس‌های سازنده قدیمی‌تر در یک کلاس Pager واحد ترکیب شده‌اند.
  • Pager یک Flow<PagingData> قابل مشاهده را با ویژگی .flow خود در معرض نمایش قرار می‌دهد. 
val flow = Pager(
  // Configure how data is loaded by passing additional properties to
  // PagingConfig, such as prefetchDistance.
  PagingConfig(pageSize = 20)
) {
  ExamplePagingSource(backend, query)
}.flow
  .cachedIn(viewModelScope)

برای کسب اطلاعات بیشتر در مورد تنظیم یک جریان واکنشی از اشیاء PagingData با استفاده از Paging 3، به تنظیم یک جریان از PagingData مراجعه کنید.

BoundaryCallback برای منابع لایه‌ای

در Paging 3، RemoteMediator جایگزین PagedList.BoundaryCallback به عنوان یک هندلر برای صفحه‌بندی از شبکه و پایگاه داده می‌شود.

برای کسب اطلاعات بیشتر در مورد استفاده از RemoteMediator برای صفحه‌بندی از شبکه و پایگاه داده در Paging 3، به codelab Android Paging مراجعه کنید.

LazyPagingItems

این بخش تمام تغییرات لازم برای مهاجرت یک پیاده‌سازی قدیمی‌تر Paging به استفاده از LazyPagingItems از Paging 3 را شرح می‌دهد.

صفحه‌بندی ۳، collectAsLazyPagingItems برای مدیریت جریان جدید PagingData ارائه می‌دهد. برای انتقال لایه ارائه خود، از مصنوع paging-compose و collectAsLazyPagingItems برای جمع‌آوری آیتم‌های PagingData و نمایش آنها در توابع @Composable استفاده کنید.

برای کسب اطلاعات بیشتر در مورد LazyPagingItems ، به بخش بارگذاری و نمایش داده‌های صفحه‌بندی شده مراجعه کنید.

لیست‌های متفاوت و به‌روزرسانی‌ها

اگر در حال حاضر از منطق سفارشیِ تفاوت‌گذاریِ لیست استفاده می‌کنید، پیاده‌سازی خود را به جای آن به استفاده از LazyPagingItems ارائه شده در Paging 3 منتقل کنید. برای اطمینان از اینکه تفاوت‌گذاری به درستی انجام می‌شود، یک کلید آیتم در لیست تنبل خود مشخص کنید:

@Composable
fun UserScreen(viewModel: UserViewModel) {
    // Collects the Flow into a LazyPagingItems object
    val lazyPagingItems = viewModel.pager.flow.collectAsLazyPagingItems()

    UserList(lazyPagingItems)
}

@Composable
fun UserScreen(viewModel: UserViewModel) {
    val lazyPagingItems = viewModel.pager.flow.collectAsLazyPagingItems()

    UserList(lazyPagingItems)
}

@Composable
fun UserList(lazyPagingItems: LazyPagingItems<User>) {
    LazyColumn {
        items(
            count = lazyPagingItems.itemCount,
            // Provide a stable key for each item, similar to DiffUtil in Views
            key = lazyPagingItems.itemKey { user -> user.id } 
        ) { index ->
            val user = lazyPagingItems[index]
            if (user != null) {
                UserRow(user = user)
            }
        }
    }
}

برای اطلاعات بیشتر در مورد کلیدهای آیتم، به کلیدهای آیتم مراجعه کنید.

حالت‌های بارگیری

در صفحه‌بندی ۳، برای نمایش هدرها یا فوترها برای حالت‌های بارگذاری، به یک آداپتور جداگانه نیاز ندارید. شیء LazyPagingItems یک ویژگی loadState را در معرض نمایش قرار می‌دهد که می‌توانید مستقیماً درون LazyColumn خود آن را بررسی کنید.

LazyColumn {
    // ... items(lazyPagingItems) go here ...

    // Show loading spinner at bottom of list when appending data
    if (lazyPagingItems.loadState.append is LoadState.Loading) {
        item {
            CircularProgressIndicator(modifier = Modifier.fillMaxWidth())
        }
    }
}

منابع اضافی

برای کسب اطلاعات بیشتر در مورد کتابخانه Paging، به منابع اضافی زیر مراجعه کنید:

مستندات

محتوا را مشاهده می‌کند

{% کلمه به کلمه %} {% فعل کمکی %} {% کلمه به کلمه %} {% فعل کمکی %}