Descrizione comando

Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

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 con icone.
• Descrizioni comando dettagliate: forniscono ulteriori dettagli, ad esempio descrivono il valore di una funzionalità. Può includere anche un titolo, un link e pulsanti facoltativi.

API surface

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

• positionProvider: posiziona la descrizione comando in base ai contenuti dell'ancora. Generalmente, viene utilizzato un fornitore di posizione predefinito del 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, si utilizzano i composabili PlainTooltip o RichTooltip.
  • Utilizza PlainTooltip per descrivere elementi o azioni dei pulsanti con icone.
  • Utilizza RichTooltip per fornire ulteriori 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 detentore dello stato che contiene la logica dell'interfaccia utente e lo stato dell'elemento per questa descrizione comando.
• content: i contenuti composibili a cui è ancorata la descrizione comando.

Mostrare una descrizione comando semplice

Utilizza una semplice descrizione comando per descrivere brevemente un elemento dell'interfaccia utente. Questo snippet di codice mostra una semplice descrizione comando 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 semplice 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 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, viene visualizzata la descrizione comando con il testo "Aggiungi ai preferiti". A seconda del dispositivo, gli utenti possono attivare la descrizione comando nei seguenti modi:
  • Passare il mouse sopra l'icona con un cursore
  • Premere a lungo l'icona su un dispositivo mobile

Risultato

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

Mostrare una descrizione comando completa

Utilizza una descrizione comando completa per fornire ulteriore contesto su un elemento dell'interfaccia utente. 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 gli ascoltatori di eventi per le interazioni degli utenti e aggiornaTooltipState di conseguenza. Quando TooltipState indica che la descrizione comando deve essere visualizzata, viene eseguita la funzione lambda della descrizione comando e viene visualizzato RichTooltip. 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. Se premi a lungo (su dispositivi touch) o passi il mouse sopra (come con il cursore del mouse) un punto qualsiasi 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 testo del corpo. TooltipDefaults.rememberRichTooltipPositionProvider() fornisce informazioni sul posizionamento per le descrizioni comando avanzate.

Risultato

Questo esempio genera una descrizione comando avanzata con un titolo associato a un'icona informativa:

Personalizzare una descrizione comando completa

Questo snippet di codice mostra una descrizione comando completa con un titolo, azioni personalizzate e un cursore personalizzato (freccia) visualizzato sopra un pulsante con 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)
                        }
                    }
                },
                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, premendo a lungo o passando il mouse sopra i contenuti ToolTipBox viene visualizzata per circa un secondo. Puoi chiudere questa descrizione comando toccando un'altra parte dello schermo o utilizzando il pulsante di azione di chiusura.
• Quando viene eseguita l'azione di dismiss, viene lanciata una coroutine per chiamare tooltipState.dismiss. In questo modo, l'esecuzione dell'azione non viene bloccata mentre viene visualizzata la 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 всtooltip, 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