Información sobre la herramienta

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

• Información sobre la herramienta simple: Describe elementos o acciones de los botones de ícono.
• Información sobre la herramienta enriquecida: Proporciona más detalles, como la descripción del valor de un atributo. También puede incluir un título, un vínculo y botones opcionales.

Superficie de la API

Puedes usar el elemento de componibilidad TooltipBox para implementar información sobre herramientas en tu app. Puedes controlar la apariencia de TooltipBox con estos parámetros principales:

• positionProvider: Coloca la información sobre la herramienta en relación con el contenido de la etiqueta de fijación. 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 la herramienta. Por lo general, usas los elementos componibles PlainTooltip o RichTooltip.
  • Usa PlainTooltip para describir elementos o acciones de los botones de ícono.
  • Usa RichTooltip para proporcionar más detalles, como describir el valor de una función. Las sugerencias enriquecidas pueden incluir un título, un vínculo y botones opcionales.
• state: Es el contenedor de estado que incluye la lógica de la IU y el estado del elemento para esta información sobre la herramienta.
• content: Es el contenido componible al que se ancla la información sobre la herramienta.

Muestra un cuadro de información simple

Usa un cuadro de información simple para describir brevemente un elemento de la IU. En este fragmento de código, se muestra una información sobre la herramienta simple sobre un botón de ícono, etiquetado como "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 con el texto "Agregar a favoritos".
  • TooltipDefaults.rememberPlainTooltipPositionProvider() proporciona un posicionamiento predeterminado para la información sobre herramientas sin formato.
  • tooltip es una función lambda que define el contenido de la información sobre la herramienta 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 la herramienta.
• 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, TooltipBox muestra la información sobre la herramienta con el texto "Agregar a favoritos". Según el dispositivo, los usuarios pueden activar la información sobre la herramienta de las siguientes maneras:
  • Colocar el cursor sobre el ícono
  • Manteniendo presionado el ícono en un dispositivo móvil

Resultado

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

Muestra un cuadro de información enriquecido

Usa un cuadro de información enriquecido para proporcionar contexto adicional sobre un elemento de la IU. En este ejemplo, se crea una información sobre la herramienta enriquecida de varias líneas con un título que se fija 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 información sobre la herramienta y TooltipBox muestra RichTooltip. El TooltipBox actúa como el ancla y el contenedor para el contenido y la información sobre la herramienta.
  • En este caso, el contenido es un componente IconButton, que proporciona el comportamiento de acción que se puede presionar. Cuando se mantenga presionado (en dispositivos táctiles) o se coloque el cursor sobre él (como con el puntero del mouse) en cualquier parte del contenido de TooltipBox, se mostrará la información sobre la herramienta para mostrar más información.
• El elemento componible RichTooltip define el contenido de la información sobre la herramienta, incluidos el título y el texto del cuerpo. TooltipDefaults.rememberRichTooltipPositionProvider() proporciona información de posicionamiento para las sugerencias enriquecidas.

Resultado

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

Cómo personalizar un cuadro de información enriquecido

En este fragmento de código, se muestra una información sobre la herramienta enriquecida con un título, acciones personalizadas y un símbolo de intercalación (flecha) personalizado 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)
                        }
                    }
                },
            ) {
                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 la herramienta con un título y una acción para descartar.
• Cuando se activa, ya sea manteniendo presionado o colocando el puntero 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 la herramienta, presiona en cualquier otro lugar de la pantalla o usa el botón de acción para descartar.
• Cuando se ejecuta la acción de descartar, el sistema inicia una corrutina para llamar a tooltipState.dismiss. Esto verifica que la ejecución de la acción no se bloquee mientras se muestra la información sobre la herramienta.
• onClick = coroutineScope.launch { tooltipState.show() } } inicia una corrutina para mostrar manualmente la información sobre la herramienta con tooltipState.show.
• El parámetro action permite agregar elementos interactivos a un cuadro de información, como un botón.
• El parámetro caretSize modifica el tamaño de la flecha de la información sobre la herramienta.

Resultado

En este ejemplo, se produce lo siguiente:

Recursos adicionales

• Material Design: Información sobre herramientas