Botones de íconos

Los botones de ícono muestran las acciones que los usuarios pueden realizar. Los botones de ícono deben usar un ícono con un significado claro y, por lo general, representan acciones comunes o de uso frecuente.

Existen dos tipos de botones de ícono:

  • Predeterminado: Estos botones pueden abrir otros elementos, como un menú o una búsqueda.
  • Activar o desactivar: Estos botones pueden representar acciones binarias que se pueden activar o desactivar, como "favorito" o "marcador".
Cinco botones con diferentes íconos, como configuración y más. Algunos están rellenos, lo que indica que están seleccionados, y otros tienen un contorno.
Figura 1: Botones de ícono; algunos están rellenos (lo que indica que están seleccionados) y otros tienen un contorno.

Superficie de la API

Usa el elemento componible IconButton para implementar botones de ícono estándar y IconToggleButton para un botón que alterna entre los estados seleccionado y no seleccionado. Para crear diferentes estilos visuales, como relleno, relleno tonal o contorno, usa FilledIconButton, FilledTonalIconButton y OutlinedIconButton, o sus contrapartes activables FilledIconToggleButton, FilledTonalIconToggleButton y OutlinedIconToggleButton.

Los parámetros clave para IconButton incluyen los siguientes:

  • onClick: Es una función lambda que se ejecuta cuando el usuario presiona el botón de ícono.
  • enabled: Es un valor booleano que controla el estado habilitado del botón. Cuando es false, el botón no responde a la entrada del usuario.
  • content: Es el contenido componible dentro del botón, por lo general, un Icon.

Los parámetros clave para IconToggleButton incluyen los siguientes:

  • checked: Es un valor booleano que controla el estado seleccionado del botón.
  • onCheckedChange: Es una función lambda que se ejecuta cuando el usuario presiona el botón y proporciona el nuevo estado de marcado.
  • enabled: Es un valor booleano que controla el estado habilitado del botón. Cuando es false, el botón no responde a la entrada del usuario.

Ejemplo básico: Botón de activación con ícono

Cuando un usuario activa o desactiva los botones de ícono, le permite seleccionar una opción (como agregar o quitar un elemento de favoritos), o bien anular su selección. IconToggleButton y sus variantes están diseñadas para este propósito.

En el siguiente ejemplo, se muestra cómo implementar un botón de activación con ícono que cambia su apariencia según si está seleccionado o no, administrando el estado con IconButton:

@Preview
@Composable
fun ToggleIconButtonExample() {
    // isToggled initial value should be read from a view model or persistent storage.
    var isToggled by rememberSaveable { mutableStateOf(false) }

    IconButton(
        onClick = { isToggled = !isToggled }
    ) {
        Icon(
            painter = if (isToggled) painterResource(R.drawable.favorite_filled) else painterResource(R.drawable.favorite),
            contentDescription = if (isToggled) "Selected icon button" else "Unselected icon button."
        )
    }
}

Puntos clave sobre el código

  • El elemento ToggleIconButtonExample que admite composición define un IconButton que se puede activar o desactivar.
    • mutableStateOf(false) crea un objeto MutableState que contiene un valor booleano, inicialmente false. Esto convierte a isToggled en un contenedor de estado, lo que significa que Compose recompone la IU cada vez que cambia su valor.
    • rememberSaveable se asegura de que el estado de isToggled persista en los cambios de configuración, como la rotación de la pantalla.
  • La lambda onClick de IconButton define el comportamiento del botón cuando se hace clic en él, lo que alterna el estado entre true y false.
  • El parámetro painter del elemento que admite composición Icon carga de forma condicional un painterResource diferente según el estado de isToggled. Esto cambia la apariencia visual del ícono.
    • Si isToggled es true, se carga el elemento de diseño de corazón relleno.
    • Si isToggled es false, se carga el elemento de diseño de corazón con contorno.
  • El contentDescription del Icon también se actualiza según el estado de isToggled para proporcionar información de accesibilidad adecuada.

Resultado

En la siguiente imagen, se muestra el botón de ícono de activación del fragmento anterior en su estado seleccionado:

