Información sobre la herramienta

Usa ventanas de información para agregar contexto a un botón o a otro elemento de la IU. Existen dos tipos de cuadros de información:

  • Consignas de herramientas simples: Describen elementos o acciones de botones de íconos.
  • Información sobre herramientas enriquecida: Proporciona más detalles, como describir el valor de una función. También puedes incluir un título, un vínculo y botones opcionales.
Una ventana de información simple de una sola línea etiquetada (1) y una ventana de información enriquecida de varias líneas con un título y un bloque de información etiquetados (2).
Figura 1: Una información sobre herramientas sin formato (1) y una enriquecida (2).

Plataforma de la API

Puedes usar el elemento componible TooltipBox para implementar las indicaciones sobre herramientas en tu app. Controlas el aspecto de TooltipBox con estos parámetros principales:

  • positionProvider: Coloca la información sobre herramientas en relación con el contenido del ancla. Por lo general, usas un proveedor de posición predeterminado de TooltipDefaults, o bien puedes proporcionar el tuyo si necesitas una lógica de posicionamiento personalizada.
  • tooltip: Es el elemento componible que contiene el contenido de la información sobre herramientas. Por lo general, usas los elementos componibles PlainTooltip o RichTooltip.
    • Usa PlainTooltip para describir elementos o acciones de botones de íconos.
    • Usa RichTooltip para proporcionar más detalles, como describir el valor de una función. Las ventanas de información enriquecidas pueden incluir un título, un vínculo y botones opcionales.
  • state: Es el contenedor de estado que contiene la lógica de la IU y el estado del elemento para esta información sobre herramientas.
  • content: Es el contenido componible al que está anclada la información sobre herramientas.

Cómo mostrar una información sobre la herramienta sin formato

Usa una información sobre herramientas simple para describir brevemente un elemento de la IU. En este fragmento de código, se muestra una información sobre herramientas simple sobre un botón de ícono con la etiqueta “Agregar a favoritos”:

@Composable
fun PlainTooltipExample(
    modifier: Modifier = Modifier,
    plainTooltipText: String = "Add to favorites"
) {
    TooltipBox(
        modifier = modifier,
        positionProvider = TooltipDefaults.rememberPlainTooltipPositionProvider(),
        tooltip = {
            PlainTooltip { Text(plainTooltipText) }
        },
        state = rememberTooltipState()
    ) {
        IconButton(onClick = { /* Do something... */ }) {
            Icon(
                imageVector = Icons.Filled.Favorite,
                contentDescription = "Add to favorites"
            )
        }
    }
}

Tooltips.kt

Puntos clave sobre el código

  • TooltipBox genera una información sobre la herramienta simple con el texto "Agregar a favoritos".
    • TooltipDefaults.rememberPlainTooltipPositionProvider() proporciona el posicionamiento predeterminado para las indicaciones sobre herramientas sin formato.
    • tooltip es una función lambda que define el contenido de la información sobre herramientas con el elemento componible PlainTooltip.
    • Text(plainTooltipText) muestra el texto dentro de la información sobre la herramienta.
    • tooltipState controla el estado de la información sobre herramientas.
  • IconButton crea un botón en el que se puede hacer clic con un ícono.
    • Icon(...) muestra un ícono de corazón dentro del botón.
    • Cuando un usuario interactúa con IconButton, se muestra la información sobre herramientas con el texto “Agregar a favoritos”. Según el dispositivo, los usuarios pueden activar la información sobre herramientas de las siguientes maneras:
    • Colocar el cursor sobre el ícono
    • Mantener presionado el ícono en un dispositivo móvil

Resultado

En este ejemplo, se produce un cuadro de información simple sobre un ícono:

Información sobre la herramienta de una sola línea que contiene el texto
Figura 2: Es una información sobre la herramienta simple que aparece cuando un usuario coloca el cursor sobre el ícono de corazón o lo mantiene presionado.

Cómo mostrar un cuadro de información enriquecido

Usa una información sobre herramientas enriquecida para proporcionar contexto adicional sobre un elemento de la IU. En este ejemplo, se crea una información sobre herramientas enriquecida de varias líneas con un título anclado a un Icon:

