Distintivos

Usa una insignia para mostrar un pequeño elemento visual que indique el estado o un valor numérico en otro elemento componible. A continuación, se incluyen algunos casos comunes en los que puedes usar una insignia:

  • Notificaciones: Muestra la cantidad de notificaciones no leídas en el ícono de una app o en la campana de notificaciones.
  • Mensajes: Indican mensajes nuevos o no leídos en una aplicación de chat.
  • Actualizaciones de estado: Muestran el estado de una tarea, como "completada", "en progreso" o "con errores".
  • Cantidad en el carrito: Muestra la cantidad de artículos en el carrito de compras de un usuario.
  • Contenido nuevo: Destaca el contenido o las funciones nuevos disponibles para el usuario.
Otro ejemplo del componente de insignia.
Figura 1: Ejemplos de insignias

Superficie de la API

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

  • content: Es el contenido componible que contiene el BadgedBox. Por lo general, Icon.
  • badge: Es el elemento componible que aparece como distintivo sobre el contenido. Por lo general, 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 al elemento Icon proporcionado que admite composición. Ten en cuenta lo siguiente en el código:

  • BadgedBox actúa como el contenedor general.
  • El argumento para el parámetro badge de BadgedBox es Badge. Como Badge no tiene argumentos propios, la app muestra la insignia predeterminada, que es un círculo rojo pequeño.
  • Icon sirve como argumento para el 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 aparece:

Es una insignia simple que no contiene contenido.
Figura 2: Es una implementación mínima de la insignia.

Ejemplo detallado

En el siguiente fragmento, se muestra cómo puedes mostrar valores en la insignia que responden a las acciones del usuario.

@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.

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

Esta implementación se ve de la siguiente manera:

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

Recursos adicionales