Botões de ícone

Os botões de ícone mostram ações que os usuários podem realizar. Os botões de ícone precisam usar um ícone com um significado claro e, normalmente, representam ações comuns ou usadas com frequência.

Há dois tipos de botões de ícone:

  • Padrão: esses botões podem abrir outros elementos, como um menu ou uma pesquisa.
  • Alternância: esses botões podem representar ações binárias que podem ser ativadas ou desativadas, como "favorito" ou "marcador".
Cinco botões com ícones diferentes, como configurações e muito mais. Alguns são preenchidos, indicando seleção, e outros são contornados.
Figura 1. Botões de ícone. Alguns estão preenchidos (indicando seleção) e outros estão contornados.

Superfície da API

Use o elemento combinável IconButton para implementar botões de ícone padrão e IconToggleButton para um botão que alterna entre os estados selecionado e não selecionado. Para criar estilos visuais diferentes, como preenchido, tonal preenchido ou contornado, use FilledIconButton, FilledTonalIconButton e OutlinedIconButton ou as contrapartes alternáveis FilledIconToggleButton, FilledTonalIconToggleButton e OutlinedIconToggleButton.

Os principais parâmetros para IconButton incluem:

  • onClick: uma função lambda que é executada quando o usuário toca no botão de ícone.
  • enabled: um booleano que controla o estado de ativação do botão. Quando false, o botão não responde à entrada do usuário.
  • content: o conteúdo combinável dentro do botão, normalmente um Icon.

Os principais parâmetros para IconToggleButton incluem:

  • checked: um booleano que controla o estado selecionado do botão.
  • onCheckedChange: uma função lambda que é executada quando o usuário toca no botão, fornecendo o novo estado marcado.
  • enabled: um booleano que controla o estado de ativação do botão. Quando false, o botão não responde à entrada do usuário.

Exemplo básico: botão de ícone de alternância

Os botões do ícone de ativação permitem que uma única opção seja selecionada ou desmarcada, como adicionar ou remover algo dos favoritos. IconToggleButton e as variantes dele foram projetados para essa finalidade.

O exemplo a seguir mostra como implementar um botão de ícone de alternância que muda de aparência dependendo se está selecionado ou não, gerenciando o estado com IconButton:

@Preview
@Composable
fun ToggleIconButtonExample() {
    // isToggled initial value should be read from a view model or persistent storage.
    var isToggled by rememberSaveable { mutableStateOf(false) }

    IconButton(
        onClick = { isToggled = !isToggled }
    ) {
        Icon(
            painter = if (isToggled) painterResource(R.drawable.favorite_filled) else painterResource(R.drawable.favorite),
            contentDescription = if (isToggled) "Selected icon button" else "Unselected icon button."
        )
    }
}

Pontos principais sobre o código

  • O elemento combinável ToggleIconButtonExample define um IconButton que pode ser alternado.
    • mutableStateOf(false) cria um objeto MutableState que contém um valor booleano, inicialmente false. Isso faz com que isToggled seja um detentor de estado, ou seja, o Compose recompõe a interface sempre que o valor muda.
    • rememberSaveable garante que o estado de isToggled persista em mudanças de configuração, como a rotação da tela.
  • A lambda onClick do IconButton define o comportamento do botão quando clicado, alternando o estado entre true e false.
  • O parâmetro painter do elemento combinável Icon carrega condicionalmente um painterResource diferente com base no estado isToggled. Isso muda a aparência visual do ícone.
    • Se isToggled for true, ele vai carregar o drawable de coração preenchido.
    • Se isToggled for false, ele vai carregar o drawable de coração contornado.
  • O contentDescription do Icon também é atualizado com base no estado do isToggled para fornecer informações de acessibilidade adequadas.

Resultado

A imagem abaixo mostra o botão de alternância do ícone do snippet anterior no estado selecionado:

Figura 2. Um botão de alternância "favorito" no estado selecionado.

Exemplo avançado: ações repetidas ao pressionar

Nesta seção, mostramos como criar botões de ícone que acionam continuamente uma ação enquanto o usuário os toca e pressiona, em vez de acionar apenas uma vez por clique.

@Composable
fun MomentaryIconButton(
    unselectedImage: Int,
    selectedImage: Int,
    contentDescription: String,
    modifier: Modifier = Modifier,
    stepDelay: Long = 100L, // Minimum value is 1L milliseconds.
    onClick: () -> Unit
) {
    val interactionSource = remember { MutableInteractionSource() }
    val isPressed by interactionSource.collectIsPressedAsState()
    val pressedListener by rememberUpdatedState(onClick)

    LaunchedEffect(isPressed) {
        while (isPressed) {
            delay(stepDelay.coerceIn(1L, Long.MAX_VALUE))
            pressedListener()
        }
    }

    IconButton(
        modifier = modifier,
        onClick = onClick,
        interactionSource = interactionSource
    ) {
        Icon(
            painter = if (isPressed) painterResource(id = selectedImage) else painterResource(id = unselectedImage),
            contentDescription = contentDescription,
        )
    }
}

Pontos principais sobre o código

  • MomentaryIconButton usa um unselectedImage: Int, o ID do recurso drawable para o ícone quando o botão não é pressionado, e selectedImage: Int, o ID do recurso drawable para o ícone quando o botão é pressionado.
  • Ele usa um interactionSource para rastrear especificamente as interações de "pressionar" do usuário.
  • isPressed será verdadeiro quando o botão estiver sendo pressionado e falso caso contrário. Quando isPressed é true, o LaunchedEffect entra em um loop.
    • Dentro desse loop, ele usa um delay (com stepDelay) para criar pausas entre as ações de acionamento. coerceIn garante que o atraso seja de pelo menos 1 ms para evitar loops infinitos.
    • O pressedListener é invocado após cada atraso no loop. Isso faz com que a ação seja repetida.
  • O pressedListener usa rememberUpdatedState para garantir que o lambda onClick (a ação a ser realizada) seja sempre o mais atualizado da composição mais recente.
  • O Icon muda a imagem exibida com base no fato de o botão estar pressionado ou não.
    • Se isPressed for verdadeiro, o selectedImage será mostrado.
    • Caso contrário, o unselectedImage será exibido.

Em seguida, use esse MomentaryIconButton em um exemplo. O snippet a seguir demonstra dois botões de ícone que controlam um contador:

@Preview()
@Composable
fun MomentaryIconButtonExample() {
    var pressedCount by remember { mutableIntStateOf(0) }

    Row(
        modifier = Modifier.fillMaxWidth(),
        verticalAlignment = Alignment.CenterVertically
    ) {
        MomentaryIconButton(
            unselectedImage = R.drawable.fast_rewind,
            selectedImage = R.drawable.fast_rewind_filled,
            stepDelay = 100L,
            onClick = { pressedCount -= 1 },
            contentDescription = "Decrease count button"
        )
        Spacer(modifier = Modifier)
        Text("advanced by $pressedCount frames")
        Spacer(modifier = Modifier)
        MomentaryIconButton(
            unselectedImage = R.drawable.fast_forward,
            selectedImage = R.drawable.fast_forward_filled,
            contentDescription = "Increase count button",
            stepDelay = 100L,
            onClick = { pressedCount += 1 }
        )
    }
}

Pontos principais sobre o código

  • O elemento combinável MomentaryIconButtonExample mostra um Row que contém duas instâncias de MomentaryIconButton e um elemento combinável Text para criar uma interface que incrementa e decrementa um contador.
  • Ele mantém uma variável de estado mutável pressedCount usando remember e mutableIntStateOf, inicializada como 0. Quando pressedCount muda, todos os elementos combináveis que o observam (como o elemento combinável Text) são recompostos para refletir o novo valor.
  • O primeiro MomentaryIconButton diminui pressedCount quando clicado ou pressionado.
  • O segundo MomentaryIconButton aumenta o pressedCount quando clicado ou pressionado.
  • Os dois botões usam um stepDelay de 100 milissegundos, o que significa que a ação onClick é repetida a cada 100 ms enquanto um botão é pressionado.

