Selos

Use um selo para mostrar um pequeno elemento visual e indicar o status ou um valor numérico em outro elemento combinável. Aqui estão 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 do app ou sino de notificação.
  • Mensagens: indique 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 do carrinho: exibe 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 selo.
Figura 1. Exemplos de selos

Plataforma da API

Use o elemento combinável BadgedBox para implementar selos no app. Em última instância, ele é um contêiner. Você controla a aparência dela 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 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

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

  • BadgedBox serve como o contêiner geral.
  • O argumento para o 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 sobre o qual o selo aparece. Nesse caso, é um ícone de e-mail.

Ele aparece assim:

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

Exemplo detalhado

O snippet a seguir demonstra como exibir 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 de containerColor e contentColor controlam a aparência do selo.
  • O elemento combinável Text para o slot de conteúdo de Badge aparece no selo. Nesse caso, ele mostra o número de itens no carrinho.

Essa 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