مفاهیم و پیادهسازی Jetpack Compose
Paging 3 تفاوت قابلتوجهی با نسخههای قبلی کتابخانه Paging دارد. این نسخه عملکرد بهبودیافتهای ارائه میدهد و مشکلات رایج در استفاده از Paging 2 را برطرف میکند. اگر برنامهتان از نسخه قبلی کتابخانه Paging استفاده میکند، این صفحه را بخوانید تا درباره انتقال به Paging 3 بیشتر بدانید.
اگر Paging 3 اولین نسخه از کتابخانه Paging است که در برنامهتان استفاده میکنید، برای اطلاعات استفاده پایه، بار کردن و نمایش دادههای صفحهبندیشده را ببینید.
مزایای انتقال به Paging 3
Paging 3 شامل ویژگیهای زیر است که در نسخههای قبلی کتابخانه وجود نداشت:
- پشتیبانی درجه یک از روالهای مشترک Kotlin و Flow.
- پشتیبانی از بارگیری ناهمگام بااستفاده از RxJava
Singleیا GuavaListenableFutureprimitives. - سیگنالهای داخلی وضعیت بارگیری و خطا برای طراحی میانای کاربر واکنشگرا، ازجمله عملکرد بازآوری و امتحان مجدد.
- بهبودهایی در لایه مخزن، ازجمله پشتیبانی از لغو و واسط منبع داده سادهشده.
- بهبودهایی در لایه نمایش، جداکنندههای فهرست، تبدیلهای صفحه سفارشی، و سرصفحهها و پاصفحههای وضعیت بارگیری.
انتقال دادن برنامه به Paging 3
برای انتقال کامل به Paging 3، باید هر سه مؤلفه اصلی را از Paging 2 منتقل کنید:
-
DataSourceکلاس PagedListPagedListAdapter
بااینحال، برخیاز مؤلفههای Paging 3 با نسخههای قبلی Paging سازگار با نسخه قدیمی هستند. بهویژه، PagingSource API از Paging 3 میتواند
منبع دادهای برای LivePagedListBuilder و RxPagedListBuilder
از نسخههای قدیمیتر باشد. بهطور مشابه، Pager API میتواند از اشیاء قدیمیتر DataSource
با روش asPagingSourceFactory استفاده کند. این یعنی گزینههای انتقال زیر را دارید:
- میتوانید
DataSourceخود را بهPagingSourceمنتقل کنید اما بقیه پیادهسازی صفحهبندی را بدون تغییر باقی بگذارید. - میتوانید
PagedListوPagedListAdapterرا انتقال دهید اما همچنان از میانای برنامهسازی کاربردیDataSourceقدیمیتر استفاده کنید. - میتوانید کل پیادهسازی «صفحهبندی» را انتقال دهید تا برنامهتان را بهطور کامل به «صفحهبندی ۳» انتقال دهید.
بخشهای این صفحه نحوه انتقال مؤلفههای «صفحهبندی» را در هر لایه از برنامهتان توضیح میدهد.
نمای کلی انتقال
برای انتقال کامل به Paging 3 و درعینحال حفظ پیادهسازی RecyclerView،
باید مؤلفههای زیر را بهروز کنید:
Paging 2 Component |
جایگزین صفحهبندی ۳ |
|
|
|
|
|
|
|
|
DataSource کلاس
این بخش تغییرات لازم برای انتقال پیادهسازی قدیمیتر «صفحهبندی» برای استفاده از PagingSource را شرح میدهد.
PageKeyedDataSource, PositionalDataSource و ItemKeyedDataSource از
Paging 2 همگی در PagingSource API در Paging 3 ترکیب شدهاند. روشهای بار کردن از همه کلاسهای API قدیمی در یک روش load در PagingSource ترکیب شدهاند. این کار تکرار کد را کاهش میدهد زیرا بخش زیادی از منطق در روشهای بار کردن در پیادهسازیهای کلاسهای قدیمی میانای برنامهسازی کاربردی اغلب یکسان است.
همه پارامترهای روش بارگیری در Paging 3 با یک LoadParams
کلاس مهرشده جایگزین میشوند که شامل زیرکلاسهایی برای هر نوع بارگیری است. اگر لازم است بین انواع بارگیری در روش load تمایز قائل شوید، بررسی کنید کدام زیرکلاس LoadParams ارسال شده است: LoadParams.Refresh, LoadParams.Prepend یا LoadParams.Append.
برای کسب اطلاعات بیشتر درباره پیادهسازی PagingSource، به تعریف منبع داده مراجعه کنید.
بازآوری کلیدها
پیادهسازیهای PagingSource باید نحوه ازسرگیری بازآوریها را از
وسط دادههای صفحهبندیشده بارشده تعریف کنند. این کار را با پیادهسازی getRefreshKey
برای نگاشت کلید اولیه صحیح بااستفاده از state.anchorPosition بهعنوان جدیدترین
نمایه دسترسییافته انجام دهید.
Java (RxJava)
// Replaces ItemKeyedDataSource.
@Nullable
@Override
String getRefreshKey(state: PagingState<String, User>) {
Integer anchorPosition = state.anchorPosition;
if (anchorPosition == null) {
return null;
}
return state.getClosestItemToPosition(anchorPosition);
}
// Replaces PositionalDataSource.
@Nullable
@Override
Integer getRefreshKey(state: PagingState<Integer, User>) {
return state.anchorPosition;
}
Java (Guava/LiveData)
// Replaces ItemKeyedDataSource.
@Nullable
@Override
String getRefreshKey(state: PagingState<String, User>) {
Integer anchorPosition = state.anchorPosition;
if (anchorPosition == null) {
return null;
}
return state.getClosestItemToPosition(anchorPosition);
}
// Replaces PositionalDataSource.
@Nullable
@Override
Integer getRefreshKey(state: PagingState<Integer, User>) {
return state.anchorPosition;
}
PagedList
این بخش همه تغییرات لازم برای انتقال پیادهسازی قدیمیتر «صفحهبندی» برای استفاده از Pager و PagingData در «صفحهبندی ۳» را شرح میدهد.
PagedListBuilder کلاس
PagingData جایگزین PagedList موجود از Paging 2 میشود. برای انتقال به
PagingData، باید موارد زیر را بهروز کنید:
- پیکربندی صفحهبندی از
PagedList.ConfigبهPagingConfigمنتقل شده است. LivePagedListBuilderوRxPagedListBuilderدر یک کلاسPagerترکیب شدهاند.
PagerیکFlow<PagingData>قابلمشاهده را با . خود نمایش میدهد.داراییflow. انواع RxJava و LiveData نیز بهعنوان ویژگیهای افزونه دردسترس هستند، که ازطریق روشهای ایستا از Java قابلفراخوانی هستند و بهترتیب از مدولهایpaging-rxjava*وpaging-runtimeارائه میشوند.
Java (RxJava)
// CoroutineScope helper provided by the lifecycle-viewmodel-ktx artifact.
CoroutineScope viewModelScope = ViewModelKt.getViewModelScope(viewModel);
Pager<Integer, User> pager = Pager<>(
new PagingConfig(/* pageSize = */ 20),
() -> ExamplePagingSource(backend, query));
Flowable<PagingData<User>> flowable = PagingRx.getFlowable(pager);
PagingRx.cachedIn(flowable, viewModelScope);
Java (Guava/LiveData)
// CoroutineScope helper provided by the lifecycle-viewmodel-ktx artifact.
CoroutineScope viewModelScope = ViewModelKt.getViewModelScope(viewModel);
Pager<Integer, User> pager = Pager<>(
new PagingConfig(/* pageSize = */ 20),
() -> ExamplePagingSource(backend, query));
PagingLiveData.cachedIn(PagingLiveData.getLiveData(pager), viewModelScope);
برای کسب اطلاعات بیشتر درباره راهاندازی جاریسازی واکنشی از اشیاء PagingData بااستفاده از
Paging 3، به راهاندازی جاریسازی PagingData مراجعه کنید.
PagedListAdapter
این بخش همه تغییرات لازم برای انتقال پیادهسازی قدیمیتر «صفحهبندی» را برای استفاده از کلاسهای PagingDataAdapter یا AsyncPagingDataDiffer از «صفحهبندی ۳» شرح میدهد.
Paging 2 از PagedListAdapter برای متصل کردن PagedList به RecyclerView استفاده میکند. در
Paging 3، PagingData جایگزین PagedList میشود.
Paging 3 برای مدیریت جاریسازیهای واکنشی جدید PagingData، PagingDataAdapter را ارائه میدهد. درغیراینصورت، PagedListAdapter و PagingDataAdapter واسط یکسانی دارند. برای انتقال از PagedListAdapter به PagingDataAdapter،
پیادهسازی PagedListAdapter را تغییر دهید تا بهجای آن PagingDataAdapter را گسترش دهد.
برای کسب اطلاعات بیشتر درباره PagingDataAdapter، به تعریف کردن آداپتور RecyclerView مراجعه کنید.
AsyncPagedListDiffer
اگر درحالحاضر از پیادهسازی سفارشی RecyclerView.Adapter با
AsyncPagedListDiffer استفاده میکنید، پیادهسازیتان را به استفاده از
AsyncPagingDataDiffer ارائهشده در Paging 3 منتقل کنید:
کاتلین
AsyncPagingDataDiffer(diffCallback, listUpdateCallback)
Java (RxJava)
new AsyncPagingDataDiffer(diffCallback, listUpdateCallback);
Java (Guava/LiveData)
new AsyncPagingDataDiffer(diffCallback, listUpdateCallback);