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: mostrar o número de notificações não lidas no ícone de um 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". "no progresso", ou "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. Ela é, em última instância, um contêiner. Você controla a aparência dele com estas duas parâmetros:

  • 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. Observação 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 padrão que é um pequeno círculo vermelho.
  • Icon serve como argumento para o parâmetro content de BadgedBox. Ela é 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 responder à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 exibe 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 em o 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