読み込み状態の管理と表示

Paging ライブラリは、ページング データの読み込みリクエストの状態をトラッキングし、LoadState クラスを通じて公開します。

個々の LoadState シグナルは、LoadType とデータソース タイプ（PagingSource または RemoteMediator）ごとに提供されます。リスナーから渡される CombinedLoadStates オブジェクトは、これらすべてのシグナルから届いた読み込み状態に関する情報を提供します。この詳細な情報を使用して、適切な読み込みインジケーターをユーザーに表示できます。

読み込み状態

Paging ライブラリは、LoadState オブジェクトを介して、UI で使用される読み込み状態を公開します。LoadState オブジェクトは、現在の読み込み状態に応じて次の 3 つの形態のいずれかを取ります。

  • アクティブな読み込みオペレーションが存在せず、エラーがない場合、LoadState は LoadState.NotLoading オブジェクトになります。このサブクラスには、ページネーションが終わりに達したかどうかを示す endOfPaginationReached プロパティも含まれています。
  • アクティブな読み込みオペレーションが存在する場合、LoadState は LoadState.Loading オブジェクトになります。
  • エラーがある場合、LoadState は LoadState.Error オブジェクトになります。

これらの状態には、LazyPagingItems ラッパーの loadState プロパティを介してアクセスします。この状態は、メイン コンテンツの可視性（全画面更新スピナーなど）の処理、または LazyColumn ストリームへの読み込みアイテム（フッタースピナーなど）の直接挿入という 2 つの方法で使用できます。

リスナーを使用して読み込み状態にアクセスする

UI で読み込み状態をモニタリングするには、LazyPagingItems ラッパーによって提供される loadState プロパティを使用します。これにより、更新、追加、先頭追加のイベントの読み込み動作に対応できる 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 プロパティに直接アクセスします。

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()
    }
}

読み込み状態の変化に対応する

読み込み状態の変化に基づいて、1 回限りの副作用をトリガーする必要がある場合があります。たとえば、リストの先頭までスクロールしたり、更新が完了したときに Snackbar を表示したりする場合などです。

LaunchedEffect 内で snapshotFlow を使用して、状態の変化をストリームとして監視します。これにより、filter や distinctUntilChanged などの標準の Flow 演算子を適用して、特定のイベントを分離できます。

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

参考情報

ページング ライブラリと読み込み状態について詳しくは、以下のリソースをご覧ください。

ドキュメント

コンテンツの閲覧