Descrizione comando

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

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

Piattaforma API

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

• positionProvider: posiziona la descrizione comando rispetto al contenuto 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 il contenuto 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 descrivendo il valore di una funzionalità. Le descrizioni comandi 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 dell'elemento 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 dell'interfaccia utente. 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 una descrizione comando con il testo "Aggiungi ai preferiti".
  • TooltipDefaults.rememberPlainTooltipPositionProvider() fornisce il posizionamento predefinito per le descrizioni comandi semplici.
  • tooltip è una funzione lambda che definisce il contenuto della descrizione comando utilizzando il PlainTooltip composable.
  • Text(plainTooltipText) visualizza il testo all'interno della descrizione comando.
  • tooltipState controlla lo stato della descrizione comando.
• IconButton crea un pulsante cliccabile con un'icona.
  • Icon(...) visualizza 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:
  • Passando il mouse sopra l'icona con un cursore.
  • Premendo 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 ulteriore contesto 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 degli utenti e aggiorna TooltipState di conseguenza. Quando TooltipState indica che la descrizione comando deve essere visualizzata, viene eseguita la lambda della descrizione comando e TooltipBox visualizza RichTooltip. TooltipBox funge da ancoraggio e contenitore sia per il contenuto sia per la descrizione comando.
  • In questo caso, il contenuto è un componente IconButton, che fornisce il comportamento di azione toccabile. Quando viene premuta a lungo (sui dispositivi touch) o quando viene passato il mouse sopra (come con il puntatore del mouse) in qualsiasi punto del contenuto di TooltipBox, la descrizione comando viene visualizzata per mostrare ulteriori informazioni.
• Il composable RichTooltip definisce il contenuto della descrizione comando, inclusi il titolo e il testo del corpo. TooltipDefaults.rememberRichTooltipPositionProvider() fornisce informazioni sul posizionamento per le descrizioni comandi avanzate.

Risultato

Questo esempio produce una descrizione comando avanzata con un titolo collegato 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 del testo personalizzato visualizzato sopra un pulsante con icona della 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)
                        }
                    }
                },
            ) {
                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 visualizza una descrizione comando con un titolo e un'azione di chiusura.
• Quando viene attivata, tramite una pressione prolungata o passando il mouse sopra il contenuto di TooltipBox con il puntatore del mouse, la descrizione comando viene visualizzata per circa un secondo. Puoi chiudere questa descrizione comando toccando un altro punto dello schermo o utilizzando il pulsante di azione 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 sia 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 comandi