Distintivos

Usa una insignia para mostrar un elemento visual pequeño que indique el estado o un valor numérico en otro elemento que admite composición. Estos son algunos casos de uso comunes en los que podrías 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: Indica 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 nuevas que están disponibles para el usuario.
Diferentes ejemplos del componente de insignia.
Figura 1: Ejemplos de insignias

Superficie de la 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 contiene BadgedBox. Por lo general, Icon.
  • badge: Es el elemento componible que aparece como insignia sobre el contenido. Por lo general, el elemento de componibilidad Badge 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"
        )
    }
}

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

  • BadgedBox sirve como 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.

Así es como aparece:

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

Ejemplo detallado

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

@Composable
fun BadgeInteractiveExample() {
    var itemCount by remember { mutableIntStateOf(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")
        }
    }
}

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, muestra la cantidad de artículos que hay 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