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 gli elementi o le azioni dei pulsanti delle icone.
• Descrizioni comando avanzate: forniscono maggiori dettagli, ad esempio la descrizione del valore di una funzionalità. Possono includere anche un titolo, un link e pulsanti facoltativi.

Piattaforma 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 ai contenuti di ancoraggio. In genere utilizzi un provider di posizione 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 per descrivere il valore di una funzionalità. Le descrizioni comando avanzate possono includere un titolo, un link e pulsanti facoltativi.
• state: il contenitore di stato che contiene la logica dell'interfaccia utente e lo stato degli elementi per questa descrizione comando.
• content: il contenuto composable 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 sul codice

• TooltipBox genera un suggerimento 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 sull'icona con un cursore
  • Premere a lungo l'icona su un dispositivo mobile

Risultato

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

Visualizzare una descrizione comando avanzata

Utilizza una descrizione comando avanzata per fornire un contesto aggiuntivo su un elemento dell'interfaccia utente. Questo esempio crea una descrizione comando avanzata su più righe 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 sul codice

• TooltipBox gestisce i listener di eventi per le interazioni e gli aggiornamenti degli utenti TooltipState di conseguenza. Quando TooltipState indica che deve essere visualizzata la descrizione comando, viene eseguita la lambda della descrizione comando e TooltipBox visualizza RichTooltip. TooltipBox funge da ancora e contenitore sia per i contenuti sia per la descrizione comando.
  • In questo caso, il contenuto è un componente IconButton, che fornisce il comportamento di azione toccabile. Quando viene premuto a lungo (su dispositivi touch) o passato sopra (come con il puntatore del mouse) in qualsiasi punto del contenuto 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 comando avanzata con un titolo allegato a 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 (freccia) personalizzato visualizzato sopra un pulsante con l'icona di una 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(
                imageVector = Icons.Filled.Camera,
                contentDescription = "Open camera"
            )
        }
    }
}
Tooltips.kt

Punti chiave sul 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 TooltipBox contenuti, 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:

Risorse aggiuntive

• Material Design: Descrizioni comando