Carrossel

Um carrossel mostra uma lista rolável de itens que se adaptam dinamicamente com base no tamanho da janela. Use carrosséis para mostrar uma coleção de conteúdo relacionado. Os itens do carrossel enfatizam os recursos visuais, mas também podem conter um texto breve que se adapta ao tamanho do item.

Há quatro layouts de carrossel disponíveis para atender a diferentes casos de uso:

• Navegação múltipla: inclui itens de tamanhos diferentes. Recomendado para navegar por muitos itens de uma só vez, como fotos.
• Não contido: contém itens de um único tamanho e que fluem pela borda da tela. Pode ser personalizado para mostrar mais texto ou outra interface acima ou abaixo de cada item.
• Hero: destaca uma imagem grande para focar e mostra uma prévia do que vem a seguir com um item pequeno. Recomendado para destacar conteúdo que você quer enfatizar, como miniaturas de filmes ou programas.
• Tela cheia: mostra um item grande de ponta a ponta por vez e rola verticalmente. Recomendado para conteúdo mais alto do que largo.

Esta página mostra como implementar os layouts de carrossel de navegação múltipla e não contido. Consulte as diretrizes do Material 3 do carrossel para mais informações sobre os tipos de layout.

Superfície da API

Para implementar carrosséis de navegação múltipla e não contidos, use os HorizontalMultiBrowseCarousel e HorizontalUncontainedCarousel elementos combináveis. Esses elementos combináveis compartilham os seguintes parâmetros principais:

• state: uma instância CarouselState que gerencia o índice do item atual e a posição de rolagem. Crie esse estado usando rememberCarouselState { itemCount }, em que itemCount é o número total de itens no carrossel.
• itemSpacing: define a quantidade de espaço vazio entre itens adjacentes no carrossel.
• contentPadding: aplica preenchimento na área de conteúdo do carrossel. Use isso para adicionar espaço antes do primeiro item ou depois do último, ou para fornecer margens para os itens na região rolável.
• content: uma função combinável que recebe um índice inteiro. Use essa lambda para definir a interface de cada item no carrossel com base no índice.

Esses elementos combináveis diferem na forma como especificam o tamanho do item:

• itemWidth (para HorizontalUncontainedCarousel): especifica a largura exata de cada item em um carrossel não contido.
• preferredItemWidth (para HorizontalMultiBrowseCarousel): sugere a largura ideal para itens em um carrossel de navegação múltipla, permitindo que o componente mostre vários itens se houver espaço.

Exemplo: carrossel de navegação múltipla

Este snippet implementa um carrossel de navegação múltipla:

@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

Principais pontos sobre o código

• Define uma classe de dados CarouselItem, que estrutura os dados de cada elemento no carrossel.
• Cria e lembra uma List de objetos CarouselItem preenchidos com recursos de imagem e descrições.
• Usa o elemento combinável HorizontalMultiBrowseCarousel, que foi projetado para mostrar vários itens em um carrossel.
  • O estado do carrossel é inicializado usando rememberCarouselState, que recebe a contagem total de itens.
  • Os itens têm um preferredItemWidth (aqui, 186.dp), que sugere uma largura ideal para cada item. O carrossel usa isso para determinar quantos itens podem caber na tela de uma só vez.
  • O parâmetro itemSpacing adiciona uma pequena lacuna entre os itens.
  • A lambda final de HorizontalMultiBrowseCarousel itera pelos CarouselItems. Em cada iteração, ela recupera o item no índice i e renderiza um elemento combinável Image para ele.
  • Modifier.maskClip(MaterialTheme.shapes.extraLarge) aplica uma máscara de forma predefinida a cada imagem, dando a ela cantos arredondados.
  • contentDescription fornece uma descrição de acessibilidade para a imagem.

Resultado

A imagem a seguir mostra o resultado do snippet anterior:

Exemplo: carrossel não contido

O snippet a seguir implementa um carrossel não contido:

@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

Principais pontos sobre o código

• O elemento combinável HorizontalUncontainedCarousel cria o layout do carrossel.
  • O parâmetro itemWidth define uma largura fixa para cada item no carrossel.

Resultado

A imagem a seguir mostra o resultado do snippet anterior: