จัดการและนำเสนอสถานะการโหลด

ไลบรารีเพจจิ้งจะติดตามสถานะของคำขอโหลดสำหรับข้อมูลที่มีการแบ่งหน้าและแสดงสถานะดังกล่าวผ่านคลาส LoadState

ระบบจะส่งสัญญาณ LoadState แยกต่างหากสำหรับ LoadType และประเภทแหล่งข้อมูลแต่ละประเภท (PagingSource หรือ RemoteMediator) ออบเจ็กต์ CombinedLoadStates ที่ Listener มีให้จะให้ข้อมูลเกี่ยวกับสถานะการโหลดจากสัญญาณทั้งหมดเหล่านี้ คุณสามารถใช้ข้อมูลโดยละเอียดนี้เพื่อแสดงสัญญาณบอกสถานะการโหลดที่เหมาะสมแก่ผู้ใช้

กำลังโหลดรัฐ

ไลบรารี Paging จะแสดงสถานะการโหลดเพื่อใช้ใน UI ผ่านออบเจ็กต์ LoadState ออบเจ็กต์ LoadState จะอยู่ในรูปแบบใดรูปแบบหนึ่งจาก 3 รูปแบบ โดยขึ้นอยู่กับสถานะการโหลดปัจจุบัน ดังนี้

  • หากไม่มีการดำเนินการโหลดที่ทำงานอยู่และไม่มีข้อผิดพลาด LoadState จะเป็นออบเจ็กต์ LoadState.NotLoading คลาสย่อยนี้ยังมีพร็อพเพอร์ตี้ endOfPaginationReached ซึ่งระบุว่าถึงจุดสิ้นสุดของการแบ่งหน้าแล้วหรือไม่
  • หากมีการดำเนินการโหลดที่ทำงานอยู่ LoadState จะเป็นออบเจ็กต์ LoadState.Loading
  • หากมีข้อผิดพลาด LoadState จะเป็นออบเจ็กต์ LoadState.Error

เข้าถึงสถานะเหล่านี้ผ่านพร็อพเพอร์ตี้ loadState ของ Wrapper LazyPagingItems คุณใช้สถานะนี้ได้ 2 วิธี ได้แก่ การจัดการระดับการมองเห็นเนื้อหาหลัก (เช่น ตัวหมุนรีเฟรชแบบเต็มหน้าจอ) หรือการแทรกรายการที่กำลังโหลดลงในสตรีม LazyColumn โดยตรง (เช่น ตัวหมุนส่วนท้าย)

เข้าถึงสถานะการโหลดด้วย Listener

หากต้องการตรวจสอบสถานะการโหลดใน UI ให้ใช้พร็อพเพอร์ตี้ loadState ที่ Wrapper LazyPagingItems มีให้ ซึ่งจะแสดงผลออบเจ็กต์ CombinedLoadStates ที่ช่วยให้คุณตอบสนองต่อลักษณะการโหลดสำหรับเหตุการณ์รีเฟรช ต่อท้าย หรือต่อหน้าได้

ในตัวอย่างต่อไปนี้ UI จะแสดงภาพหมุนเพื่อแสดงการโหลดหรือข้อความแสดงข้อผิดพลาด โดยขึ้นอยู่กับสถานะปัจจุบันของการโหลดเพื่อรีเฟรช (ครั้งแรก)

@Composable
fun UserListScreen(viewModel: UserViewModel) {
  val pagingItems = viewModel.flow.collectAsLazyPagingItems()

  Box(modifier = Modifier.fillMaxSize()) {
    // Show the list content
    LazyColumn {
      items(pagingItems.itemCount) { index ->
        UserItem(pagingItems[index])
      }
    }

    // Handle the loading state
    when (val state = pagingItems.loadState.refresh) {
      is LoadState.Loading -> {
        CircularProgressIndicator(modifier = Modifier.align(Alignment.Center))
      }
      is LoadState.Error -> {
        ErrorButton(
          message = state.error.message ?: "Unknown error",
          onClick = { pagingItems.retry() },
          modifier = Modifier.align(Alignment.Center)
        )
      }
      else -> {} // No separate view needed for success/not loading
    }
  }
}

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

หากต้องการแสดงสัญญาณบอกสถานะการโหลดที่จุดเริ่มต้นหรือจุดสิ้นสุดของรายการ (ทำหน้าที่เป็นส่วนหัวหรือส่วนท้าย) ให้เพิ่มบล็อกรายการเฉพาะสำหรับสถานะเหล่านั้นภายในขอบเขต LazyColumn ของคุณ

คุณสามารถตรวจสอบสถานะการเพิ่มไว้ข้างหน้าสำหรับส่วนหัวและสถานะการเพิ่มต่อท้ายสำหรับส่วนท้ายได้โดยใช้ออบเจ็กต์ CombinedLoadStates

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

@Composable
fun UserList(viewModel: UserViewModel) {
  val pagingItems = viewModel.pager.flow.collectAsLazyPagingItems()

  LazyColumn {
    // 1. Header (Prepend state)
    // Useful if you support bidirectional paging or jumping to the middle
    item {
      val prependState = pagingItems.loadState.prepend
      if (prependState is LoadState.Loading) {
        LoadingItem()
      } else if (prependState is LoadState.Error) {
        ErrorItem(
          message = prependState.error.message ?: "Error",
          onClick = { pagingItems.retry() }
        )
      }
    }

    // 2. Main Data
    items(pagingItems.itemCount) { index ->
      UserItem(pagingItems[index])
    }

    // 3. Footer (Append state)
    // Shows when the user scrolls to the bottom and more data is loading
    item {
      val appendState = pagingItems.loadState.append
      if (appendState is LoadState.Loading) {
        LoadingItem()
      } else if (appendState is LoadState.Error) {
        ErrorItem(
          message = appendState.error.message ?: "Error",
          onClick = { pagingItems.retry() }
        )
      }
    }
  }
}