Resultado

O vídeo a seguir mostra a interface com os botões de ícone e o contador:

Figura 3. Uma interface de contador com dois botões de ícone (mais e menos) que aumentam e diminuem o contador.

Atualização do M3 Expressive

Com a atualização do M3 Expressive, os botões de ícone oferecem mais opções de tamanho, canto e largura, além de poderem mudar de forma quando pressionados ou selecionados. Quando colocados em grupos de botões padrão, os botões de ícone também interagem com os botões vizinhos quando pressionados.

Forma animada

Os botões de ícone podem animar a forma quando pressionados, e os botões de alternância podem animar a forma com base no estado marcado. Para ativar a animação de formas, transmita IconButtonDefaults.shapes() ou IconButtonDefaults.toggleableShapes() para o parâmetro shapes de IconButton ou IconToggleButton.

Botões de ícone

Estados do botão de ícone
Figura 4. Animação de formato de botão de ícone em formas redondas e quadradas.

O snippet abaixo demonstra como implementar um botão de ícone que anima a forma quando pressionado:

@Composable
fun IconButtonWithAnimatedShapeSample() {
    IconButton(
        onClick = { /* doSomething() */ },
        shapes = IconButtonDefaults.shapes(),
    ) {
        Icon(painter = rememberVectorPainter(AppIcons.LockFilled), contentDescription = "Localized description")
    }
}

Botões de ícone de alternância

Estados do botão de ícone de alternância
Figura 5. Animação de forma do botão de ícone de alternância nos estados não selecionado e selecionado.

O snippet a seguir demonstra como implementar um botão de ícone de alternância que anima a forma com base no estado marcado:

@Composable
fun IconToggleButtonWithAnimatedShapeSample() {
    var checked by remember { mutableStateOf(false) }
    IconToggleButton(
        checked = checked,
        onCheckedChange = { checked = it },
        shapes = IconButtonDefaults.toggleableShapes(),
    ) {
        if (checked) {
            Icon(painter = rememberVectorPainter(AppIcons.LockFilled), contentDescription = "Localized description")
        } else {
            Icon(painter = rememberVectorPainter(AppIcons.Lock), contentDescription = "Localized description")
        }
    }
}

Variantes de tamanho, largura e formato

Os botões de ícone estão disponíveis em formatos redondos e quadrados, cinco tamanhos e três larguras.

Exemplos de tamanhos, formas e larguras de botões de ícone.
Figura 6. Os recursos expressivos incluem cinco tamanhos, duas formas e três larguras.

Para mais informações sobre as atualizações do M3 Expressive para botões de ícone, consulte as diretrizes de botões de ícone do Material Design 3.

Há cinco variantes de tamanho de botão de ícone: extra pequeno, pequeno, médio, grande e extra grande. Cada tamanho é compatível com três opções de largura: uniforme (padrão), estreita e larga.

Cinco linhas e três colunas de botões de ícone mostrando um ícone de coração. Cada linha aumenta de tamanho, e as três colunas variam em largura: uniforme, estreita e larga.
Figura 7. Botões de ícone mostrando cinco tamanhos e três opções de largura: uniforme, estreita e larga.

Os botões de ícone estão disponíveis em variantes de cantos arredondados ou quadrados, e os botões de ícone de alternância mudam de forma quando pressionados ou selecionados.

Duas linhas de cinco botões de ícone com um ícone de coração, aumentando de tamanho da esquerda para a direita. A linha de cima tem cantos arredondados, e a de baixo tem cantos quadrados.
Figura 8. Botões de ícone disponíveis em variantes de canto redondo ou quadrado.

Para orientações sobre como escolher entre as variantes de canto, consulte as diretrizes de botões de ícone do Material Design 3 (link em inglês).

Outros recursos