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

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

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.pullToRefresh(
            state = state,
            isRefreshing = isRefreshing,
            threshold = PositionalThreshold,
            onRefresh = {

            }
        ),
        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 クラスのコンテナの色と位置のしきい値を使用しています。これにより、Material ライブラリのデフォルトの動作とスタイルを再利用しながら、関心のある要素のみをカスタマイズできます。
  • MyCustomIndicator は Crossfade を使用して、雲のアイコン と CircularProgressIndicator の間を遷移します。ユーザーがプルすると雲のアイコンが拡大し、更新アクションが開始されると CircularProgressIndicator に遷移します。
    • targetState は isRefreshing を使用して、表示する状態（雲のアイコンまたは円形の進行状況インジケーター）を決定します。
    • animationSpec は、遷移の tween アニメーションを定義します。継続時間は CROSSFADE_DURATION_MILLIS です。
    • state.distanceFraction は、ユーザーがプルダウンした距離を表します。範囲は 0f（プルなし）から 1f（完全にプル）までです。
    • graphicsLayer 修飾子は、スケールと透明度を変更します。

結果

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

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

参考情報