Selos

Use um selo para mostrar um pequeno elemento visual que indica status ou um valor numérico em outro elemento combinável. Confira alguns cenários comuns em que você pode usar um selo:

  • Notificações: mostre o número de notificações não lidas em um ícone de app ou no sino de notificação.
  • Mensagens: indicam mensagens novas ou não lidas em um aplicativo de chat.
  • Atualizações de status: mostram o status de uma tarefa, como "concluída", "em andamento" ou "com falha".
  • Quantidade no carrinho: mostra o número de itens no carrinho de compras de um usuário.
  • Novo conteúdo: destaque novos conteúdos ou recursos disponíveis para o usuário.
Outro exemplo do componente de selo.
Figura 1. Exemplos de selos

Superfície da API

Use o elemento combinável BadgedBox para implementar selos no seu aplicativo. Ele é, em última análise, um contêiner. Você controla a aparência dele com estes dois parâmetros principais:

  • content: o conteúdo combinável que o BadgedBox contém. Normalmente, Icon.
  • badge: o elemento combinável que aparece como o selo sobre o conteúdo. Normalmente, o elemento combinável Badge dedicado.

Exemplo básico

Este snippet de código mostra uma implementação básica de BadgedBox:

@Composable
fun BadgeExample() {
    BadgedBox(
        badge = {
            Badge()
        }
    ) {
        Icon(
            imageVector = Icons.Filled.Mail,
            contentDescription = "Email"
        )
    }
}
Badges.kt

Este exemplo mostra um selo que se sobrepõe ao elemento combinável Icon fornecido. Observe o seguinte no código:

  • O BadgedBox serve como contêiner geral.
  • O argumento do parâmetro badge de BadgedBox é Badge. Como Badge não tem argumentos próprios, o app mostra o selo padrão, que é um pequeno círculo vermelho.
  • Icon serve como argumento para o parâmetro content de BadgedBox. É o ícone em que o selo aparece. Nesse caso, é um ícone de e-mail.

Ela aparece assim:

Um selo simples que não contém conteúdo.
Figura 2. Uma implementação mínima de selo.

Exemplo detalhado

O snippet a seguir demonstra como mostrar valores no selo que respondem às ações do usuário.

@Composable
fun BadgeInteractiveExample() {
    var itemCount by remember { mutableStateOf(0) }

    Column(
        verticalArrangement = Arrangement.spacedBy(16.dp)
    ) {
        BadgedBox(
            badge = {
                if (itemCount > 0) {
                    Badge(
                        containerColor = Color.Red,
                        contentColor = Color.White
                    ) {
                        Text("$itemCount")
                    }
                }
            }
        ) {
            Icon(
                imageVector = Icons.Filled.ShoppingCart,
                contentDescription = "Shopping cart",
            )
        }
        Button(onClick = { itemCount++ }) {
            Text("Add item")
        }
    }
}
Badges.kt

Este exemplo implementa um ícone de carrinho de compras com um selo que mostra o número de itens no carrinho do usuário.

  • O BadgedBox só aparece quando a contagem de itens é maior que zero.
  • Os argumentos para containerColor e contentColor controlam a aparência do selo.
  • O elemento combinável Text para o slot de conteúdo de Badge aparece dentro do selo. Nesse caso, ele mostra o número de itens no carrinho.

Esta implementação aparece da seguinte maneira:

Uma implementação de selo que contém o número de itens em um carrinho de compras.
Figura 3. Um selo que mostra o número de itens em um carrinho de compras.

Outros recursos