Carrusel

Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Un carrusel muestra una lista desplazable de elementos que se adaptan de forma dinámica según el tamaño de la ventana. Usa los carruseles para mostrar una colección de contenido relacionado. Los elementos del carrusel enfatizan las imágenes, 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:

• Multinavegación: Incluye elementos de diferentes tamaños. Se recomienda para explorar muchos elementos a la vez, como fotos.
• Sin contención: Contiene elementos de un solo tamaño que se extienden más allá del borde de la pantalla. Se puede personalizar para mostrar más texto o alguna otra IU sobre o debajo de cada elemento.
• Hero: Destaca una imagen grande en la que enfocarse y proporciona un adelanto 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.
• Pantalla completa: Muestra un elemento grande de borde a borde a la vez y se desplaza verticalmente. Se recomienda para el contenido que es más alto que ancho.

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

Plataforma de la API

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

• state: Es 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 del carrusel.
• itemSpacing: Define la cantidad de espacio vacío entre los elementos adyacentes en el carrusel.
• contentPadding: Aplica padding 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: Es una función componible que recibe un índice entero. Usa esta expresión 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 de los elementos:

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

Ejemplo de carrusel de navegación múltiple

Este fragmento implementa un carrusel de navegació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 un 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 la cantidad total de elementos.
  • Los elementos tienen un preferredItemWidth (aquí, 186.dp), que sugiere un ancho óptimo para cada elemento. El carrusel usa esto para determinar cuántos elementos pueden caber en la pantalla a la vez.
  • El parámetro itemSpacing agrega una pequeña brecha entre los elementos.
  • La expresión lambda final de HorizontalMultiBrowseCarousel itera en 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 contención

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

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