Carosello

Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Un carosello mostra un elenco scorrevole di elementi che si adattano dinamicamente in base alle dimensioni della finestra. Utilizza i caroselli per mostrare una raccolta di contenuti correlati. Gli elementi del carosello mettono in evidenza le immagini, ma possono anche contenere un breve testo che si adatta alle dimensioni dell'elemento.

Sono disponibili quattro layout carosello per adattarsi a diversi casi d'uso:

• Multi-browse: include articoli di dimensioni diverse. Consigliato per sfogliare molti elementi contemporaneamente, ad esempio foto.
• Senza limiti: contiene elementi di una sola dimensione che si estendono oltre il bordo dello schermo. Può essere personalizzato per mostrare più testo o un'altra interfaccia utente sopra o sotto ciascun elemento.
• Hero: mette in evidenza un'immagine grande su cui concentrarsi e offre un'anteprima di ciò che segue con un piccolo elemento. Consigliato per mettere in evidenza i contenuti che vuoi mettere in risalto, ad esempio le miniature di film o programmi.
• Schermo intero: mostra un elemento grande da un lato all'altro alla volta e scorre verticalmente. Consigliato per i contenuti più alti che larghi.

Questa pagina mostra come implementare i layout di carosello con più visualizzazioni e non contenuti. Per ulteriori informazioni sui tipi di layout, consulta le linee guida di Material 3 per i caroselli.

API surface

Per implementare caroselli con più visualizzazioni e non contenuti, utilizza i composabili HorizontalMultiBrowseCarousel e HorizontalUncontainedCarousel. Questi composabili condividono i seguenti parametri chiave:

• state: un'istanza di CarouselState che gestisce l'indice dell'elemento corrente e la posizione di scorrimento. Crea questo stato utilizzando rememberCarouselState { itemCount }, dove itemCount è il numero totale di elementi nel carosello.
• itemSpacing: definisce la quantità di spazio vuoto tra gli elementi adiacenti nel carousel.
• contentPadding: applica un'area di a capo intorno all'area dei contenuti del carosello. Utilizzalo per aggiungere spazio prima del primo elemento o dopo l'ultimo elemento oppure per fornire margini per gli elementi all'interno della regione scorrevole.
• content: una funzione componibile che riceve un indice intero. Utilizza questa funzione lambda per definire l'interfaccia utente di ogni elemento del carosello in base al relativo indice.

Questi composabili differiscono per il modo in cui specificano le dimensioni degli elementi:

• itemWidth (per HorizontalUncontainedCarousel): specifica la larghezza esatta di ogni elemento in un carosello non contenuto.
• preferredItemWidth (per HorizontalMultiBrowseCarousel): suggerisce la larghezza ideale per gli elementi di un carosello di navigazione multipla, consentendo al componente di visualizzare più elementi se lo spazio lo consente.

Esempio: carosello di navigazione multipla

Questo snippet implementa un carosello con più opzioni di navigazione:

@Composable
fun CarouselExample_MultiBrowse() {
    data class CarouselItem(
        val id: Int,
        @DrawableRes val imageResId: Int,
        val contentDescription: String
    )

    val items = remember {
        listOf(
            CarouselItem(0, R.drawable.cupcake, "cupcake"),
            CarouselItem(1, R.drawable.donut, "donut"),
            CarouselItem(2, R.drawable.eclair, "eclair"),
            CarouselItem(3, R.drawable.froyo, "froyo"),
            CarouselItem(4, R.drawable.gingerbread, "gingerbread"),
        )
    }

    HorizontalMultiBrowseCarousel(
        state = rememberCarouselState { items.count() },
        modifier = Modifier
            .fillMaxWidth()
            .wrapContentHeight()
            .padding(top = 16.dp, bottom = 16.dp),
        preferredItemWidth = 186.dp,
        itemSpacing = 8.dp,
        contentPadding = PaddingValues(horizontal = 16.dp)
    ) { i ->
        val item = items[i]
        Image(
            modifier = Modifier
                .height(205.dp)
                .maskClip(MaterialTheme.shapes.extraLarge),
            painter = painterResource(id = item.imageResId),
            contentDescription = item.contentDescription,
            contentScale = ContentScale.Crop
        )
    }
}
Carousel.kt

Punti chiave del codice

• Definisce una classe di dati CarouselItem, che struttura i dati per ogni elemento del carosello.
• Crea e memorizza un List di oggetti CarouselItem che vengono compilati con risorse e descrizioni delle immagini.
• Utilizza il composable HorizontalMultiBrowseCarousel, progettato per la visualizzazione di più elementi in un carosello.
  • Lo stato del carosello viene inizializzato utilizzando rememberCarouselState, che indica il conteggio totale degli elementi.
  • Gli elementi hanno un preferredItemWidth (qui 186.dp), che suggerisce una larghezza ottimale per ogni elemento. Il carosello lo utilizza per determinare quanti elementi possono essere visualizzati contemporaneamente sullo schermo.
  • Il parametro itemSpacing aggiunge un piccolo spazio tra gli elementi.
  • Il lambda finale di HorizontalMultiBrowseCarousel esegue l'iterazione di CarouselItems. In ogni iterazione, recupera l'elemento all'indice i e ne esegue il rendering di un composable Image.
  • Modifier.maskClip(MaterialTheme.shapes.extraLarge) applica una maschera di forma predefinita a ogni immagine, dandole angoli arrotondati.
  • contentDescription fornisce una descrizione dell'accessibilità per l'immagine.

Risultato

L'immagine seguente mostra il risultato dello snippet precedente:

Esempio: carosello non contenuto

Il seguente snippet implementa un carosello non contenuto:

@Composable
fun CarouselExample() {
    data class CarouselItem(
        val id: Int,
        @DrawableRes val imageResId: Int,
        val contentDescription: String
    )

    val carouselItems = remember {
        listOf(
            CarouselItem(0, R.drawable.cupcake, "cupcake"),
            CarouselItem(1, R.drawable.donut, "donut"),
            CarouselItem(2, R.drawable.eclair, "eclair"),
            CarouselItem(3, R.drawable.froyo, "froyo"),
            CarouselItem(4, R.drawable.gingerbread, "gingerbread"),
        )
    }

    HorizontalUncontainedCarousel(
        state = rememberCarouselState { carouselItems.count() },
        modifier = Modifier
            .fillMaxWidth()
            .wrapContentHeight()
            .padding(top = 16.dp, bottom = 16.dp),
        itemWidth = 186.dp,
        itemSpacing = 8.dp,
        contentPadding = PaddingValues(horizontal = 16.dp)
    ) { i ->
        val item = carouselItems[i]
        Image(
            modifier = Modifier
                .height(205.dp)
                .maskClip(MaterialTheme.shapes.extraLarge),
            painter = painterResource(id = item.imageResId),
            contentDescription = item.contentDescription,
            contentScale = ContentScale.Crop
        )
    }
}
Carousel.kt

Punti chiave del codice

• Il composable HorizontalUncontainedCarousel crea il layout del carosello.
  • Il parametro itemWidth imposta una larghezza fissa per ogni elemento del carosello.

Risultato

L'immagine seguente mostra il risultato dello snippet precedente: