Trascina per aggiornare

Il componente di aggiornamento tramite trascinamento verso il basso consente agli utenti di trascinare verso il basso all'inizio dei contenuti di un'app per aggiornare i dati.

Piattaforma API

Utilizza il composable PullToRefreshBox per implementare l'aggiornamento tramite trascinamento verso il basso, che funge da contenitore per i contenuti scorrevoli. I seguenti parametri chiave controllano il comportamento e l'aspetto dell'aggiornamento:

• isRefreshing: un valore booleano che indica se l'azione di aggiornamento è in corso.
• onRefresh: una funzione lambda che viene eseguita quando l'utente avvia un aggiornamento.
• indicator: personalizza l'indicatore disegnato dal sistema sull'aggiornamento tramite trascinamento verso il basso.

Esempio di base

Questo snippet mostra l'utilizzo di base di 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

Punti chiave sul codice

• PullToRefreshBox racchiude un LazyColumn, che mostra un elenco di stringhe.
• PullToRefreshBox richiede i parametri isRefreshing e onRefresh.
• I contenuti all'interno del blocco PullToRefreshBox rappresentano i contenuti scorrevoli.

Risultato

Questo video mostra l'implementazione di base dell'aggiornamento tramite trascinamento verso il basso dal codice precedente:

Esempio avanzato: personalizzare il colore dell'indicatore

@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

Punti chiave sul codice

• Il colore dell'indicatore viene personalizzato tramite le proprietà containerColor e color nel parametro indicator.
• rememberPullToRefreshState() gestisce lo stato dell'azione di aggiornamento. Utilizza questo stato insieme al parametro indicator.

Risultato

Questo video mostra un'implementazione dell'aggiornamento tramite trascinamento verso il basso con un indicatore colorato:

Esempio avanzato: creare un indicatore completamente personalizzato

Puoi creare indicatori personalizzati complessi sfruttando i composable e le animazioni esistenti.Questo snippet mostra come creare un indicatore completamente personalizzato nell'implementazione dell'aggiornamento tramite trascinamento verso il basso:

@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

Punti chiave sul codice

• Lo snippet precedente utilizzava l'Indicator fornito dalla libreria. Questo snippet crea un composable indicatore personalizzato denominato MyCustomIndicator. In questo composable, il modificatore pullToRefreshIndicator gestisce il posizionamento e l'attivazione di un aggiornamento.
• Come nello snippet precedente, l'esempio estrae l'istanza PullToRefreshState, in modo da poter passare la stessa istanza sia a PullToRefreshBox sia a pullToRefreshModifier.
• L'esempio utilizza il colore del contenitore e la soglia di posizione della classe PullToRefreshDefaults. In questo modo, puoi riutilizzare il comportamento e lo stile predefiniti della libreria Material, personalizzando solo gli elementi di tuo interesse.
• MyCustomIndicator utilizza Crossfade per la transizione tra un'icona a forma di nuvola e un CircularProgressIndicator. L'icona a forma di nuvola aumenta di dimensioni quando l'utente trascina verso il basso e passa a un CircularProgressIndicator quando inizia l'azione di aggiornamento.
  • targetState utilizza isRefreshing per determinare lo stato da visualizzare (l'icona a forma di nuvola o l'indicatore di avanzamento circolare).
  • animationSpec definisce un'animazione tween per la transizione, con una durata specificata di CROSSFADE_DURATION_MILLIS.
  • state.distanceFraction rappresenta la distanza di trascinamento verso il basso dell'utente, che va da 0f (nessun trascinamento) a 1f (trascinamento completo).
  • Il modificatore graphicsLayer modifica la scala e la trasparenza.

Risultato

Questo video mostra l'indicatore personalizzato del codice precedente:

Risorse aggiuntive

• PullToRefreshState