@Composable
fun LoadingItem() {
  Box(modifier = Modifier.fillMaxWidth().padding(16.dp), contentAlignment = Alignment.Center) {
    CircularProgressIndicator()
  }
}

@Composable
fun ErrorItem(message: String, onClick: () -> Unit) {
  Column(
    modifier = Modifier.fillMaxWidth().padding(16.dp),
    horizontalAlignment = Alignment.CenterHorizontally
  ) {
    Text(text = message, color = Color.Red)
    Button(onClick = onClick) { Text("Retry") }
  }
}

เข้าถึงข้อมูลสถานะการโหลดเพิ่มเติม

ดังที่แสดงในตัวอย่างก่อนหน้านี้ การเรียกใช้ pagingItems.loadState.refresh นั้นสะดวกมาก อย่างไรก็ตาม วิธีนี้จะบดบังความแตกต่างระหว่างการโหลดจากฐานข้อมูลในเครื่อง (PagingSource) และเครือข่าย (RemoteMediator) ซึ่งอาจทำให้ UI แสดงภาพหมุนเพื่อโหลดสั้นๆ แม้ว่าข้อมูลที่แคชไว้จะพร้อมใช้งานทันทีก็ตาม

หากต้องการควบคุมอย่างแม่นยำ เช่น แสดงภาพหมุนขณะโหลดเฉพาะเมื่อฐานข้อมูลในเครื่องว่างเปล่าและมีการซิงค์เครือข่ายอยู่ ให้เข้าถึงพร็อพเพอร์ตี้ source และ mediator โดยตรงภายใน Composable

val loadState = pagingItems.loadState

val isSyncing = loadState.mediator?.refresh is LoadState.Loading

val isLocalEmpty = loadState.source.refresh is LoadState.NotLoading &&
                   pagingItems.itemSnapshotList.items.isEmpty()

if (isSyncing && isLocalEmpty) {
    FullScreenLoading()
} else {
    UserList(pagingItems)

    if (isSyncing) {
        TopOverlaySpinner()
    }
}

เนื่องจาก pagingItems.loadState จะส่งออบเจ็กต์ CombinedLoadStates ใหม่เมื่อใดก็ตามที่ prepend หรือ append มีการเปลี่ยนแปลงระหว่างการเลื่อน ให้รวมการตรวจสอบการรีเฟรชใน derivedStateOf ด้วย remember(pagingItems) วิธีนี้ช่วยป้องกันไม่ให้การอัปเดตขอบการเลื่อนจัดองค์ประกอบขอบเขตหลักใหม่ซึ่งจะสลับเฉพาะตัวบ่งชี้การรีเฟรชแบบเต็มหน้าจอเท่านั้น

val showFullScreenLoading by remember(pagingItems) {
  derivedStateOf {
    // Avoid recomposing on prepend or append updates while scrolling, and
    // avoid covering existing items during a background refresh.
    pagingItems.loadState.source.refresh is LoadState.Loading &&
      pagingItems.itemCount == 0
  }
}

if (showFullScreenLoading) {
  Box(
    modifier = Modifier.fillMaxSize(),
    contentAlignment = Alignment.Center
  ) {
    CircularProgressIndicator()
  }
}

ตอบสนองต่อการเปลี่ยนแปลงสถานะการโหลด

คุณอาจต้องทริกเกอร์ผลข้างเคียงแบบครั้งเดียวตามการเปลี่ยนแปลงสถานะการโหลด เช่น การเลื่อนไปที่ด้านบนของรายการหรือแสดง Snackbar เมื่อการรีเฟรชเสร็จสมบูรณ์หรือล้มเหลว

ใช้ snapshotFlow ภายใน LaunchedEffect เพื่อสังเกตการเปลี่ยนแปลงสถานะเป็นสตรีม ซึ่งจะช่วยให้คุณใช้โอเปอเรเตอร์ Flow มาตรฐาน เช่น filter, distinctUntilChanged และ distinctUntilChangedBy เพื่อแยกเหตุการณ์ที่เฉพาะเจาะจงได้

val listState = rememberLazyListState()

LaunchedEffect(pagingItems) {
  // 1. Convert the state to a Flow
  snapshotFlow { pagingItems.loadState.refresh }
    // 2. Filter for the specific event (Refresh completed successfully)
    .distinctUntilChanged()
    .filter { it is LoadState.NotLoading }
    .collect {
      // 3. Trigger the side effect
      listState.animateScrollToItem(0)
    }
}

ในทำนองเดียวกัน คุณสามารถใช้ distinctUntilChangedBy ใน loadState เพื่อแสดงข้อผิดพลาด Snackbar เฉพาะเมื่อสถานะ refresh เปลี่ยนเป็น LoadState.Error ได้ดังนี้

val snackbarHostState = remember { SnackbarHostState() }

// Key on pagingItems rather than loadState so state updates do not restart the
// coroutine and reset distinctUntilChangedBy.
LaunchedEffect(pagingItems) {
  snapshotFlow { pagingItems.loadState }
    // Ignore prepend and append updates so scrolling does not re-trigger the
    // refresh error Snackbar.
    .distinctUntilChangedBy { it.refresh }
    .filter { it.refresh is LoadState.Error }
    .collect { loadState ->
      val error = (loadState.refresh as LoadState.Error).error
      val result = snackbarHostState.showSnackbar(
        message = "Data failed to load: ${error.localizedMessage ?: "Unknown error"}",
        actionLabel = "Retry"
      )
      if (result == SnackbarResult.ActionPerformed) {
        pagingItems.retry()
      }
    }
}

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

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

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

ดูเนื้อหา