Zum Aktualisieren nach unten ziehen

Mit der Komponente „Zum Aktualisieren ziehen“ können Nutzer am Anfang des Inhalts einer App nach unten ziehen, um die Daten zu aktualisieren.

API-Oberfläche

Verwenden Sie die PullToRefreshBox zusammensetzbare Funktion, um die Funktion „Zum Aktualisieren ziehen“ zu implementieren. Sie dient als Container für scrollbare Inhalte. Die folgenden wichtigen Parameter steuern das Aktualisierungsverhalten und das Erscheinungsbild:

• isRefreshing: Ein boolescher Wert, der angibt, ob die Aktualisierung ausgeführt wird.
• onRefresh: Eine Lambda-Funktion, die ausgeführt wird, wenn der Nutzer eine Aktualisierung startet.
• indicator: Passt die Anzeige an, die das System für die Funktion „Zum Aktualisieren ziehen“ zeichnet.

Einfaches Beispiel

Dieses Snippet zeigt die grundlegende Verwendung von 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

Wichtige Informationen zum Code

• PullToRefreshBox umschließt eine LazyColumn, in der eine Liste von Strings angezeigt wird.
• PullToRefreshBox erfordert die Parameter isRefreshing und onRefresh.
• Der Inhalt im Block PullToRefreshBox stellt den scrollbaren Inhalt dar.

Ergebnis

Dieses Video zeigt die grundlegende Implementierung der Funktion „Zum Aktualisieren ziehen“ aus dem vorherigen Code:

Erweitertes Beispiel: Indikatorfarbe anpassen

@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

Wichtige Informationen zum Code

• Die Indikatorfarbe wird über die Eigenschaften containerColor und color im Parameter indicator angepasst.
• rememberPullToRefreshState() verwaltet den Status der Aktualisierung. Sie verwenden diesen Status in Verbindung mit dem Parameter indicator.

Ergebnis

Dieses Video zeigt eine Implementierung der Funktion „Zum Aktualisieren ziehen“ mit einem farbigen Indikator:

Erweitertes Beispiel: Vollständig benutzerdefinierten Indikator erstellen

Sie können komplexe benutzerdefinierte Indikatoren erstellen, indem Sie vorhandene zusammensetzbare Funktionen und Animationen nutzen.Dieses Snippet zeigt, wie Sie einen vollständig benutzerdefinierten Indikator in Ihrer Implementierung der Funktion „Zum Aktualisieren ziehen“ erstellen:

@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

Wichtige Informationen zum Code

• Im vorherigen Snippet wurde der von der Bibliothek bereitgestellte Indicator verwendet. In diesem Snippet wird eine benutzerdefinierte zusammensetzbare Indikatorfunktion namens MyCustomIndicator erstellt. In dieser zusammensetzbaren Funktion verarbeitet der Modifikator pullToRefreshIndicator die Positionierung und das Auslösen einer Aktualisierung.
• Wie im vorherigen Snippet wird im Beispiel die PullToRefreshState-Instanz extrahiert, sodass Sie dieselbe Instanz sowohl an PullToRefreshBox als auch an pullToRefreshModifier übergeben können.
• Im Beispiel werden die Containerfarbe und der Positionsschwellenwert aus der Klasse PullToRefreshDefaults verwendet. So können Sie das Standardverhalten und die Standardformatierung aus der Material-Bibliothek wiederverwenden und nur die Elemente anpassen, die Sie benötigen.
• MyCustomIndicator verwendet Crossfade, um zwischen einem Cloud-Symbol und einem CircularProgressIndicator zu wechseln. Das Cloud-Symbol wird größer, wenn der Nutzer zieht, und wechselt zu einem CircularProgressIndicator, wenn die Aktualisierung beginnt.
  • targetState verwendet isRefreshing, um zu bestimmen, welcher Status angezeigt werden soll (das Cloud-Symbol oder der kreisförmige Fortschrittsindikator).
  • animationSpec definiert eine tween-Animation für den Übergang mit einer angegebenen Dauer von CROSSFADE_DURATION_MILLIS.
  • state.distanceFraction gibt an, wie weit der Nutzer nach unten gezogen hat. Der Wert reicht von 0f (kein Ziehen) bis 1f (vollständig gezogen).
  • Der Modifikator graphicsLayer ändert die Skalierung und Transparenz.

Ergebnis

Dieses Video zeigt den benutzerdefinierten Indikator aus dem vorherigen Code:

Zusätzliche Ressourcen

• PullToRefreshState