Carrossel

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

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 textos breves que se adaptam 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 em muitos itens de uma vez, como fotos.
• Não contido: contém itens de um único tamanho e que fluem além da borda da tela. Pode ser personalizado para mostrar mais texto ou outra interface acima ou abaixo de cada item.
• Principal: destaca uma imagem grande para focar e mostra uma prévia do que vem por aí 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 borda a borda por vez e rola verticalmente. Recomendado para conteúdo mais alto do que largo.

Esta página mostra como implementar os layouts de carrossel multinavegação e sem contenção. Consulte as diretrizes do carrossel do Material 3 para mais informações sobre os tipos de layout.

Superfície da API

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

• state: uma instância CarouselState que gerencia o índice de 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 os itens adjacentes no carrinho.
• contentPadding: aplica o padding em torno da área de conteúdo do carrossel. Use essa opção para adicionar espaço antes do primeiro item ou depois do último item ou para fornecer margens para os itens na região rolável.
• content: uma função combinável que recebe um índice de número 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 sem contenção.
• preferredItemWidth (para HorizontalMultiBrowseCarousel): sugere a largura ideal para itens em um carrossel de navegação múltipla, permitindo que o componente exiba 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

Pontos principais sobre o código

• Define uma classe de dados CarouselItem, que estrutura os dados de cada elemento no carrossel.
• Cria e lembra um List de objetos CarouselItem que são 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 (neste caso, 186.dp), que sugere uma largura ideal para cada item. O carrossel usa isso para determinar quantos itens podem caber na tela de uma vez.
  • O parâmetro itemSpacing adiciona uma pequena lacuna entre os itens.
  • A lambda final de HorizontalMultiBrowseCarousel itera pelo CarouselItems. Em cada iteração, ele 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 cantos arredondados a ela.
  • contentDescription fornece uma descrição de acessibilidade para a imagem.

Resultado

A imagem a seguir mostra o resultado do snippet anterior:

Exemplo: carrossel sem contenção

O snippet a seguir implementa um carrossel sem contenção:

@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

Pontos principais 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: