Przeciągnij w dół, aby odświeżyć

Komponent „przeciągnij, aby odświeżyć” umożliwia użytkownikom przeciągnięcie w dół na początku treści aplikacji, aby odświeżyć dane.

Powierzchnia interfejsu API

Użyj elementu kompozycyjnego PullToRefreshBox, aby zaimplementować funkcję „przeciągnij, aby odświeżyć”, która działa jako kontener treści z możliwością przewijania. Następujące kluczowe parametry kontrolują zachowanie i wygląd odświeżania:

  • isRefreshing: wartość logiczna wskazująca, czy trwa odświeżanie.
  • onRefresh: funkcja lambda, która jest wykonywana, gdy użytkownik rozpoczyna odświeżanie.
  • indicator: dostosowuje wskaźnik rysowany przez system podczas odświeżania.

Podstawowy przykład

Ten fragment kodu pokazuje podstawowe użycie elementu 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

Najważniejsze informacje o kodzie

  • PullToRefreshBox otacza element LazyColumn, który wyświetla listę ciągów znaków.
  • PullToRefreshBox wymaga parametrów isRefreshing i onRefresh.
  • Treść w bloku PullToRefreshBox reprezentuje treść z możliwością przewijania.

Wynik

Ten film pokazuje podstawową implementację funkcji „przeciągnij, aby odświeżyć” z poprzedniego kodu:

Rysunek 1. Podstawowa implementacja funkcji „przeciągnij, aby odświeżyć” na liście elementów.

Zaawansowany przykład: dostosowywanie koloru wskaźnika

@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

Najważniejsze informacje o kodzie

  • Kolor wskaźnika jest dostosowywany za pomocą właściwości containerColor i color w parametrze indicator.
  • rememberPullToRefreshState() zarządza stanem odświeżania. Używasz tego stanu w połączeniu z parametrem indicator.

Wynik

Ten film pokazuje implementację funkcji „przeciągnij, aby odświeżyć” z kolorowym wskaźnikiem:

Rysunek 2. Implementacja funkcji „przeciągnij, aby odświeżyć” ze stylem niestandardowym.

Zaawansowany przykład: tworzenie w pełni dostosowanego wskaźnika

Możesz tworzyć złożone wskaźniki niestandardowe, korzystając z istniejących elementów kompozycyjnych i animacji.Ten fragment kodu pokazuje, jak utworzyć w pełni niestandardowy wskaźnik w implementacji funkcji „przeciągnij, aby odświeżyć”:

@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

Najważniejsze informacje o kodzie

  • W poprzednim fragmencie kodu użyto elementu Indicator udostępnianego przez bibliotekę. Ten fragment kodu tworzy niestandardowy element kompozycyjny wskaźnika o nazwie MyCustomIndicator. W tym elemencie kompozycyjnym modyfikator pullToRefreshIndicator obsługuje pozycjonowanie i wyzwalanie odświeżania.
  • Podobnie jak w poprzednim fragmencie kodu, przykład wyodrębnia instancję PullToRefreshState, dzięki czemu możesz przekazać tę samą instancję zarówno do elementu PullToRefreshBox, jak i do elementu pullToRefreshModifier.
  • Przykład używa koloru kontenera i progu pozycji z klasy PullToRefreshDefaults. Dzięki temu możesz ponownie wykorzystać domyślne zachowanie i style z biblioteki Material, dostosowując tylko te elementy, które Cię interesują.
  • MyCustomIndicator używa Crossfade do przejścia między ikoną chmury a elementem CircularProgressIndicator. Ikona chmury powiększa się, gdy użytkownik przeciąga, i przechodzi do elementu CircularProgressIndicator, gdy rozpoczyna się odświeżanie.
    • targetState używa elementu isRefreshing, aby określić, który stan ma być wyświetlany (ikona chmury czy okrągły wskaźnik postępu).
    • animationSpec definiuje animację tween dla przejścia z określonym czasem trwania CROSSFADE_DURATION_MILLIS.
    • state.distanceFraction reprezentuje, jak daleko użytkownik przeciągnął w dół, w zakresie od 0f (brak przeciągnięcia) do 1f (pełne przeciągnięcie).
    • Modyfikator graphicsLayer modyfikuje skalę i przezroczystość.

Wynik

Ten film pokazuje niestandardowy wskaźnik z poprzedniego kodu:

Rysunek 3. Implementacja funkcji „przeciągnij, aby odświeżyć” z niestandardowym wskaźnikiem.

Dodatkowe materiały