Carrusel

Un carrusel muestra una lista de elementos desplazable que se adapta de forma dinámica según el tamaño de la ventana. Usa carruseles para mostrar una colección de contenido relacionado. Los elementos del carrusel enfatizan los elementos visuales, pero también pueden contener texto breve que se adapta al tamaño del elemento.

Hay cuatro diseños de carrusel disponibles para adaptarse a diferentes casos de uso:

• Multi-browse: Incluye elementos de diferentes tamaños. Se recomienda para explorar muchos elementos a la vez, como fotos.
• Sin contenedor: Contiene elementos de un solo tamaño que fluyen más allá del borde de la pantalla. Se puede personalizar para mostrar más texto o otra IU arriba o debajo de cada elemento.
• Hero: Destaca una imagen grande para enfocarse y proporciona un vistazo de lo que sigue con un elemento pequeño. Se recomienda para destacar el contenido que deseas enfatizar, como miniaturas de películas o programas.
• Full-screen: Muestra un elemento grande de borde a borde a la vez y se desplaza verticalmente. Se recomienda para contenido que es más alto que ancho.

En esta página, se muestra cómo implementar los diseños de carrusel de exploración múltiple y sin contenedor. Consulta los lineamientos de Material 3 para carruseles para obtener más información sobre los tipos de diseño.

Superficie de la API

Para implementar carruseles de exploración múltiple y sin contenedor, usa los HorizontalMultiBrowseCarousel y HorizontalUncontainedCarousel elementos componibles. Estos elementos componibles comparten los siguientes parámetros clave:

• state: Una instancia de CarouselState que administra el índice del elemento actual y la posición de desplazamiento. Crea este estado con rememberCarouselState { itemCount }, donde itemCount es la cantidad total de elementos en el carrusel.
• itemSpacing: Define la cantidad de espacio vacío entre los elementos adyacentes del carrusel.
• contentPadding: Aplica relleno alrededor del área de contenido del carrusel. Úsalo para agregar espacio antes del primer elemento o después del último, o para proporcionar márgenes para los elementos dentro de la región desplazable.
• content: Una función de componibilidad que recibe un índice entero. Usa esta lambda para definir la IU de cada elemento del carrusel según su índice.

Estos elementos componibles difieren en la forma en que especifican el tamaño del elemento:

• itemWidth (para HorizontalUncontainedCarousel): Especifica el ancho exacto de cada elemento en un carrusel sin contenedor.
• preferredItemWidth (para HorizontalMultiBrowseCarousel): Sugiere el ancho ideal para los elementos de un carrusel de exploración múltiple, lo que permite que el componente muestre varios elementos si el espacio lo permite.

Ejemplo: Carrusel de exploración múltiple

En este fragmento, se implementa un carrusel de exploración múltiple:

@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

Puntos clave sobre el código

• Define una clase de datos CarouselItem, que estructura los datos de cada elemento del carrusel.
• Crea y recuerda una List de objetos CarouselItem que se propagan con recursos de imagen y descripciones.
• Usa el elemento componible HorizontalMultiBrowseCarousel, que está diseñado para mostrar varios elementos en un carrusel.
  • El estado del carrusel se inicializa con rememberCarouselState, que recibe el recuento total de elementos.
  • Los elementos tienen un preferredItemWidth (aquí, 186.dp), que sugiere un ancho óptimo para cada elemento. El carrusel lo usa para determinar cuántos elementos pueden caber en la pantalla a la vez.
  • El parámetro itemSpacing agrega un pequeño espacio entre los elementos.
  • La lambda final de HorizontalMultiBrowseCarousel itera a través de los CarouselItems. En cada iteración, recupera el elemento en el índice i y renderiza un elemento componible Image para él.
  • Modifier.maskClip(MaterialTheme.shapes.extraLarge) aplica una máscara de forma predefinida a cada imagen, lo que le da esquinas redondeadas.
  • contentDescription proporciona una descripción de accesibilidad para la imagen.

Resultado

En la siguiente imagen, se muestra el resultado del fragmento anterior:

Ejemplo: Carrusel sin contenedor

En el siguiente fragmento, se implementa un carrusel sin contenedor:

@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

Puntos clave sobre el código

• El elemento componible HorizontalUncontainedCarousel crea el diseño del carrusel.
  • El parámetro itemWidth establece un ancho fijo para cada elemento del carrusel.

Resultado

En la siguiente imagen, se muestra el resultado del fragmento anterior: