Distintivos

Usa una insignia para mostrar un pequeño elemento visual que denota el estado o un valor numérico en otro elemento componible. Estos son algunos casos comunes en los que podrías usar una insignia:

• Notificaciones: Muestra la cantidad de notificaciones no leídas en un ícono de la app o una campana de notificaciones.
• Mensajes: Indica los mensajes nuevos o no leídos en una aplicación de chat.
• Actualizaciones de estado: Muestran el estado de una tarea, como “completa”, “en curso” o “con errores”.
• Cantidad del carrito: Muestra la cantidad de artículos en el carrito de compras del usuario.
• Contenido nuevo: Destaca el contenido o las funciones nuevos disponibles para el usuario.

Figura 1: Ejemplos de insignias

Plataforma de API

Usa el elemento componible BadgedBox para implementar insignias en tu aplicación. En última instancia, es un contenedor. Puedes controlar su apariencia con estos dos parámetros principales:

• content: Es el contenido componible que incluye el BadgedBox. Por lo general, es Icon.
• badge: Es el elemento componible que aparece como insignia sobre el contenido. Por lo general, es el elemento Badge componible dedicado.

Ejemplo básico

En este fragmento de código, se muestra una implementación básica de BadgedBox:

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

En este ejemplo, se muestra una insignia que se superpone con el elemento componible Icon proporcionado. Ten en cuenta lo siguiente en el código:

• BadgedBox funciona como el contenedor general.
• El argumento del parámetro badge de BadgedBox es Badge. Como Badge no tiene argumentos propios, la app muestra la insignia predeterminada, que es un pequeño círculo rojo.
• Icon sirve como argumento del parámetro content de BadgedBox. Es el ícono sobre el que aparece la insignia. En este caso, es un ícono de correo electrónico.

Así es como se ve:

Figura 2: La implementación de una insignia es mínima.

Importante: Puedes pasar cualquier elemento componible a la ranura de contenido del elemento BadgedBox componible. Por lo tanto, puedes crear una insignia que se muestre en un Button, un Image o cualquier otro elemento componible.

Ejemplo detallado

En el siguiente fragmento, se indica cómo puedes mostrar los valores de la insignia que responden a las acciones de los usuarios.

@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

En este ejemplo, se implementa un ícono de carrito de compras con una insignia que muestra la cantidad de artículos en el carrito del usuario.

• Solo se muestra BadgedBox cuando el recuento de elementos es superior a 0.
• Los argumentos de containerColor y contentColor controlan el aspecto de la insignia.
• El elemento Text componible para el espacio de contenido de Badge aparece dentro de la insignia. En este caso, muestra la cantidad de artículos en el carrito.

Esta implementación aparece de la siguiente manera:

Figura 3: Es una insignia que muestra la cantidad de artículos en un carrito de compras.

Recursos adicionales

• Material 3: Insignias
• BadgedBox
• Badge