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 mettono in risalto le immagini, ma possono anche contenere un breve testo che si adatta alle dimensioni dell'elemento.

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

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

Questa pagina mostra come implementare i layout di navigazione multipla e carosello non contenuto. Per ulteriori informazioni sui tipi di layout, consulta le linee guida di Material 3 per i caroselli.

Piattaforma API

Per implementare i caroselli con navigazione multipla e non contenuti, utilizza i componibili HorizontalMultiBrowseCarousel e HorizontalUncontainedCarousel. 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 la spaziatura interna intorno all'area dei contenuti del carosello. Utilizza questo attributo 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 la UI per ogni elemento del carosello in base al relativo indice.

Questi componibili differiscono nel 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 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 di navigazione multipla:

@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 per ogni elemento del carosello.
• Crea e memorizza un List di oggetti CarouselItem che vengono 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 assegnato il numero totale di elementi.
  • Gli elementi hanno un preferredItemWidth (qui, 186.dp), che suggerisce una larghezza ottimale per ogni elemento. Il carosello utilizza questo valore per determinare quanti elementi possono essere visualizzati contemporaneamente sullo schermo.
  • Il parametro itemSpacing aggiunge un piccolo spazio tra gli elementi.
  • La funzione lambda finale di HorizontalMultiBrowseCarousel esegue l'iterazione di CarouselItems. In ogni iterazione, recupera l'elemento all'indice i e esegue il rendering di un elemento componibile Image per l'elemento.
  • 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

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 sul 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: