ย้ายไปที่หน้า 3

Paging 3 แตกต่างจาก Paging Library เวอร์ชันก่อนหน้าอย่างมาก เวอร์ชันนี้มีฟังก์ชันการทำงานที่ได้รับการปรับปรุงและแก้ไขปัญหาทั่วไป ในการใช้ Paging 2 หากแอปใช้ไลบรารี Paging เวอร์ชันก่อนหน้าอยู่แล้ว โปรดอ่านหน้านี้เพื่อดูข้อมูลเพิ่มเติมเกี่ยวกับการย้ายข้อมูลไปยัง Paging 3

หาก Paging 3 เป็นไลบรารี Paging เวอร์ชันแรกที่คุณใช้ในแอป โปรดดูโหลดและแสดงข้อมูลที่แบ่งหน้าเพื่อดูข้อมูลการใช้งานพื้นฐาน

ประโยชน์ของการย้ายข้อมูลไปยัง Paging 3

Paging 3 มีฟีเจอร์ต่อไปนี้ที่ไม่มีในไลบรารีเวอร์ชันก่อนหน้า

  • รองรับ Kotlin Coroutines และ Flow อย่างเต็มที่
  • รองรับการโหลดแบบไม่พร้อมกันโดยใช้ RxJava Single หรือ Guava ListenableFuture primitive
  • สถานะการโหลดและสัญญาณข้อผิดพลาดในตัวสำหรับการออกแบบ UI ที่ตอบสนอง รวมถึงฟังก์ชันการลองอีกครั้งและการรีเฟรช
  • การปรับปรุงเลเยอร์ที่เก็บ รวมถึงการรองรับการยกเลิกและ อินเทอร์เฟซแหล่งข้อมูลที่เรียบง่าย
  • การปรับปรุงเลเยอร์การนำเสนอ ตัวคั่นรายการ การเปลี่ยนรูปแบบหน้าเว็บที่กำหนดเอง รวมถึงส่วนหัวและส่วนท้ายของสถานะการโหลด

ย้ายข้อมูลแอปไปยัง Paging 3

หากต้องการย้ายข้อมูลไปยัง Paging 3 อย่างสมบูรณ์ คุณต้องย้ายข้อมูลคอมโพเนนต์หลักทั้ง 3 รายการ จาก Paging 2 ดังนี้

  • DataSource ชั้นเรียน
  • PagedList
  • PagedListAdapter

อย่างไรก็ตาม คอมโพเนนต์ Paging 3 บางรายการจะเข้ากันได้แบบย้อนหลังกับ Paging เวอร์ชันก่อนหน้า โดยเฉพาะอย่างยิ่ง API PagingSource จาก Paging 3 สามารถเป็นแหล่งข้อมูลสำหรับ LivePagedListBuilder และ RxPagedListBuilder จากเวอร์ชันเก่ากว่าได้ ในทำนองเดียวกัน Pager API สามารถใช้ออบเจ็กต์ DataSource รุ่นเก่ากับเมธอด asPagingSourceFactory() ได้ ซึ่งหมายความว่าคุณมี ตัวเลือกการย้ายข้อมูลต่อไปนี้

  • คุณสามารถย้ายข้อมูล DataSource ไปยัง PagingSource ได้ แต่ไม่ต้องเปลี่ยนแปลงการติดตั้งใช้งานการแบ่งหน้าส่วนที่เหลือ
  • คุณสามารถย้ายข้อมูล PagedList และ PagedListAdapter แต่ยังคงใช้ API DataSource รุ่นเก่าได้
  • คุณย้ายข้อมูลการใช้งาน Paging ทั้งหมดเพื่อย้ายข้อมูลแอปไปยัง Paging 3 อย่างเต็มรูปแบบได้

ส่วนต่างๆ ในหน้านี้จะอธิบายวิธีย้ายข้อมูลคอมโพเนนต์การแบ่งหน้าในแต่ละเลเยอร์ ของแอป

DataSource ชั้นเรียน

ส่วนนี้อธิบายการเปลี่ยนแปลงที่จำเป็นทั้งหมดเพื่อย้ายข้อมูลการใช้งาน Paging เวอร์ชันเก่าไปใช้ PagingSource

PageKeyedDataSource, PositionalDataSource และ ItemKeyedDataSource จาก Paging 2 จะรวมกันเป็น PagingSource API ใน Paging 3 ระบบจะรวม วิธีการโหลดจากคลาส API เก่าทั้งหมดไว้ใน load() เมธอดเดียวใน PagingSource ซึ่งจะช่วยลดการทำโค้ดซ้ำเนื่องจากตรรกะส่วนใหญ่ในวิธีการโหลดในข้อมูลโค้ดของคลาส API แบบเก่ามักจะเหมือนกัน

