Dica

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Use tooltips para adicionar contexto a um botão ou outro elemento da interface. Há dois tipos de dicas:

• Dicas simples: descrevem elementos ou ações de botões de ícone.
• Dicas detalhadas: forneça mais detalhes, como descrever o valor de um recurso. Também pode incluir um título, link e botões opcionais.

Superfície da API

Você pode usar o elemento combinável TooltipBox para implementar dicas de ferramentas no app. Controle a aparência de TooltipBox com estes parâmetros principais:

• positionProvider: posiciona a dica de ferramenta em relação ao conteúdo de âncora. Normalmente, você usa um provedor de posição padrão do TooltipDefaults ou pode fornecer o seu próprio se precisar de uma lógica de posicionamento personalizada.
• tooltip: o elemento combinável que contém o conteúdo da dica. Normalmente, você usa os elementos combináveis PlainTooltip ou RichTooltip.
  • Use PlainTooltip para descrever elementos ou ações de botões de ícone.
  • Use RichTooltip para fornecer mais detalhes, como descrever o valor de um recurso. As dicas avançadas podem incluir um título, um link e botões opcionais.
• state: o detentor de estado que contém a lógica da interface e o estado do elemento para essa dica.
• content: o conteúdo combinável ao qual a dica de ferramenta está ancorada.

Mostrar uma dica simples

Use uma dica simples para descrever um elemento da interface brevemente. Este snippet de código mostra uma dica simples sobre um botão de ícone, com a etiqueta "Adicionar aos favoritos":

@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

Pontos principais sobre o código

• TooltipBox gera uma dica simples com o texto "Adicionar aos favoritos".
  • TooltipDefaults.rememberPlainTooltipPositionProvider() fornece a posição padrão para dicas simples.
  • tooltip é uma função lambda que define o conteúdo da dica usando o elemento combinável PlainTooltip.
  • Text(plainTooltipText) exibe o texto na dica.
  • tooltipState controla o estado da dica.
• IconButton cria um botão clicável com um ícone.
  • Icon(...) mostra um ícone de coração no botão.
  • Quando um usuário interage com o IconButton, a dica de ferramenta é mostrada com o texto "Adicionar aos favoritos". Dependendo do dispositivo, os usuários podem acionar a dica de ferramenta das seguintes maneiras:
  • Passar o cursor sobre o ícone
  • Toque no ícone e mantenha pressionado em um dispositivo móvel

Resultado

Este exemplo produz uma dica simples sobre um ícone:

Mostrar uma dica detalhada

Use uma dica interativa para fornecer mais contexto sobre um elemento da interface. Este exemplo cria uma dica de ferramenta avançada com várias linhas e um título ancorado a um 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

Pontos principais sobre o código

• TooltipBox processa os listeners de eventos para interações do usuário e atualiza TooltipState de acordo. Quando TooltipState indica que a dica deve ser mostrada, a lambda da dica é executada e o RichTooltip é exibido. O TooltipBox atua como âncora e contêiner para o conteúdo e a dica.
  • Nesse caso, o conteúdo é um componente IconButton, que fornece o comportamento de ação acionável. Quando pressionado por muito tempo (em dispositivos com tela touch) ou passado (como com o ponteiro do mouse) sobre qualquer lugar do conteúdo de TooltipBox, a dica aparece para mostrar mais informações.
• O elemento combinável RichTooltip define o conteúdo da dica, incluindo o título e o texto do corpo. TooltipDefaults.rememberRichTooltipPositionProvider() fornece informações de posicionamento para dicas de ferramentas detalhadas.

Resultado

Este exemplo produz uma dica de ferramenta avançada com um título anexado a um ícone de informações:

Personalizar uma dica de ferramentas avançada

Este snippet de código mostra uma dica interativa com um título, ações personalizadas e um careta (seta) personalizado exibido na parte de cima de um botão de ícone de câmera:

@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

Pontos principais sobre o código

• Um RichToolTip mostra uma dica com um título e uma ação de dispensa.
• Quando ativada, seja por um toque longo ou passando o cursor sobre o conteúdo ToolTipBox com o ponteiro do mouse, a dica de ferramenta aparece por cerca de um segundo. Para dispensar essa dica, toque em outro lugar da tela ou use o botão de ação de dispensa.
• Quando a ação de dispensar é executada, uma corrotina é iniciada para chamar tooltipState.dismiss. Isso garante que a execução da ação não seja bloqueada enquanto a dica de ferramenta é mostrada.
• onClick = coroutineScope.launch { tooltipState.show() } } inicia uma corrotina para mostrar manualmente a dica de ferramenta usando tooltipState.show.
• O parâmetro action permite a adição de elementos interativos a uma tooltip, como um botão.
• O parâmetro caretSize modifica o tamanho da seta da dica.

Resultado

Este exemplo produz o seguinte:

Outros recursos

• Material Design: Dicas