Descrizione comando

Utilizza i tooltip per aggiungere contesto a un pulsante o a un altro elemento UI. Esistono due tipi di descrizioni comando:

• Tooltip semplici: descrivono elementi o azioni dei pulsanti con icone.
• Tooltip avanzati: forniscono maggiori dettagli, ad esempio descrivono il valore di una funzionalità. Può anche includere un titolo, un link e dei pulsanti facoltativi.

Figura 1. Un tooltip semplice (1) e un tooltip avanzato (2).

Piattaforma API

Puoi utilizzare il composable TooltipBox per implementare i tooltip nella tua app. Puoi controllare l'aspetto di TooltipBox con questi parametri principali:

• positionProvider: posiziona il tooltip in relazione ai contenuti di ancoraggio. In genere, utilizzi un provider di posizione predefinito di TooltipDefaults oppure puoi fornirne uno tuo se hai bisogno di una logica di posizionamento personalizzata.
• tooltip: il composable che contiene i contenuti del tooltip. In genere, utilizzi i componibili PlainTooltip o RichTooltip.
  • Utilizza PlainTooltip per descrivere elementi o azioni dei pulsanti di icone.
  • Utilizza RichTooltip per fornire maggiori dettagli, ad esempio per descrivere il valore di una funzionalità. I tooltip avanzati possono includere un titolo, un link e dei pulsanti facoltativi.
• state: il contenitore di stato che contiene la logica della UI e lo stato degli elementi per questo tooltip.
• content: il contenuto componibile a cui è ancorato il tooltip.

Visualizza un tooltip semplice

Utilizza un tooltip semplice per descrivere brevemente un elemento UI. Questo snippet di codice mostra un tooltip semplice sopra un pulsante con icona, con l'etichetta "Aggiungi ai preferiti":

@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(
                painter = rememberVectorPainter(AppIcons.Favorite),
                contentDescription = "Add to favorites"
            )
        }
    }
}
Tooltips.kt

Punti chiave sul codice

• TooltipBox genera un tooltip con il testo "Aggiungi ai preferiti".
  • TooltipDefaults.rememberPlainTooltipPositionProvider() fornisce il posizionamento predefinito per i tooltip semplici.
  • tooltip è una funzione lambda che definisce i contenuti della descrizione comando utilizzando il componibile PlainTooltip.
  • Text(plainTooltipText) mostra il testo all'interno del tooltip.
  • tooltipState controlla lo stato della descrizione comando.
• IconButton crea un pulsante cliccabile con un'icona.
  • Icon(...) mostra un'icona a forma di cuore all'interno del pulsante.
  • Quando un utente interagisce con IconButton, TooltipBox mostra il tooltip con il testo "Aggiungi ai preferiti". A seconda del dispositivo, gli utenti possono attivare il tooltip nei seguenti modi:
  • Passaggio del mouse sull'icona con un cursore
  • Tenendo premuta l'icona su un dispositivo mobile

Risultato

Questo esempio produce un tooltip semplice sopra un'icona:

Figura 2. Un semplice tooltip che viene visualizzato quando un utente passa il mouse sopra l'icona a forma di cuore o la tiene premuta.

Visualizza un tooltip avanzato

Utilizza un tooltip avanzato per fornire un contesto aggiuntivo su un elemento UI. Questo esempio crea un tooltip avanzato multilinea con un titolo ancorato 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(
                painter = rememberVectorPainter(AppIcons.Info),
                contentDescription = "Show more information"
            )
        }
    }
}
Tooltips.kt

Punti chiave sul codice

• TooltipBox gestisce i listener di eventi per le interazioni utente e aggiorna TooltipState di conseguenza. Quando TooltipState indica che il tooltip deve essere mostrato, viene eseguita la funzione lambda del tooltip e TooltipBox visualizza RichTooltip. TooltipBox funge da ancoraggio e contenitore sia per i contenuti sia per il tooltip.
  • In questo caso, i contenuti sono un componente IconButton, che fornisce il comportamento dell'azione toccabile. Quando viene premuto a lungo (su dispositivi touch) o quando il puntatore del mouse viene posizionato sopra un punto qualsiasi dei contenuti di TooltipBox, viene visualizzato il tooltip per mostrare ulteriori informazioni.
• Il composable RichTooltip definisce i contenuti del tooltip, inclusi il titolo e il corpo del testo. TooltipDefaults.rememberRichTooltipPositionProvider() fornisce informazioni sulla posizione per i tooltip avanzati.

Risultato

Questo esempio genera una descrizione comando estesa con un titolo associato a un'icona informazioni:

Figura 3. Un tooltip avanzato con un titolo e un'icona informazioni.

Personalizza un tooltip avanzato

Questo snippet di codice mostra un tooltip esteso con un titolo, azioni personalizzate e un cursore del testo personalizzato (freccia) visualizzato sopra un pulsante con l'icona della fotocamera:

@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(
                painter = rememberVectorPainter(AppIcons.Camera),
                contentDescription = "Open camera"
            )
        }
    }
}
Tooltips.kt

Punti chiave sul codice

• Un RichTooltip mostra un tooltip con un titolo e un'azione di chiusura.
• Quando viene attivato, tramite una pressione prolungata o passando il puntatore del mouse sopra i contenuti TooltipBox, il tooltip viene visualizzato per circa un secondo. Puoi ignorare questo tooltip toccando un altro punto dello schermo o utilizzando il pulsante di azione Ignora.
• Quando viene eseguita l'azione di chiusura, il sistema avvia una coroutine per chiamare tooltipState.dismiss. In questo modo, l'esecuzione dell'azione non viene bloccata mentre viene visualizzato il tooltip.
• onClick = coroutineScope.launch { tooltipState.show() } } avvia una coroutine per mostrare manualmente il tooltip utilizzando tooltipState.show.
• Il parametro action consente di aggiungere elementi interattivi a un tooltip, ad esempio un pulsante.
• Il parametro caretSize modifica le dimensioni della freccia della descrizione comando.

Risultato

Questo esempio produce il seguente output:

Figura 4. Un tooltip avanzato personalizzato con un'azione di chiusura ancorata a un'icona della fotocamera.

Risorse aggiuntive

• Material Design: tooltip