ไลบรารีเพจจิ้งจะติดตามสถานะของคำขอโหลดสำหรับข้อมูลที่มีการแบ่งหน้าและแสดงสถานะดังกล่าวผ่านคลาส 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 และสถานะการโหลดได้ที่แหล่งข้อมูลต่อไปนี้
เอกสารประกอบ
ดูเนื้อหา
แนะนำสำหรับคุณ
- หมายเหตุ: ข้อความลิงก์จะแสดงเมื่อ JavaScript ปิดอยู่
- ภาพรวมของไลบรารี Paging