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.

Interfejs API

Aby zaimplementować funkcję przeciągania w dół w celu odświeżenia, użyj funkcji kompozycyjnej PullToRefreshBox, która działa jako kontener na treści, które można przewijać. Te kluczowe parametry sterują zachowaniem i wyglądem odświeżania:

  • isRefreshing: wartość logiczna wskazująca, czy działanie odświeżania jest w toku.
  • onRefresh: funkcja lambda, która jest wykonywana, gdy użytkownik inicjuje odświeżanie.
  • indicator: dostosowuje wskaźnik, który system wyświetla po przeciągnięciu w dół, aby odświeżyć.

Podstawowy przykład

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

Najważniejsze informacje o kodzie

  • PullToRefreshBox zawiera element LazyColumn, który wyświetla listę ciągów tekstowych.
  • PullToRefreshBox wymaga parametrów isRefreshing i onRefresh.
  • Treść w bloku PullToRefreshBox reprezentuje treść przewijaną.

Wynik

Ten film przedstawia podstawową implementację funkcji przeciągania w dół, aby odświeżyć, z poprzedniego kodu:

Rysunek 1. Podstawowa implementacja funkcji przeciągania w dół w celu odświeżenia listy elementów.

Przykład zaawansowany: 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) })
            }
        }
    }
}

Najważniejsze informacje o kodzie

  • Kolor wskaźnika można dostosować za pomocą właściwości containerColor i color w parametrze indicator.
  • rememberPullToRefreshState() zarządza stanem działania odświeżania. Tego stanu używa się w połączeniu z parametrem indicator.

Wynik

Ten film pokazuje implementację funkcji przeciągania w dół, aby odświeżyć, z kolorowym wskaźnikiem:

Rysunek 2. Implementacja funkcji przeciągania w dół w celu odświeżenia ze stylem niestandardowym.

Przykład zaawansowany: tworzenie w pełni dostosowanego wskaźnika

Możesz tworzyć złożone wskaźniki niestandardowe, korzystając z istniejących funkcji 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
                        }
                )
            }
        }
    }
}

Najważniejsze informacje o kodzie

  • W poprzednim fragmencie kodu użyto elementu Indicator dostarczonego przez bibliotekę. Ten fragment kodu tworzy niestandardowy element kompozycyjny wskaźnika o nazwie MyCustomIndicator. W tej funkcji kompozycyjnej modyfikator pullToRefreshIndicator obsługuje pozycjonowanie i wywoływanie 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 PullToRefreshBox, jak i do pullToRefreshModifier.
  • W przykładzie użyto koloru kontenera i progu pozycji z klasy PullToRefreshDefaults. Dzięki temu możesz ponownie wykorzystać działanie domyślne i styl z biblioteki Material, dostosowując tylko te elementy, które Cię interesują.
  • MyCustomIndicator używa Crossfade do przechodzenia między ikoną chmury a CircularProgressIndicator. Ikona chmury powiększa się, gdy użytkownik przeciąga, i zmienia się w CircularProgressIndicator, gdy rozpoczyna się odświeżanie.
    • targetState używa isRefreshing, aby określić, który stan ma być wyświetlany (ikona chmury czy kołowy wskaźnik postępu).
    • animationSpec definiuje animację tween dla przejścia z określonym czasem trwania wynoszącym CROSSFADE_DURATION_MILLIS.
    • state.distanceFraction określa, jak daleko użytkownik przeciągnął palcem w dół, od 0f (brak przeciągnięcia) do 1f (pełne przeciągnięcie).
    • Modyfikator graphicsLayer zmienia skalę i przezroczystość.

Wynik

Ten film pokazuje niestandardowy wskaźnik z poprzedniego kodu:

Rysunek 3. Implementacja funkcji przeciągania w dół w celu odświeżenia z niestandardowym wskaźnikiem.

Dodatkowe materiały