@Composable
fun RichTooltipExample(
    modifier: Modifier = Modifier,
    richTooltipSubheadText: String = "Rich Tooltip",
    richTooltipText: String = "Rich tooltips support multiple lines of informational text."
) {
    TooltipBox(
        modifier = modifier,
        positionProvider = TooltipDefaults.rememberRichTooltipPositionProvider(),
        tooltip = {
            RichTooltip(
                title = { Text(richTooltipSubheadText) }
            ) {
                Text(richTooltipText)
            }
        },
        state = rememberTooltipState()
    ) {
        IconButton(onClick = { /* Icon button's click event */ }) {
            Icon(
                imageVector = Icons.Filled.Info,
                contentDescription = "Show more information"
            )
        }
    }
}
Tooltips.kt

Puntos clave sobre el código

  • TooltipBox controla los objetos de escucha de eventos para las interacciones del usuario y actualiza TooltipState según corresponda. Cuando TooltipState indica que se debe mostrar la información sobre la herramienta, se ejecuta la lambda de la información sobre la herramienta y se muestra RichTooltip. El TooltipBox actúa como ancla y contenedor del contenido y la información sobre herramientas.
    • En este caso, el contenido es un componente IconButton, que proporciona el comportamiento de acción que se puede presionar. Cuando se mantenga presionada la pantalla (en dispositivos táctiles) o se coloque el cursor (como con el puntero del mouse) sobre cualquier parte del contenido de TooltipBox, se mostrará la información sobre herramientas para mostrar más información.
  • El elemento componible RichTooltip define el contenido de la información sobre herramientas, incluido el título y el texto del cuerpo. TooltipDefaults.rememberRichTooltipPositionProvider() proporciona información de posicionamiento para las herramientas de ayuda enriquecidas.

Resultado

En este ejemplo, se produce una información sobre herramientas enriquecida con un título adjunto a un ícono de información:

Un cuadro de información de varias líneas con el título
Figura 3: Una información sobre herramientas enriquecida con un título y un ícono de información.

Cómo personalizar una información sobre herramientas enriquecida

Este fragmento de código muestra una información sobre herramientas enriquecida con un título, acciones personalizadas y una virgulilla (flecha) personalizada que se muestra sobre un botón de ícono de cámara:

@Composable
fun AdvancedRichTooltipExample(
    modifier: Modifier = Modifier,
    richTooltipSubheadText: String = "Custom Rich Tooltip",
    richTooltipText: String = "Rich tooltips support multiple lines of informational text.",
    richTooltipActionText: String = "Dismiss"
) {
    val tooltipState = rememberTooltipState()
    val coroutineScope = rememberCoroutineScope()

    TooltipBox(
        modifier = modifier,
        positionProvider = TooltipDefaults.rememberRichTooltipPositionProvider(),
        tooltip = {
            RichTooltip(
                title = { Text(richTooltipSubheadText) },
                action = {
                    Row {
                        TextButton(onClick = {
                            coroutineScope.launch {
                                tooltipState.dismiss()
                            }
                        }) {
                            Text(richTooltipActionText)
                        }
                    }
                },
                caretSize = DpSize(32.dp, 16.dp)
            ) {
                Text(richTooltipText)
            }
        },
        state = tooltipState
    ) {
        IconButton(onClick = {
            coroutineScope.launch {
                tooltipState.show()
            }
        }) {
            Icon(
                imageVector = Icons.Filled.Camera,
                contentDescription = "Open camera"
            )
        }
    }
}
Tooltips.kt

Puntos clave sobre el código

  • Un RichToolTip muestra una información sobre herramientas con un título y una acción para descartar.
  • Cuando se activa, ya sea con una presión prolongada o colocando el cursor del mouse sobre el contenido de ToolTipBox, la información sobre la herramienta se muestra durante aproximadamente un segundo. Para descartar esta información sobre herramientas, presiona en otro lugar de la pantalla o usa el botón de acción para descartar.
  • Cuando se ejecuta la acción de descartar, se inicia una corrutina para llamar a tooltipState.dismiss. Esto garantiza que la ejecución de la acción no se bloquee mientras se muestra la información sobre herramientas.
  • onClick = coroutineScope.launch { tooltipState.show() } } inicia una corrutina para mostrar la información sobre herramientas de forma manual con tooltipState.show.
  • El parámetro action permite agregar elementos interactivos a una tooltip, como un botón.
  • El parámetro caretSize modifica el tamaño de la flecha de la información sobre herramientas.

Resultado

En este ejemplo, se produce lo siguiente:

Información sobre herramientas de varias líneas con el título
Figura 4: Una información sobre herramientas enriquecida personalizada con una acción para descartar anclada a un ícono de cámara.

Recursos adicionales