Carosello

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

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

• Multi-browse: include elementi di dimensioni diverse. È consigliato per sfogliare molti elementi contemporaneamente, ad esempio le foto.
• Uncontained: contiene elementi di una singola dimensione che scorrono oltre il bordo dello schermo. Può essere personalizzato per mostrare più testo o altra UI sopra o sotto ogni elemento.
• Hero: mette in evidenza un'immagine di grandi dimensioni su cui concentrarsi e fornisce un'anteprima di ciò che segue con un piccolo elemento. È consigliato per mettere in evidenza i contenuti che vuoi enfatizzare, ad esempio le miniature di film o serie TV.
• Schermo intero: mostra un elemento di grandi dimensioni da bordo a bordo alla volta e scorre verticalmente. È consigliato per i contenuti più alti che larghi.

Questa pagina mostra come implementare i layout di carosello multi-browse e non contenuti. Per ulteriori informazioni sui tipi di layout, consulta le linee guida di Material 3 per i caroselli per.

Piattaforma API

Per implementare i caroselli multi-browse e non contenuti, utilizza i HorizontalMultiBrowseCarousel e HorizontalUncontainedCarousel componibili. Questi componibili condividono i seguenti parametri chiave:

• state: un'istanza 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 carosello.
• contentPadding: applica il padding intorno all'area dei contenuti del carosello. Utilizzalo per aggiungere spazio prima del primo elemento o dopo l'ultimo elemento o per fornire margini per gli elementi all'interno della regione scorrevole.
• content: una funzione componibile che riceve un indice intero. Utilizza questa lambda per definire l'UI di ogni elemento nel carosello in base al suo indice.

Questi componibili 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 in un carosello multi-browse, consentendo al componente di visualizzare più elementi se lo spazio lo consente.

Esempio: carosello multi-browse

Questo snippet implementa un carosello multi-browse:

@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 sul codice

• Definisce una classe di dati CarouselItem, che struttura i dati di ogni elemento del carosello.
• Crea e memorizza un List di oggetti CarouselItem compilati con risorse immagine e descrizioni.
• Utilizza il componibile HorizontalMultiBrowseCarousel, progettato per visualizzare più elementi in un carosello.
  • Lo stato del carosello viene inizializzato utilizzando rememberCarouselState, a cui viene fornito il conteggio totale degli elementi.
  • Gli elementi hanno una preferredItemWidth (in questo caso, 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.
  • La lambda finale di HorizontalMultiBrowseCarousel scorre gli CarouselItems. In ogni iterazione, recupera l'elemento all'indice i e ne esegue il rendering di un componibile Image.
  • Modifier.maskClip(MaterialTheme.shapes.extraLarge) applica una maschera di forma predefinita a ogni immagine, conferendole angoli arrotondati.
  • contentDescription fornisce una descrizione per l'accessibilità dell'immagine.

Risultato

L'immagine seguente mostra il risultato dello snippet precedente:

Esempio: carosello non contenuto

Lo snippet seguente 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 sul codice

• Il componibile 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: