Os menus suspensos permitem que os usuários cliquem em um ícone, campo de texto ou outro componente e selecionem uma opção em uma lista em uma superfície temporária. Este guia descreve como criar menus básicos e mais complexos com divisores e ícones.
Superfície da API
Use os componentes DropdownMenu, DropdownMenuItem, IconButton e
ExposedDropdownMenuBox para implementar menus suspensos. Os
componentes DropdownMenu e DropdownMenuItem são usados para mostrar os itens
do menu, enquanto o IconButton ou outros componentes podem acionar a exibição do menu.
ExposedDropdownMenuBox é usado para criar um menu anexado a um campo de texto.
Os principais parâmetros do componente DropdownMenu incluem:
expanded: indica se o menu está visível.onDismissRequest: usado para processar o fechamento do menu.content: o conteúdo combinável do menu, que normalmente contém elementos combináveisDropdownMenuItem.
Os principais parâmetros de DropdownMenuItem incluem:
text: define o conteúdo exibido no item de menu.onClick: callback para processar a interação com o item no menu.
Criar um menu suspenso básico
O snippet a seguir demonstra uma implementação mínima de DropdownMenu:
@Composable fun MinimalDropdownMenu() { var expanded by remember { mutableStateOf(false) } Box( modifier = Modifier .padding(16.dp) ) { IconButton(onClick = { expanded = !expanded }) { Icon(painter = rememberVectorPainter(AppIcons.MoreVert), contentDescription = "More options") } DropdownMenu( expanded = expanded, onDismissRequest = { expanded = false } ) { DropdownMenuItem( text = { Text("Option 1") }, onClick = { /* Do something... */ } ) DropdownMenuItem( text = { Text("Option 2") }, onClick = { /* Do something... */ } ) } } }
Pontos principais sobre o código
- Define um
DropdownMenubásico que contém dois itens de menu. - O parâmetro
expandedcontrola a visibilidade do menu como expandido ou recolhido. - O parâmetro
onDismissRequestdefine um callback que é executado quando o usuário fecha o menu. - O elemento combinável
DropdownMenuItemrepresenta itens selecionáveis no menu suspenso. - Um
IconButtonaciona a expansão e o recolhimento do menu.
Resultado
Criar um menu suspenso mais longo
DropdownMenu é rolável por padrão se todos os itens de menu não puderem ser mostrados
de uma vez. O snippet a seguir cria um menu suspenso mais longo e rolável:
@Composable fun LongBasicDropdownMenu() { var expanded by remember { mutableStateOf(false) } // Placeholder list of 100 strings for demonstration val menuItemData = List(100) { "Option ${it + 1}" } Box( modifier = Modifier .padding(16.dp) ) { IconButton(onClick = { expanded = !expanded }) { Icon(painter = rememberVectorPainter(AppIcons.MoreVert), contentDescription = "More options") } DropdownMenu( expanded = expanded, onDismissRequest = { expanded = false } ) { menuItemData.forEach { option -> DropdownMenuItem( text = { Text(option) }, onClick = { /* Do something... */ } ) } } } }
Pontos principais sobre o código
- O
DropdownMenué rolável quando a altura total do conteúdo excede o espaço disponível. Esse código cria umDropdownMenurolável que mostra 100 itens de marcador de posição. - O loop
forEachgera dinamicamente elementos combináveisDropdownMenuItem. Os itens não são criados de forma lenta, o que significa que todos os 100 itens suspensos são criados e existem na composição. - O
IconButtonaciona a expansão e o recolhimento doDropdownMenuquando clicado. - A lambda
onClickem cadaDropdownMenuItempermite definir a ação realizada quando o usuário seleciona um item de menu.
Resultado
O snippet de código anterior produz o seguinte menu rolável:
Criar um menu suspenso mais longo com divisores
O snippet a seguir mostra uma implementação mais avançada de um menu suspenso. Neste snippet, ícones iniciais e finais são adicionados aos itens de menu, e divisores separam grupos de itens de menu.
@Composable fun DropdownMenuWithDetails() { var expanded by remember { mutableStateOf(false) } Box( modifier = Modifier .fillMaxWidth() .padding(16.dp) ) { IconButton(onClick = { expanded = !expanded }) { Icon(painter = rememberVectorPainter(AppIcons.MoreVert), contentDescription = "More options") } DropdownMenu( expanded = expanded, onDismissRequest = { expanded = false } ) { // First section DropdownMenuItem( text = { Text("Profile") }, leadingIcon = { Icon(painter = rememberVectorPainter(AppIcons.Person), contentDescription = null) }, onClick = { /* Do something... */ } ) DropdownMenuItem( text = { Text("Settings") }, leadingIcon = { Icon(painter = rememberVectorPainter(AppIcons.Settings), contentDescription = null) }, onClick = { /* Do something... */ } ) HorizontalDivider() // Second section DropdownMenuItem( text = { Text("Send Feedback") }, leadingIcon = { Icon(painter = rememberVectorPainter(AppIcons.Feedback), contentDescription = null) }, trailingIcon = { Icon(painter = rememberVectorPainter(AppIcons.Send), contentDescription = null) }, onClick = { /* Do something... */ } ) HorizontalDivider() // Third section DropdownMenuItem( text = { Text("About") }, leadingIcon = { Icon(painter = rememberVectorPainter(AppIcons.Info), contentDescription = null) }, onClick = { /* Do something... */ } ) DropdownMenuItem( text = { Text("Help") }, leadingIcon = { Icon(painter = rememberVectorPainter(AppIcons.Help), contentDescription = null) }, trailingIcon = { Icon(painter = rememberVectorPainter(AppIcons.OpenInNew), contentDescription = null) }, onClick = { /* Do something... */ } ) } } }
Esse código define um DropdownMenu em um Box.
Pontos principais sobre o código
- Os parâmetros
leadingIconetrailingIconadicionam ícones ao início e ao fim de umDropdownMenuItem. - Um
IconButtonaciona a expansão do menu. - O
DropdownMenucontém vários elementos combináveisDropdownMenuItem, cada um representando uma ação selecionável. - Os elementos combináveis
HorizontalDividerinserem uma linha horizontal para separar grupos de itens de menu.
Resultado
O snippet anterior produz um menu suspenso com ícones e divisores:
Atualização do M3 Expressive
O Material 3 Expressive apresenta DropdownMenuPopup, DropdownMenuGroup e
CheckableDropdownMenuItem como opções adicionais ao lado de DropdownMenu e
DropdownMenuItem para criar menus segmentados com itens agrupados, lacunas e
estados de verificação.
Para mais informações sobre as atualizações do M3 Expressive para menus, consulte as diretrizes de menus do Material Design 3.
Cardápios segmentados
Os menus segmentados agrupam ações relacionadas em seções visuais distintas separadas por
lacunas ou divisores. O snippet a seguir demonstra como implementar um
menu suspenso segmentado com DropdownMenuPopup, DropdownMenuGroup e
CheckableDropdownMenuItem:
@OptIn(ExperimentalMaterial3Api::class) @Composable fun GroupedMenuSample() { val groupInteractionSource = remember { MutableInteractionSource() } var expanded by remember { mutableStateOf(false) } val groupLabels = listOf("Modification", "Navigation") val groupItemLabels = listOf(listOf("Edit", "Settings"), listOf("Home", "More Options")) val groupItemLeadingIcons = listOf(listOf(AppIcons.Edit, AppIcons.Settings), listOf(null, AppIcons.Info)) val groupItemCheckedLeadingIcons = listOf( listOf(AppIcons.EditFilled, AppIcons.SettingsFilled), listOf(AppIcons.Check, AppIcons.InfoFilled), ) val groupItemTrailingIcons: List<List<ImageVector?>> = listOf(listOf(null, null), listOf(AppIcons.Home, AppIcons.MoreVert)) val groupItemCheckedTrailingIcons: List<List<ImageVector?>> = listOf(listOf(null, null), listOf(AppIcons.HomeFilled, AppIcons.MoreVert)) val groupItemSupportingText: List<List<String?>> = listOf(listOf("Edit mode", null), listOf(null, "Opens menu")) val checked = remember { listOf(mutableStateListOf(false, false), mutableStateListOf(false, false)) } Box(modifier = Modifier.fillMaxSize().wrapContentSize(Alignment.TopStart)) { // Icon button should have a tooltip associated with it for a11y. TooltipBox( positionProvider = TooltipDefaults.rememberTooltipPositionProvider(TooltipAnchorPosition.Above), tooltip = { PlainTooltip { Text("Localized description") } }, state = rememberTooltipState(), ) { IconButton(onClick = { expanded = true }) { Icon(painter = rememberVectorPainter(AppIcons.MoreVert), contentDescription = "Localized description") } } DropdownMenuPopup(expanded = expanded, onDismissRequest = { expanded = false }) { val groupCount = groupLabels.size groupLabels.fastForEachIndexed { groupIndex, label -> DropdownMenuGroup( shapes = MenuDefaults.groupShape(groupIndex, groupCount), interactionSource = groupInteractionSource, ) { MenuDefaults.DropdownMenuGroupLabel { Text(label) } HorizontalDivider(modifier = Modifier.padding(MenuDefaults.HorizontalDividerPadding)) val groupItemCount = groupItemLabels[groupIndex].size groupItemLabels[groupIndex].fastForEachIndexed { itemIndex, itemLabel -> CheckableDropdownMenuItem( text = { Text(itemLabel) }, supportingText = groupItemSupportingText[groupIndex][itemIndex]?.let { supportingText -> { Text(supportingText) } }, shapes = MenuDefaults.itemShape(itemIndex, groupItemCount), leadingIcon = groupItemLeadingIcons[groupIndex][itemIndex]?.let { iconData -> { Icon( painter = rememberVectorPainter(iconData), modifier = Modifier.size(MenuDefaults.LeadingIconSize), contentDescription = null, ) } }, checkedLeadingIcon = { Icon( painter = rememberVectorPainter(groupItemCheckedLeadingIcons[groupIndex][itemIndex]), modifier = Modifier.size(MenuDefaults.LeadingIconSize), contentDescription = null, ) }, trailingContent = if (checked[groupIndex][itemIndex]) { groupItemCheckedTrailingIcons[groupIndex][itemIndex]?.let { iconData -> { Icon( painter = rememberVectorPainter(iconData), modifier = Modifier.size(MenuDefaults.TrailingIconSize), contentDescription = null, ) } } } else { groupItemTrailingIcons[groupIndex][itemIndex]?.let { iconData -> { Icon( painter = rememberVectorPainter(iconData), modifier = Modifier.size(MenuDefaults.TrailingIconSize), contentDescription = null, ) } } }, checked = checked[groupIndex][itemIndex], onCheckedChange = { checked[groupIndex][itemIndex] = it }, ) } } if (groupIndex != groupCount - 1) { Spacer(Modifier.height(MenuDefaults.GroupSpacing)) } } if (checked.last().last()) { DropdownMenuButtonGroup() } } } } @Composable private fun DropdownMenuButtonGroup() { ButtonGroup( overflowIndicator = { menuState -> ButtonGroupDefaults.OverflowIndicator(menuState) }, modifier = Modifier.fillMaxWidth(), horizontalArrangement = Arrangement.spacedBy(2.dp, Alignment.CenterHorizontally), ) { customItem( buttonGroupContent = { FilledIconButton( onClick = {}, colors = IconButtonDefaults.filledIconButtonColors( containerColor = MenuDefaults.groupStandardContainerColor ), ) { Icon(painter = rememberVectorPainter(AppIcons.ThumbUp), contentDescription = "Localized description") } }, menuContent = { DropdownMenuItem( leadingIcon = { Icon(painter = rememberVectorPainter(AppIcons.ThumbUp), contentDescription = null) }, text = { Text("Thumbs up") }, onClick = {}, ) }, ) customItem( buttonGroupContent = { FilledIconButton( onClick = {}, colors = IconButtonDefaults.filledIconButtonColors( containerColor = MenuDefaults.groupStandardContainerColor ), ) { Icon(painter = rememberVectorPainter(AppIcons.ThumbDown), contentDescription = "Localized description") } }, menuContent = { DropdownMenuItem( leadingIcon = { Icon(painter = rememberVectorPainter(AppIcons.ThumbDown), contentDescription = null) }, text = { Text("Thumbs down") }, onClick = {}, ) }, ) customItem( buttonGroupContent = { FilledIconButton( onClick = {}, colors = IconButtonDefaults.filledIconButtonColors( containerColor = MenuDefaults.groupStandardContainerColor ), ) { Icon(painter = rememberVectorPainter(AppIcons.TagFaces), contentDescription = "Localized description") } }, menuContent = { DropdownMenuItem( leadingIcon = { Icon(painter = rememberVectorPainter(AppIcons.TagFaces), contentDescription = null) }, text = { Text("Emotes") }, onClick = {}, ) }, ) } }
Outros recursos
- Material Design: Menus