下方向にスワイプして更新

プルダウン更新コンポーネントを使用すると、アプリのコンテンツの先頭で下にドラッグしてデータを更新できます。

API サーフェス

PullToRefreshBox コンポーザブルを使用して、スクロール可能なコンテンツのコンテナとして機能するプルダウン更新を実装します。次の主なパラメータは、更新の動作と外観を制御します。

  • isRefreshing: 更新アクションが進行中かどうかを示すブール値。
  • onRefresh: ユーザーが更新を開始したときに実行されるラムダ関数。
  • indicator: プルダウン更新時にシステムが描画するインジケーターをカスタマイズします。

基本的な例

このスニペットは、PullToRefreshBox の基本的な使用方法を示しています。

@Composable
fun PullToRefreshBasicSample(
    items: List<String>,
    isRefreshing: Boolean,
    onRefresh: () -> Unit,
    modifier: Modifier = Modifier
) {
    PullToRefreshBox(
        isRefreshing = isRefreshing,
        onRefresh = onRefresh,
        modifier = modifier
    ) {
        LazyColumn(Modifier.fillMaxSize()) {
            items(items) {
                ListItem({ Text(text = it) })
            }
        }
    }
}
PullToRefreshBox.kt

コードに関する主なポイント

  • PullToRefreshBox は、文字列のリストを表示する LazyColumn をラップします。
  • PullToRefreshBox には isRefreshing パラメータと onRefresh パラメータが必要です。
  • PullToRefreshBox ブロック内のコンテンツは、スクロール可能なコンテンツを表します。

結果

次の動画は、上記のコードによるプルダウン更新の基本的な実装を示しています。

図 1. アイテムのリストでの基本的なプル更新の実装。

高度な例: インジケーターの色をカスタマイズする

@Composable
fun PullToRefreshCustomStyleSample(
    items: List<String>,
    isRefreshing: Boolean,
    onRefresh: () -> Unit,
    modifier: Modifier = Modifier
) {
    val state = rememberPullToRefreshState()

    PullToRefreshBox(
        isRefreshing = isRefreshing,
        onRefresh = onRefresh,
        modifier = modifier,
        state = state,
        indicator = {
            Indicator(
                modifier = Modifier.align(Alignment.TopCenter),
                isRefreshing = isRefreshing,
                containerColor = MaterialTheme.colorScheme.primaryContainer,
                color = MaterialTheme.colorScheme.onPrimaryContainer,
                state = state
            )
        },
    ) {
        LazyColumn(Modifier.fillMaxSize()) {
            items(items) {
                ListItem({ Text(text = it) })
            }
        }
    }
}
PullToRefreshBox.kt

コードに関する主なポイント

  • インジケーターの色は、indicator パラメータの containerColor プロパティと color プロパティでカスタマイズされます。
  • rememberPullToRefreshState() は、更新アクションの状態を管理します。この状態は、indicator パラメータと組み合わせて使用します。

結果

この動画は、色付きのインジケーターを使用したプルダウン更新の実装を示しています。

図 2. カスタム スタイルを使用したプル更新の実装。

高度な例: 完全にカスタマイズされたインジケーターを作成する

既存のコンポーザブルとアニメーションを活用して、複雑なカスタム インジケーターを作成できます。次のスニペットは、プルして更新の実装で完全にカスタムのインジケーターを作成する方法を示しています。

@Composable
fun PullToRefreshCustomIndicatorSample(
    items: List<String>,
    isRefreshing: Boolean,
    onRefresh: () -> Unit,
    modifier: Modifier = Modifier
) {
    val state = rememberPullToRefreshState()

    PullToRefreshBox(
        isRefreshing = isRefreshing,
        onRefresh = onRefresh,
        modifier = modifier,
        state = state,
        indicator = {
            MyCustomIndicator(
                state = state,
                isRefreshing = isRefreshing,
                modifier = Modifier.align(Alignment.TopCenter)
            )
        }
    ) {
        LazyColumn(Modifier.fillMaxSize()) {
            items(items) {
                ListItem({ Text(text = it) })
            }
        }
    }
}

// ...
@Composable
fun MyCustomIndicator(
    state: PullToRefreshState,
    isRefreshing: Boolean,
    modifier: Modifier = Modifier,
) {
    Box(
        modifier = modifier.pullToRefreshIndicator(
            state = state,
            isRefreshing = isRefreshing,
            containerColor = PullToRefreshDefaults.containerColor,
            threshold = PositionalThreshold
        ),
        contentAlignment = Alignment.Center
    ) {
        Crossfade(
            targetState = isRefreshing,
            animationSpec = tween(durationMillis = CROSSFADE_DURATION_MILLIS),
            modifier = Modifier.align(Alignment.Center)
        ) { refreshing ->
            if (refreshing) {
                CircularProgressIndicator(Modifier.size(SPINNER_SIZE))
            } else {
                val distanceFraction = { state.distanceFraction.coerceIn(0f, 1f) }
                Icon(
                    imageVector = Icons.Filled.CloudDownload,
                    contentDescription = "Refresh",
                    modifier = Modifier
                        .size(18.dp)
                        .graphicsLayer {
                            val progress = distanceFraction()
                            this.alpha = progress
                            this.scaleX = progress
                            this.scaleY = progress
                        }
                )
            }
        }
    }
}
PullToRefreshBox.kt

コードに関する主なポイント

  • 前のスニペットでは、ライブラリが提供する Indicator を使用しました。このスニペットは、MyCustomIndicator というカスタム インジケーター コンポーザブルを作成します。このコンポーザブルでは、pullToRefreshIndicator 修飾子が位置決めと更新のトリガーを処理します。
  • 前のスニペットと同様に、この例では PullToRefreshState インスタンスを抽出するため、同じインスタンスを PullToRefreshBox と pullToRefreshModifier の両方に渡すことができます。
  • この例では、PullToRefreshDefaults クラスのコンテナの色と位置のしきい値を使用します。これにより、マテリアル ライブラリのデフォルトの動作とスタイルを再利用しながら、必要な要素のみをカスタマイズできます。
  • MyCustomIndicator は Crossfade を使用して、クラウド アイコンと CircularProgressIndicator の間を移行します。ユーザーがプルすると、雲のアイコンが拡大し、更新アクションが開始されると CircularProgressIndicator に切り替わります。
    • targetState は、isRefreshing を使用して、表示する状態（クラウド アイコンまたは円形の進行状況インジケーター）を決定します。
    • animationSpec は、遷移の tween アニメーションを定義します。継続時間は CROSSFADE_DURATION_MILLIS で指定します。
    • state.distanceFraction は、ユーザーがプルダウンした距離を表します。0f（プルダウンなし）から 1f（完全にプルダウン）までの範囲です。
    • graphicsLayer 修飾子は、スケールと透明度を変更します。

結果

次の動画は、上記のコードのカスタム インジケーターを示しています。

図 3. カスタム インジケーターを使用したプルダウン更新の実装。

参考情報