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 de carrousel mettent l'accent sur les éléments visuels, mais peuvent également contenir un bref texte qui s'adapte à la taille de l'élément.

Quatre mises en page de carrousel sont disponibles pour s'adapter à 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.
• Uncontained : 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 une autre interface utilisateur au-dessus ou en dessous de chaque élément.
• Hero : met en évidence une grande image sur laquelle se concentrer et fournit un aperçu de la suite avec un petit élément. Recommandé pour mettre en avant du contenu que vous souhaitez mettre en avant, comme des miniatures de films ou de séries.
• Plein écran : affiche un grand élément bord à bord à la fois et défile verticalement. Recommandé pour les contenus plus hauts que larges.

Cette page vous explique comment implémenter les mises en page de carrousel "Multi-browse" et "Uncontained". Pour en savoir plus sur les types de mise en page, consultez les consignes Material 3 pour les carrousels pour.

Surface d'API

Pour implémenter des carrousels "Multi-browse" et "Uncontained", utilisez les HorizontalMultiBrowseCarousel et HorizontalUncontainedCarousel composables. 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 un remplissage 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 fournir des marges pour les éléments dans la région défilable.
• content : fonction composable qui reçoit un index entier. Utilisez ce lambda pour définir l'interface utilisateur de chaque élément du carrousel en fonction de son index.

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

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

Exemple : Carrousel "Multi-browse"

Cet extrait implémente un carrousel "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

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 une List d'objets CarouselItem qui sont remplis de ressources d'image et de 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 une preferredItemWidth (ici, 186.dp), ce 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 à la fois.
  • Le paramètre itemSpacing ajoute un petit espace entre les éléments.
  • Le lambda de fin de HorizontalMultiBrowseCarousel itère sur les CarouselItems. À chaque itération, il récupère l'élément à l'index i et affiche un Image composable 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 d'accessibilité pour l'image.

Résultat

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

Exemple : Carrousel "Uncontained"

L'extrait suivant implémente un carrousel "Uncontained" :

@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 précédent :