Figura 2. Un botón de activación de "favorito" en su estado seleccionado.

Ejemplo avanzado: Acciones repetidas al presionar

En esta sección, se muestra cómo crear botones de ícono que activen una acción de forma continua mientras el usuario los mantiene presionados, en lugar de activarla solo una vez por clic.

@Composable
fun MomentaryIconButton(
    unselectedImage: Int,
    selectedImage: Int,
    contentDescription: String,
    modifier: Modifier = Modifier,
    stepDelay: Long = 100L, // Minimum value is 1L milliseconds.
    onClick: () -> Unit
) {
    val interactionSource = remember { MutableInteractionSource() }
    val isPressed by interactionSource.collectIsPressedAsState()
    val pressedListener by rememberUpdatedState(onClick)

    LaunchedEffect(isPressed) {
        while (isPressed) {
            delay(stepDelay.coerceIn(1L, Long.MAX_VALUE))
            pressedListener()
        }
    }

    IconButton(
        modifier = modifier,
        onClick = onClick,
        interactionSource = interactionSource
    ) {
        Icon(
            painter = if (isPressed) painterResource(id = selectedImage) else painterResource(id = unselectedImage),
            contentDescription = contentDescription,
        )
    }
}

Puntos clave sobre el código

  • MomentaryIconButton toma un unselectedImage: Int, el ID de recurso de elemento de diseño para el ícono cuando no se presiona el botón, y selectedImage: Int, el ID de recurso de elemento de diseño para el ícono cuando se presiona el botón.
  • Usa un interactionSource para hacer un seguimiento específico de las interacciones de "presión" del usuario.
  • isPressed es verdadero cuando se presiona el botón de forma activa y falso en caso contrario. Cuando isPressed es true, el LaunchedEffect ingresa un bucle.
    • Dentro de este bucle, usa un delay (con stepDelay) para crear pausas entre las acciones de activación. coerceIn garantiza que la demora sea de al menos 1 ms para evitar bucles infinitos.
    • Se invoca pressedListener después de cada retraso dentro del bucle. Esto hace que la acción se repita.
  • pressedListener usa rememberUpdatedState para garantizar que la lambda onClick (la acción que se debe realizar) siempre sea la más actualizada de la composición más reciente.
  • El Icon cambia la imagen que se muestra según si el botón está presionado o no.
    • Si isPressed es verdadero, se muestra selectedImage.
    • De lo contrario, se muestra unselectedImage.

Luego, usa este MomentaryIconButton en un ejemplo. En el siguiente fragmento, se muestran dos botones de ícono que controlan un contador:

@Preview()
@Composable
fun MomentaryIconButtonExample() {
    var pressedCount by remember { mutableIntStateOf(0) }

    Row(
        modifier = Modifier.fillMaxWidth(),
        verticalAlignment = Alignment.CenterVertically
    ) {
        MomentaryIconButton(
            unselectedImage = R.drawable.fast_rewind,
            selectedImage = R.drawable.fast_rewind_filled,
            stepDelay = 100L,
            onClick = { pressedCount -= 1 },
            contentDescription = "Decrease count button"
        )
        Spacer(modifier = Modifier)
        Text("advanced by $pressedCount frames")
        Spacer(modifier = Modifier)
        MomentaryIconButton(
            unselectedImage = R.drawable.fast_forward,
            selectedImage = R.drawable.fast_forward_filled,
            contentDescription = "Increase count button",
            stepDelay = 100L,
            onClick = { pressedCount += 1 }
        )
    }
}

Puntos clave sobre el código

  • El elemento MomentaryIconButtonExample que admite composición muestra una Row que contiene dos instancias de MomentaryIconButton y un elemento Text que admite composición para compilar una IU que incremente y disminuya un contador.
  • Mantiene una variable de estado mutable pressedCount con remember y mutableIntStateOf, inicializada en 0. Cuando cambia pressedCount, se vuelven a componer todos los elementos componibles que lo observan (como el elemento componible Text) para reflejar el valor nuevo.
  • El primer MomentaryIconButton disminuye pressedCount cuando se hace clic en él o se mantiene presionado.
  • El segundo MomentaryIconButton aumenta pressedCount cuando se hace clic en él o se mantiene presionado.
  • Ambos botones usan un stepDelay de 100 milisegundos, lo que significa que la acción onClick se repite cada 100 ms mientras se mantiene presionado un botón.

Resultado

En el siguiente video, se muestra la IU con los botones de ícono y el contador:

Figura 3. Una IU de contador con dos botones de ícono (más y menos) que aumentan y disminuyen el contador

Actualización de M3 Expressive

Con la actualización de M3 Expressive, los botones de ícono admiten opciones adicionales de tamaño, esquina y ancho, y pueden cambiar de forma cuando se presionan o seleccionan. Cuando se colocan en grupos de botones estándar, los botones de ícono también interactúan con los botones vecinos cuando se presionan.

Forma animada

Los botones de ícono pueden animar su forma cuando se presionan, y los botones de ícono de activación pueden animar su forma según su estado de marcado. Para habilitar la animación de formas, pasa IconButtonDefaults.shapes() o IconButtonDefaults.toggleableShapes() al parámetro shapes de IconButton o IconToggleButton.

Botones de ícono

Estados del botón de ícono
Figura 4: Animación de la forma de un botón de ícono en formas redondas y cuadradas.

En el siguiente fragmento, se muestra cómo implementar un botón de ícono que anima su forma cuando se presiona:

@Composable
fun IconButtonWithAnimatedShapeSample() {
    IconButton(
        onClick = { /* doSomething() */ },
        shapes = IconButtonDefaults.shapes(),
    ) {
        Icon(painter = rememberVectorPainter(AppIcons.LockFilled), contentDescription = "Localized description")
    }
}

Botones de activación con ícono

Estados del botón de ícono de activación
Figura 5: Animación de la forma del botón de activación con ícono en los estados seleccionado y no seleccionado.

En el siguiente fragmento, se muestra cómo implementar un botón de activación con ícono que anima su forma según su estado de marcado:

@Composable
fun IconToggleButtonWithAnimatedShapeSample() {
    var checked by remember { mutableStateOf(false) }
    IconToggleButton(
        checked = checked,
        onCheckedChange = { checked = it },
        shapes = IconButtonDefaults.toggleableShapes(),
    ) {
        if (checked) {
            Icon(painter = rememberVectorPainter(AppIcons.LockFilled), contentDescription = "Localized description")
        } else {
            Icon(painter = rememberVectorPainter(AppIcons.Lock), contentDescription = "Localized description")
        }
    }
}

Variantes de tamaño, ancho y forma

Los botones de ícono están disponibles en formas redondas y cuadradas, cinco tamaños y tres anchos.

Ejemplos de tamaños, formas y anchos de botones de íconos.
Figura 6: Los atributos expresivos incluyen cinco tamaños, dos formas y tres anchos.

Para obtener más información sobre las actualizaciones de M3 Expressive para los botones de ícono, consulta los lineamientos de los botones de ícono de Material Design 3.

Existen cinco variantes de tamaño de botones de ícono: extrapequeño, pequeño, mediano, grande y extragrande. Cada tamaño admite tres opciones de ancho: uniforme (predeterminado), estrecho y ancho.

Cinco filas y tres columnas de botones de ícono que muestran un ícono de corazón. Cada fila aumenta de tamaño, y las tres columnas varían según el ancho: uniforme, estrecho y ancho.
Figura 7: Botones de íconos que muestran cinco tamaños y tres opciones de ancho: uniforme, estrecho y ancho.

Los botones de ícono están disponibles en variantes de esquinas redondeadas o cuadradas, y los botones de ícono de activación cambian de forma cuando se presionan o seleccionan.

Dos filas de cinco botones de ícono con un ícono de corazón, que aumentan de tamaño de izquierda a derecha; la fila superior tiene esquinas redondeadas y la fila inferior tiene esquinas cuadradas.
Figura 8: Botones de ícono disponibles en variantes de esquinas redondeadas o cuadradas

Para obtener orientación sobre cómo elegir entre las variantes de esquinas, consulta los lineamientos de los botones de ícono de Material Design 3.

Recursos adicionales