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".
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. Quandofalse, o botão não responde à entrada do usuário.content: o conteúdo combinável dentro do botão, normalmente umIcon.
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. Quandofalse, 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
ToggleIconButtonExampledefine umIconButtonque pode ser alternado.mutableStateOf(false)cria um objetoMutableStateque contém um valor booleano, inicialmentefalse. Isso faz com queisToggledseja um detentor de estado, ou seja, o Compose recompõe a interface sempre que o valor muda.rememberSaveablegarante que o estado deisToggledpersista em mudanças de configuração, como a rotação da tela.
- A lambda
onClickdoIconButtondefine o comportamento do botão quando clicado, alternando o estado entretrueefalse. - O parâmetro
painterdo elemento combinávelIconcarrega condicionalmente umpainterResourcediferente com base no estadoisToggled. Isso muda a aparência visual do ícone.- Se
isToggledfortrue, ele vai carregar o drawable de coração preenchido. - Se
isToggledforfalse, ele vai carregar o drawable de coração contornado.
- Se
- O
contentDescriptiondoIcontambém é atualizado com base no estado doisToggledpara 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:
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
MomentaryIconButtonusa umunselectedImage: Int, o ID do recurso drawable para o ícone quando o botão não é pressionado, eselectedImage: Int, o ID do recurso drawable para o ícone quando o botão é pressionado.- Ele usa um
interactionSourcepara rastrear especificamente as interações de "pressionar" do usuário. isPressedserá verdadeiro quando o botão estiver sendo pressionado e falso caso contrário. QuandoisPressedétrue, oLaunchedEffectentra em um loop.- Dentro desse loop, ele usa um
delay(comstepDelay) para criar pausas entre as ações de acionamento.coerceIngarante 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.
- Dentro desse loop, ele usa um
- O
pressedListenerusarememberUpdatedStatepara garantir que o lambdaonClick(a ação a ser realizada) seja sempre o mais atualizado da composição mais recente. - O
Iconmuda a imagem exibida com base no fato de o botão estar pressionado ou não.- Se
isPressedfor verdadeiro, oselectedImageserá mostrado. - Caso contrário, o
unselectedImageserá exibido.
- Se
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
MomentaryIconButtonExamplemostra umRowque contém duas instâncias deMomentaryIconButtone um elemento combinávelTextpara criar uma interface que incrementa e decrementa um contador. - Ele mantém uma variável de estado mutável
pressedCountusandorememberemutableIntStateOf, inicializada como 0. QuandopressedCountmuda, todos os elementos combináveis que o observam (como o elemento combinávelText) são recompostos para refletir o novo valor. - O primeiro
MomentaryIconButtondiminuipressedCountquando clicado ou pressionado. - O segundo
MomentaryIconButtonaumenta opressedCountquando clicado ou pressionado. - Os dois botões usam um
stepDelayde 100 milissegundos, o que significa que a açãoonClické 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:
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
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
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.
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.
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.
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).