Descrizione comando

Utilizza le descrizioni comando per aggiungere contesto a un pulsante o a un altro elemento dell'interfaccia utente. Esistono due tipi di descrizioni comando:

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

Figura 1. Una descrizione comando semplice (1) e una descrizione comando avanzata (2).

Superficie API

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

• positionProvider: Posiziona la descrizione comando rispetto al contenuto di ancoraggio. In genere utilizzi un fornitore di posizioni predefinito da TooltipDefaults oppure puoi fornire il tuo se hai bisogno di una logica di posizionamento personalizzata.
• tooltip: il composable che contiene i contenuti della descrizione comando. In genere, utilizzi i composable PlainTooltip o RichTooltip.
  • Utilizza PlainTooltip per descrivere elementi o azioni dei pulsanti con icone.
  • Utilizza RichTooltip per fornire maggiori dettagli, ad esempio descrivere il valore di una funzionalità. Le descrizioni comando avanzate possono includere un titolo, un link e pulsanti facoltativi.
• state: il titolare dello stato che contiene la logica e lo stato degli elementi dell'interfaccia utente per questa descrizione comando.
• content: il contenuto componibile a cui è ancorata la descrizione comando.

Visualizzare una descrizione comando semplice

Utilizza una descrizione comando semplice per descrivere brevemente un elemento UI. Questo snippet di codice mostra una descrizione comando semplice sopra un pulsante con icona, etichettato "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(
                imageVector = Icons.Filled.Favorite,
                contentDescription = "Add to favorites"
            )
        }
    }
}
Tooltips.kt

Punti chiave del codice

• TooltipBox genera una descrizione comando con il testo "Aggiungi ai preferiti".
  • TooltipDefaults.rememberPlainTooltipPositionProvider() fornisce il posizionamento predefinito per le descrizioni comando semplici.
  • tooltip è una funzione lambda che definisce il contenuto della descrizione comando utilizzando il composable 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 la descrizione comando con il testo "Aggiungi ai preferiti". A seconda del dispositivo, gli utenti possono attivare la descrizione comando nei seguenti modi:
  • Passaggio del mouse sopra l'icona con un cursore
  • Premere a lungo l'icona su un dispositivo mobile

Risultato

Questo esempio produce una descrizione comando semplice sopra un'icona:

Figura 2. Una semplice descrizione comando che viene visualizzata quando un utente passa il mouse sopra l'icona a forma di cuore o la preme a lungo.

Visualizzare una descrizione comando avanzata

Utilizza una descrizione comando avanzata per fornire ulteriore contesto su un elemento UI. Questo esempio crea una descrizione comando avanzata 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(
                imageVector = Icons.Filled.Info,
                contentDescription = "Show more information"
            )
        }
    }
}
Tooltips.kt

Punti chiave del codice

• TooltipBox gestisce i listener di eventi per le interazioni degli utenti e aggiorna TooltipState di conseguenza. Quando TooltipState indica che deve essere mostrata la descrizione comando, viene eseguita la lambda della descrizione comando e TooltipBox mostra RichTooltip. Il TooltipBox funge da ancora e contenitore sia per i contenuti sia per la descrizione comando.
  • In questo caso, i contenuti sono un componente IconButton, che fornisce il comportamento dell'azione toccabile. Quando viene premuto a lungo (sui dispositivi touch) o quando viene passato sopra (come con il puntatore del mouse) in qualsiasi punto dei contenuti di TooltipBox, viene visualizzata la descrizione comando per mostrare ulteriori informazioni.
• Il composable RichTooltip definisce i contenuti della descrizione comando, inclusi il titolo e il corpo del testo. TooltipDefaults.rememberRichTooltipPositionProvider() fornisce informazioni sul posizionamento per le descrizioni comando avanzate.

Risultato

Questo esempio produce una descrizione avanzata con un titolo collegato a un'icona informativa:

Figura 3. Una descrizione comando avanzata con un titolo e un'icona informativa.

Personalizzare una descrizione comando avanzata

Questo snippet di codice mostra una descrizione comando avanzata con un titolo, azioni personalizzate e un cursore personalizzato (freccia) visualizzato sopra un pulsante con l'icona di una videocamera:

@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

Punti chiave del codice

• Un RichToolTip mostra una descrizione comando con un titolo e un'azione di chiusura.
• Quando viene attivata, tramite una pressione prolungata o passando il puntatore del mouse sopra i contenuti ToolTipBox, la descrizione comando viene visualizzata per circa un secondo. Puoi chiudere questo suggerimento toccando un altro punto dello schermo o utilizzando il pulsante di chiusura.
• Quando viene eseguita l'azione di chiusura, il sistema avvia una coroutine per chiamare tooltipState.dismiss. In questo modo si verifica che l'esecuzione dell'azione non venga bloccata durante la visualizzazione della descrizione comando.
• onClick = coroutineScope.launch { tooltipState.show() } } avvia una coroutine per mostrare manualmente la descrizione comando utilizzando tooltipState.show.
• Il parametro action consente di aggiungere elementi interattivi a una descrizione comando, ad esempio un pulsante.
• Il parametro caretSize modifica le dimensioni della freccia della descrizione comando.

Risultato

Questo esempio produce quanto segue:

Figura 4. Una descrizione comando avanzata personalizzata con un'azione di chiusura ancorata a un'icona della videocamera.

Risorse aggiuntive

• Material Design: descrizioni comando