Menus

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.

Um menu suspenso com duas opções. Um ícone com três pontos verticais indica que, ao clicar nele, o menu é aberto.
Figura 1. Um menu suspenso básico com dois itens listados.

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áveis DropdownMenuItem.

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 DropdownMenu básico que contém dois itens de menu.
  • O parâmetro expanded controla a visibilidade do menu como expandido ou recolhido.
  • O parâmetro onDismissRequest define um callback que é executado quando o usuário fecha o menu.
  • O elemento combinável DropdownMenuItem representa itens selecionáveis no menu suspenso.
  • Um IconButton aciona a expansão e o recolhimento do menu.

Resultado

Figura 2. Um menu suspenso mínimo com apenas duas opções.

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 um DropdownMenu rolável que mostra 100 itens de marcador de posição.
  • O loop forEach gera dinamicamente elementos combináveis DropdownMenuItem. 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 IconButton aciona a expansão e o recolhimento do DropdownMenu quando clicado.
  • A lambda onClick em cada DropdownMenuItem permite 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:

Figura 3. Um menu suspenso longo e 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 leadingIcon e trailingIcon adicionam ícones ao início e ao fim de um DropdownMenuItem.
  • Um IconButton aciona a expansão do menu.
  • O DropdownMenu contém vários elementos combináveis DropdownMenuItem, cada um representando uma ação selecionável.
  • Os elementos combináveis HorizontalDivider inserem uma linha horizontal para separar grupos de itens de menu.

Resultado

O snippet anterior produz um menu suspenso com ícones e divisores:

Figura 4. Um menu suspenso dividido em seções com ícones à esquerda e à direita.

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.

Exemplos de menus expressivos do Material 3.
Figura 5. Variações do menu vertical do Material 3 Expressive com lacunas (1, à esquerda) e divisores (2, à direita).

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