พารามิเตอร์วิธีการโหลดทั้งหมดจะถูกแทนที่ใน Paging 3 ด้วยLoadParams คลาสที่ปิดผนึก ซึ่งรวมถึงคลาสย่อยสำหรับประเภทการโหลดแต่ละประเภท หากต้องการแยกความแตกต่างระหว่างประเภทการโหลดในเมธอด load() ให้ตรวจสอบว่ามีการส่งคลาสย่อยของ LoadParams ใดเข้ามา ได้แก่ LoadParams.Refresh, LoadParams.Prepend หรือ LoadParams.Append

ดูข้อมูลเพิ่มเติมเกี่ยวกับการติดตั้งใช้งาน PagingSource ได้ที่กําหนดแหล่งข้อมูล

รีเฟรชคีย์

การติดตั้งใช้งาน PagingSource ต้องกําหนดวิธีรีเฟรชต่อจากกลางข้อมูลหน้าเว็บที่โหลด โดยทำได้ด้วยการใช้ getRefreshKey() เพื่อแมปคีย์เริ่มต้นที่ถูกต้องโดยใช้ state.anchorPosition เป็นดัชนีที่เข้าถึงล่าสุด

Kotlin

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

Java

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

// Replacing ItemKeyedDataSource.
@Nullable
@Override
String getRefreshKey(state: PagingState<String, User>) {
  Integer anchorPosition = state.anchorPosition;
  if (anchorPosition == null) {
    return null;
  }

  return state.getClosestItemToPosition(anchorPosition);
}

// Replacing PositionalDataSource.
@Nullable
@Override
Integer getRefreshKey(state: PagingState<Integer, User>) {
  return state.anchorPosition;
}

การเปลี่ยนรูปแบบรายการ

ในไลบรารีการแบ่งหน้าเวอร์ชันที่ต่ำกว่า การเปลี่ยนรูปแบบข้อมูลที่แบ่งหน้าจะขึ้นอยู่กับวิธีการต่อไปนี้

  • DataSource.map()
  • DataSource.mapByPage()
  • DataSource.Factory.map()
  • DataSource.Factory.mapByPage()

ใน Paging 3 การเปลี่ยนรูปแบบทั้งหมดจะใช้เป็นตัวดำเนินการใน PagingData หากคุณใช้วิธีใดวิธีหนึ่งในรายการก่อนหน้าเพื่อเปลี่ยนรูปแบบรายการที่มีการแบ่งหน้า คุณต้องย้ายตรรกะการเปลี่ยนรูปแบบจาก DataSource ไปยัง PagingData เมื่อสร้าง Pager โดยใช้ PagingSource ใหม่

ดูข้อมูลเพิ่มเติมเกี่ยวกับการใช้การเปลี่ยนรูปแบบกับข้อมูลที่แบ่งหน้าโดยใช้ Paging 3 ได้ที่ เปลี่ยนรูปแบบสตรีมข้อมูล

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 ตามลำดับ

Kotlin

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)

Java

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

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

BoundaryCallback สำหรับแหล่งข้อมูลแบบเลเยอร์

ใน Paging 3 RemoteMediator จะแทนที่ PagedList.BoundaryCallback ในฐานะ ตัวแฮนเดิลสำหรับการแบ่งหน้าจากเครือข่ายและฐานข้อมูล

ดูข้อมูลเพิ่มเติมเกี่ยวกับการใช้ RemoteMediator เพื่อเปลี่ยนหน้าจากเครือข่ายและฐานข้อมูลใน Paging 3 ได้ที่ Codelab ของ Android Paging

PagedListAdapter

Paging 2 ใช้ PagedListAdapter เพื่อเชื่อมโยง PagedList กับ RecyclerView ใน Paging 3 PagingData จะแทนที่ PagedList หากคุณย้ายข้อมูลแอปเพื่อใช้ Jetpack Compose สำหรับ UI ก็ไม่จำเป็นต้องมีอแดปเตอร์เพื่อแสดงข้อมูลที่แบ่งหน้า

แต่ให้ใช้paging-composeอาร์ติแฟกต์และcollectAsLazyPagingItemsเมธอดส่วนขยาย เพื่อรวบรวมรายการ PagingData และแสดงใน@Composableฟังก์ชัน เช่น LazyColumn แทน

ดูข้อมูลเพิ่มเติมเกี่ยวกับการใช้ Paging 3 กับ Jetpack Compose ได้ที่ภาพรวมของ Paging 3

แหล่งข้อมูลเพิ่มเติม

ดูข้อมูลเพิ่มเติมเกี่ยวกับไลบรารี Paging ได้ที่แหล่งข้อมูลเพิ่มเติมต่อไปนี้

Codelabs

ตัวอย่าง