Carrousel

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Un carrousel affiche une liste déroulante d'éléments qui s'adaptent de manière dynamique en fonction de la taille de la fenêtre. Utilisez des carrousels pour présenter une collection de contenus associés. Les éléments du carrousel mettent l'accent sur les visuels, mais peuvent également contenir un texte court qui s'adapte à la taille de l'élément.

Quatre mises en page de carrousel sont disponibles pour différents cas d'utilisation:

• Multi-browsing (Multi-navigation) : inclut des éléments de différentes tailles. Recommandé pour parcourir de nombreux éléments à la fois, comme des photos.
• Non contenu: contient des éléments de taille unique qui débordent du bord de l'écran. Peut être personnalisé pour afficher plus de texte ou une autre UI au-dessus ou en dessous de chaque élément.
• Image principale: met en avant une grande image sur laquelle se concentrer et donne un aperçu de ce qui va suivre avec un petit élément. Recommandé pour mettre en avant des contenus que vous souhaitez mettre en avant, comme des miniatures de films ou d'émissions.
• Plein écran: affiche un élément de grande taille d'un bord à l'autre à la fois et défile verticalement. Recommandé pour les contenus plus hauts que larges.

Cette page explique comment implémenter les mises en page multi-parcours et sans conteneur. Pour en savoir plus sur les types de mise en page, consultez les consignes Material 3 concernant les carrousels.

Surface d'API

Pour implémenter la navigation multiple et les carrousels non contenus, utilisez les composables HorizontalMultiBrowseCarousel et HorizontalUncontainedCarousel. Ces composables partagent les paramètres clés suivants:

• state: instance CarouselState qui gère l'index de l'élément actuel et la position de défilement. Créez cet état à l'aide de rememberCarouselState { itemCount }, où itemCount correspond au nombre total d'éléments du carrousel.
• itemSpacing: définit la quantité d'espace vide laissé entre les éléments adjacents du carrousel.
• contentPadding: applique une marge intérieure autour de la zone de contenu du carrousel. Utilisez-le pour ajouter de l'espace avant le premier élément ou après le dernier élément, ou pour fournir des marges pour les éléments dans la région à faire défiler.
• content: fonction composable qui reçoit un indice entier. Utilisez ce lambda pour définir l'UI de chaque élément du carrousel en fonction de son indice.

Ces composables diffèrent dans la façon dont ils spécifient la taille des éléments:

• itemWidth (pour HorizontalUncontainedCarousel): spécifie la largeur exacte de chaque élément d'un carrousel non contenu.
• preferredItemWidth (pour HorizontalMultiBrowseCarousel): suggère la largeur idéale pour les éléments d'un carrousel multi-parcours, ce qui permet au composant d'afficher plusieurs éléments si l'espace le permet.

Exemple: Carrousel de plusieurs pages

Cet extrait implémente un carrousel de navigation multiple:

@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

Points clés concernant le code

• Définit une classe de données CarouselItem, qui structure les données de chaque élément du carrousel.
• Crée et mémorise un List d'objets CarouselItem remplis de ressources et de descriptions d'images.
• Utilise le composable HorizontalMultiBrowseCarousel, conçu pour afficher plusieurs éléments dans un carrousel.
  • L'état du carrousel est initialisé à l'aide de rememberCarouselState, qui reçoit le nombre total d'éléments.
  • Les éléments disposent d'un preferredItemWidth (ici, 186.dp), qui suggère une largeur optimale pour chaque élément. Le carrousel l'utilise pour déterminer le nombre d'éléments pouvant tenir à l'écran en même temps.
  • Le paramètre itemSpacing ajoute un petit espace entre les éléments.
  • Le lambda de fin de HorizontalMultiBrowseCarousel itère sur CarouselItems. À chaque itération, il récupère l'élément à l'index i et affiche un composable Image pour celui-ci.
  • Modifier.maskClip(MaterialTheme.shapes.extraLarge) applique un masque de forme prédéfini à chaque image, lui donnant des coins arrondis.
  • contentDescription fournit une description d'accessibilité pour l'image.

Résultat

L'image suivante montre le résultat de l'extrait de code précédent:

Exemple: Carrousel non contenu

L'extrait de code suivant implémente un carrousel non contenu:

@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

Points clés concernant le code

• Le composable HorizontalUncontainedCarousel crée la mise en page du carrousel.
  • Le paramètre itemWidth définit une largeur fixe pour chaque élément du carrousel.

Résultat

L'image suivante montre le résultat de l'extrait de code précédent: