โหลดและแสดงข้อมูลการแบ่งหน้า

ไลบรารี Paging มีความสามารถที่มีประสิทธิภาพในการโหลดและแสดงข้อมูลที่มีการแบ่งหน้าจากชุดข้อมูลขนาดใหญ่ คู่มือนี้แสดงวิธีใช้ไลบรารีการแบ่งหน้าเพื่อตั้งค่าสตรีมข้อมูลที่มีการแบ่งหน้าจากแหล่งข้อมูลเครือข่ายและแสดงในรายการแบบ Lazy

กำหนดแหล่งข้อมูล

ขั้นตอนแรกคือการกำหนดการติดตั้งใช้งาน PagingSource เพื่อระบุแหล่งข้อมูล คลาส API PagingSource มีเมธอด load ซึ่งคุณลบล้างเพื่อระบุวิธีดึงข้อมูลที่มีการแบ่งหน้าจากแหล่งข้อมูลที่เกี่ยวข้องได้

ใช้คลาส PagingSource โดยตรงเพื่อใช้ Kotlin Coroutine สำหรับการโหลดแบบไม่พร้อมกัน

เลือกประเภทคีย์และค่า

PagingSource<Key, Value> มีพารามิเตอร์ประเภท 2 รายการ ได้แก่ Key และ Value คีย์จะกำหนดตัวระบุที่ใช้ในการโหลดข้อมูล และค่าคือประเภทของข้อมูลเอง เช่น หากคุณโหลดหน้าของออบเจ็กต์ User จากเครือข่ายโดยส่งหมายเลขหน้า Int ไปยัง Retrofit ให้เลือก Int เป็นประเภท Key และ User เป็นประเภท Value

กำหนด PagingSource

ตัวอย่างต่อไปนี้ใช้ PagingSource ที่โหลดหน้าของรายการตามหมายเลขหน้า ประเภท Key คือ Int และประเภท Value คือ User

class ExamplePagingSource(
    val backend: ExampleBackendService,
    val query: String
) : PagingSource<Int, User>() {
  override suspend fun load(
    params: LoadParams<Int>
  ): LoadResult<Int, User> {

    init {
        // the data source is expected to be immutable
        // invalidate PagingSource if data source
        // has updated
        backEnd.addDatabaseOnChangedListener {
            invalidate()
        }
    }

    try {
      // Start refresh at page 1 if undefined.
      val nextPageNumber = params.key ?: 1
      val response = backend.searchUsers(query, nextPageNumber)
      return LoadResult.Page(
        data = response.users,
        prevKey = null, // Only paging forward.
        nextKey = nextPageNumber + 1
      )
    } catch (e: Exception) {
      // Handle errors in this block and return LoadResult.Error for
      // expected errors (such as a network failure).
    }
  }

  override fun getRefreshKey(state: PagingState<Int, User>): Int? {
    // Try to find the page key of the closest page to anchorPosition from
    // either the prevKey or the nextKey; you need to handle nullability
    // here.
    //  * prevKey == null -> anchorPage is the first page.
    //  * nextKey == null -> anchorPage is the last page.
    //  * both prevKey and nextKey are null -> anchorPage is the
    //    initial page, so return null.
    return state.anchorPosition?.let { anchorPosition ->
      val anchorPage = state.closestPageToPosition(anchorPosition)
      anchorPage?.prevKey?.plus(1) ?: anchorPage?.nextKey?.minus(1)
    }
  }
}

การติดตั้งใช้งาน PagingSource ทั่วไปจะส่งพารามิเตอร์ที่ระบุไว้ในคอนสตรัคเตอร์ไปยังเมธอด load เพื่อโหลดข้อมูลที่เหมาะสมสำหรับการค้นหา ในตัวอย่างข้างต้น พารามิเตอร์เหล่านั้นคือ

  • backend: อินสแตนซ์ของบริการแบ็กเอนด์ที่ให้ข้อมูล
  • query: คำค้นหาที่จะส่งไปยังบริการที่ระบุโดย backend

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

ออบเจ็กต์ LoadResult มีผลลัพธ์ของการดำเนินการโหลด LoadResult เป็นคลาสที่ปิดผนึกซึ่งใช้รูปแบบใดรูปแบบหนึ่งจาก 3 รูปแบบ โดยขึ้นอยู่กับว่าการเรียก load สำเร็จหรือไม่ ดังนี้

  • หากโหลดสำเร็จ ให้แสดงผลออบเจ็กต์ LoadResult.Page ส่ง null สำหรับ nextKey หรือ prevKey หากโหลดข้อมูลในทิศทางนั้นไม่ได้อีก
  • หากโหลดไม่สำเร็จ ให้แสดงผลออบเจ็กต์ LoadResult.Error
  • หาก PagingSource ใช้ไม่ได้อีกต่อไปเนื่องจากข้อมูลเบื้องหลังมีการเปลี่ยนแปลง ให้แสดงผลออบเจ็กต์ LoadResult.Invalid

ภาพต่อไปนี้แสดงให้เห็นว่าฟังก์ชัน load ในตัวอย่างนี้รับคีย์สำหรับการโหลดแต่ละครั้งและให้คีย์สำหรับการโหลดครั้งถัดไปอย่างไร

ในการเรียกใช้การโหลดแต่ละครั้ง ExamplePagingSource จะใช้คีย์ปัจจุบันและแสดงผลคีย์ถัดไปที่จะโหลด
รูปที่ 1 แผนภาพแสดงวิธีที่ load ใช้และอัปเดตคีย์

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

// Only for positional or offset PagingSources where Key is a 0-based item index
// rather than a page number.
override fun getRefreshKey(state: PagingState<Int, User>): Int? {
  // Center the refreshed load around the user's current viewport so the list
  // does not jump back to the top on invalidation.
  return state.anchorPosition?.let { anchorPosition ->
    (anchorPosition - state.config.initialLoadSize / 2).coerceAtLeast(0)
  }
}

จัดการข้อผิดพลาด

คำขอโหลดข้อมูลอาจล้มเหลวได้จากหลายสาเหตุ โดยเฉพาะเมื่อโหลดผ่านเครือข่าย รายงานข้อผิดพลาดที่พบระหว่างการโหลดโดยแสดงผลออบเจ็กต์ LoadResult.Error จากเมธอด load

ตัวอย่างเช่น คุณสามารถตรวจจับและรายงานข้อผิดพลาดในการโหลดใน ExamplePagingSource จากตัวอย่างก่อนหน้าได้โดยเพิ่มโค้ดต่อไปนี้ลงในเมธอด load

catch (e: IOException) {
  // IOException for network failures.
  return LoadResult.Error(e)
} catch (e: HttpException) {
  // HttpException for any non-2xx HTTP status codes.
  return LoadResult.Error(e)
}

ดูข้อมูลเพิ่มเติมเกี่ยวกับการจัดการข้อผิดพลาดของ Retrofit ได้ที่ตัวอย่างในเอกสารอ้างอิง API ของ PagingSource

PagingSource จะรวบรวมและส่งออบเจ็กต์ LoadResult.Error ไปยัง UI เพื่อให้คุณดำเนินการกับออบเจ็กต์เหล่านั้นได้ ดูข้อมูลเพิ่มเติมเกี่ยวกับการแสดงสถานะการโหลดใน UI ได้ที่จัดการและแสดงสถานะการโหลด

ตั้งค่าสตรีมของ PagingData

ถัดไป คุณต้องมีสตรีมข้อมูลที่มีการแบ่งหน้าจากการติดตั้งใช้งาน PagingSource ตั้งค่าสตรีมข้อมูลใน ViewModel คลาส Pager มีเมธอดที่แสดงสตรีมแบบรีแอ็กทีฟของออบเจ็กต์ PagingData จาก PagingSource ไลบรารีเพจจิ้งจะแสดงสตรีมข้อมูลเป็น Flow

เมื่อสร้างอินสแตนซ์ Pager เพื่อตั้งค่าสตรีมแบบรีแอ็กทีฟ คุณต้องระบุออบเจ็กต์การกำหนดค่า PagingConfig และฟังก์ชันที่บอก Pager ถึงวิธีรับอินสแตนซ์ของการติดตั้งใช้งาน PagingSource นอกจากนี้ คุณยังระบุ initialKey ที่ไม่บังคับได้ด้วย เช่น 1 สำหรับหมายเลขหน้าที่อิงตาม 1 หรือ 0 สำหรับการแบ่งหน้าตามออฟเซ็ต ใน PagingConfig คุณสามารถกำหนดค่า pageSize, initialLoadSize, prefetchDistance และ enablePlaceholders ได้ พร็อพเพอร์ตี้ prefetchDistance จะกำหนดจำนวนรายการจากขอบด้านใดด้านหนึ่งของเนื้อหาที่โหลดซึ่งจะทริกเกอร์การดึงข้อมูลครั้งถัดไป

class UserViewModel(
    private val backend: ExampleBackendService,
    private val query: String
) : ViewModel() {

    val userPagingFlow: Flow<PagingData<User>> = Pager(
        config = PagingConfig(
            pageSize = 20,
            // Load 3 pages initially so the user can scroll immediately without
            // hitting a loading state.
            initialLoadSize = 60,
            // Fetch the next page far enough ahead of the scroll position to
            // avoid visible pauses.
            prefetchDistance = 20,
            enablePlaceholders = true
        ),
        initialKey = 1,
        pagingSourceFactory = {
            ExamplePagingSource(backend, query)
        }
    )
    .flow
    .cachedIn(viewModelScope)
}

โอเปอเรเตอร์ cachedIn ทำให้สตรีมข้อมูลแชร์ได้และแคชข้อมูลที่โหลดด้วย CoroutineScope ที่ระบุ หากไม่มี cachedIn ระบบจะไม่สามารถเรียกคืน PagingData ได้ ตัวอย่างนี้ใช้ viewModelScope ที่ได้จากอาร์ติแฟกต์ lifecycle-viewmodel-ktx ของวงจร

ออบเจ็กต์ Pager จะเรียกใช้เมธอด load จากออบเจ็กต์ PagingSource โดยส่งออบเจ็กต์ LoadParams ไปให้และรับออบเจ็กต์ LoadResult กลับมา

รวบรวมและแสดงข้อมูลใน UI

หากต้องการเชื่อมต่อสตรีมที่มีการแบ่งหน้ากับ UI ให้รับโฟลว์จาก ViewModel แล้วส่งไปยัง Composable ของรายการ

@Composable
fun UserScreen(viewModel: UserViewModel = viewModel()) {
    val userFlow = viewModel.userPagingFlow
    UserList(flow = userFlow)
}

ใช้ collectAsLazyPagingItems เพื่อแปลงโฟลว์ PagingData เป็น LazyPagingItems จากนั้นใช้ items API ภายใน LazyColumn เพื่อจัดวางแต่ละรายการ

ตรวจสอบว่าได้ระบุตัวระบุที่ไม่ซ้ำกันและคงที่สำหรับสินค้าแต่ละรายการโดยใช้ itemKey ตัวอย่างต่อไปนี้ใช้ it.id (อ้างอิงพร็อพเพอร์ตี้ User.id) เนื่องจากค่านี้จะคงที่สำหรับอินสแตนซ์ User ในการอัปเดตข้อมูล

@Composable
fun UserList(flow: Flow<PagingData<User>>) {
    val lazyPagingItems = flow.collectAsLazyPagingItems()
    LazyColumn {
        items(
            lazyPagingItems.itemCount,
            key = lazyPagingItems.itemKey { it.id }
        ) { index ->
            val user = lazyPagingItems[index]
            if (user != null) {
                UserRow(user)
            } else {
                UserPlaceholder()
            }
        }
    }
}

ไลบรารีการแบ่งหน้าใช้ null สำหรับตัวยึดตำแหน่งขณะที่หน้ากำลังโหลด ดังนั้นหากคุณเปิดใช้ตัวยึดตำแหน่ง คุณต้องจัดการค่า null ในบล็อกเนื้อหา

ตอนนี้รายการจะแสดงข้อมูลที่มีการแบ่งหน้า และไลบรารีเพจจิ้งจะโหลดหน้าเพิ่มเติมเมื่อผู้ใช้เลื่อนดู

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

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

เอกสารประกอบ

ดูเนื้อหา