מעבר ל-Paging 3 (תצוגות)

מושגים ויישום ב-Jetpack פיתוח נייטיבarrow_forward

‫Paging 3 שונה באופן משמעותי מגרסאות קודמות של ספריית Paging. הגרסה הזו מספקת פונקציונליות משופרת ונותנת מענה לקשיים נפוצים בשימוש ב-Paging 2. אם האפליקציה שלכם כבר משתמשת בגרסה קודמת של ספריית Paging, כדאי לקרוא את הדף הזה כדי לקבל מידע נוסף על מעבר ל-Paging 3.

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

היתרונות של מעבר ל-Paging 3

‫Paging 3 כולל את התכונות הבאות שלא היו קיימות בגרסאות קודמות של הספרייה:

• תמיכה מלאה בשגרות המשך (coroutine) וב-Flow ב-Kotlin.
• תמיכה בטעינה אסינכרונית באמצעות פרימיטיבים של RxJava‏ Single או Guava‏ ListenableFuture.
• מצב טעינה מובנה ואותות שגיאה לעיצוב ממשק משתמש רספונסיבי, כולל פונקציונליות של ניסיון חוזר ורענון.
• שיפורים בשכבת המאגר, כולל תמיכה בביטול וממשק פשוט יותר למקורות נתונים.
• שיפורים בשכבת ההצגה, במפרידי הרשימות, בהמרות של דפים בהתאמה אישית ובכותרות העליונות והתחתונות של מצב הטעינה.

העברת האפליקציה ל-Paging 3

כדי לבצע את ההעברה המלאה ל-Paging 3, צריך להעביר את כל שלושת הרכיבים העיקריים מ-Paging 2:

• DataSource כיתות
• PagedList
• PagedListAdapter

עם זאת, חלק מהרכיבים של Paging 3 תואמים לאחור לגרסאות קודמות של Paging. בפרט, ה-API‏ PagingSource מ-Paging 3 יכול להיות מקור נתונים ל-LivePagedListBuilder ול-RxPagedListBuilder מגרסאות ישנות יותר. באופן דומה, אפשר להשתמש ב-API‏ Pager כדי לעבוד עם אובייקטים ישנים יותר של DataSource באמצעות השיטה asPagingSourceFactory. כלומר, יש לכם את האפשרויות הבאות להעברה:

• אתם יכולים להעביר את DataSource ל-PagingSource אבל להשאיר את שאר ההטמעה של הפונקציה Paging ללא שינוי.
• אפשר להעביר את PagedList וPagedListAdapter אבל עדיין להשתמש ב-API הישן יותר DataSource.
• אפשר להעביר את כל ההטמעה של Paging כדי להעביר את האפליקציה באופן מלא ל-Paging 3.

בקטעים שבדף הזה מוסבר איך להעביר רכיבי עימוד בכל שכבה של האפליקציה.

סקירה כללית על מיגרציה

כדי לבצע העברה מלאה ל-Paging 3 תוך שמירה על ההטמעה של RecyclerView, צריך לעדכן את הרכיבים הבאים:

DataSource כיתות

בקטע הזה מתוארים השינויים שצריך לבצע כדי להעביר הטמעה ישנה יותר של פונקציית ה-Paging לשימוש ב-PagingSource.

‫PageKeyedDataSource, PositionalDataSource, ו-ItemKeyedDataSource מ-Paging 2 משולבים כולם ב-API‏ PagingSource ב-Paging 3. שיטות הטעינה מכל המחלקות הישנות של ה-API משולבות בשיטה אחת של load ב-PagingSource. השינוי הזה מצמצם את הכפילות בקוד, כי הרבה מהלוגיקה בשיטות הטעינה בהטמעות של מחלקות ה-API הישנות זהה.

כל הפרמטרים של שיטת הטעינה מוחלפים ב-Paging 3 במחלקה LoadParams sealed, שכוללת מחלקות משנה לכל סוג טעינה. אם אתם צריכים להבחין בין סוגי טעינה בשיטה load, בדקו איזה מחלקת משנה של LoadParams הועברה: LoadParams.Refresh, LoadParams.Prepend או LoadParams.Append.

מידע נוסף על הגדרת מקור נתוניםPagingSource

רענון המקשים

בהטמעות של PagingSource צריך להגדיר איך הרענונים ממשיכים מהאמצע של הנתונים שנטענו בדפים. כדי לעשות זאת, מטמיעים את getRefreshKey כדי למפות את המקש ההתחלתי הנכון באמצעות state.anchorPosition בתור האינדקס האחרון שאליו ניגשו.

// 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;
}

// 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

בקטע הזה מתוארים כל השינויים שצריך לבצע כדי להעביר הטמעה ישנה של Paging לשימוש ב-Pager וב-PagingData ב-Paging 3.

‫PagedListBuilder כיתות

‫PagingData מחליף את PagedList הקיים מ-Paging 2. כדי לעבור אל PagingData, צריך לעדכן את הפרטים הבאים:

• ההגדרה של החלוקה לדפים הועברה מ-PagedList.Config ל-PagingConfig.
• הכיתות LivePagedListBuilder ו-RxPagedListBuilder שולבו לכיתה אחת Pager.

• ‫Pager חושף Flow<PagingData> שניתן לצפייה באמצעות .flow נכס. גרסאות של RxJava ו-LiveData זמינות גם כמאפייני הרחבה שאפשר להפעיל מ-Java באמצעות שיטות סטטיות, והן מסופקות מהמודולים paging-rxjava* ו-paging-runtime בהתאמה.

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

// 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

בקטע הזה מתוארים כל השינויים שצריך לבצע כדי להעביר הטמעה ישנה של Paging לשימוש במחלקות PagingDataAdapter או AsyncPagingDataDiffer מ-Paging 3.

ב-Paging 2 נעשה שימוש ב-PagedListAdapter כדי לקשר PagedList ל-RecyclerView. ב-Paging 3, ‏ PagingData מחליף את PagedList.

‫Paging 3 מספק PagingDataAdapter לטיפול בזרמי נתונים ריאקטיביים PagingData חדשים. אחרת, הממשק של PagedListAdapter ושל PagingDataAdapter זהה. כדי לעבור מ-PagedListAdapter ל-PagingDataAdapter, צריך לשנות את ההטמעה של PagedListAdapter כך שהיא תרחיב את PagingDataAdapter במקום זאת.

מידע נוסף על PagingDataAdapter זמין במאמר הגדרת מתאם RecyclerView.

AsyncPagedListDiffer

אם אתם משתמשים כרגע בהטמעה מותאמת אישית של RecyclerView.Adapter עם AsyncPagedListDiffer, אתם צריכים להעביר את ההטמעה לשימוש ב-AsyncPagingDataDiffer שמופיע ב-Paging 3:

AsyncPagingDataDiffer(diffCallback, listUpdateCallback)

new AsyncPagingDataDiffer(diffCallback, listUpdateCallback);

new AsyncPagingDataDiffer(diffCallback, listUpdateCallback);