Carrousel

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 répondre à différents cas d'utilisation :

• Multi-browse : 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 d'une seule taille qui dépassent le bord de l'écran. Peut être personnalisé pour afficher plus de texte ou d'autres éléments d'interface utilisateur au-dessus ou en dessous de chaque élément.
• Hero : met en avant une grande image sur laquelle se concentrer et donne un aperçu de la suite avec un petit élément. Recommandé pour mettre en avant du contenu que vous souhaitez souligner, comme des miniatures de films ou d'émissions.
• Plein écran : affiche un grand élément bord à bord à la fois et défile verticalement. Recommandé pour les contenus dont la hauteur est supérieure à la largeur.

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

Surface d'API

Pour implémenter des carrousels à plusieurs éléments et 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 dans le carrousel.
• itemSpacing : définit la quantité d'espace vide entre les éléments adjacents du carrousel.
• contentPadding : applique une marge intérieure autour de la zone de contenu du carrousel. Utilisez cette option pour ajouter de l'espace avant le premier élément ou après le dernier élément, ou pour définir des marges pour les éléments de la zone de défilement.
• content : fonction composable qui reçoit un index entier. Utilisez cette fonction lambda pour définir l'UI de chaque élément du carrousel en fonction de son index.

Ces composables diffèrent par 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 des éléments d'un carrousel à plusieurs éléments, ce qui permet au composant d'afficher plusieurs éléments si l'espace le permet.

Exemple : Carrousel de navigation multiple

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 renseignés avec des ressources d'image et des descriptions.
• 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 ont 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 s'afficher simultanément à l'écran.
  • Le paramètre itemSpacing ajoute un petit espace entre les éléments.
  • Le lambda de fin de HorizontalMultiBrowseCarousel effectue une itération 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, ce qui lui donne des angles arrondis.
  • contentDescription fournit une description de l'image pour l'accessibilité.

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 :