菜单

下拉菜单可让用户点击图标、文本字段或其他组件,然后从临时界面上的选项列表中进行选择。本指南介绍了如何创建基本菜单以及包含分隔线和图标的更复杂菜单。

一个下拉菜单,其中显示了两个选项。一个带有三个竖点的图标,表示点击它会打开菜单。
图 1. 一个列出了两项内容的基本下拉菜单。

API Surface

使用 DropdownMenu、DropdownMenuItem、IconButton 和 ExposedDropdownMenuBox 组件实现下拉菜单。DropdownMenu 和 DropdownMenuItem 组件用于显示菜单项,而 IconButton 或其他组件可以触发菜单显示。 ExposedDropdownMenuBox 用于创建附加到文本字段的菜单。

DropdownMenu 组件的关键参数包括:

  • expanded:指示菜单是否可见。
  • onDismissRequest:用于处理菜单关闭。
  • content:菜单的可组合内容,通常包含 DropdownMenuItem 可组合项。

DropdownMenuItem 的关键参数包括:

  • text:定义菜单项中显示的内容。
  • onClick:用于处理与菜单中项的互动的回调。

创建基本下拉菜单

以下代码段展示了最简单的 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... */ }
            )
        }
    }
}

代码要点

  • 定义一个包含两个菜单项的基本 DropdownMenu。
  • expanded 参数用于控制菜单的可见性(展开或收起)。
  • onDismissRequest 参数定义了在用户关闭菜单时执行的回调。
  • DropdownMenuItem 可组合项表示下拉菜单中的可选项。
  • IconButton 会触发菜单的展开和收起。

结果

图 2. 一个仅包含两个选项的极简下拉菜单。

创建较长的下拉菜单

如果无法一次显示所有菜单项,DropdownMenu 默认可滚动。以下代码段会创建一个较长的可滚动下拉菜单:

@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... */ }
                )
            }
        }
    }
}

代码要点

  • 当 DropdownMenu 内容的总高度超过可用空间时,该组件可滚动。此代码会创建一个可滚动的 DropdownMenu,其中显示 100 个占位符项。
  • forEach 循环会动态生成 DropdownMenuItem 可组合项。这些项不是延迟创建的,这意味着所有 100 个下拉项都会创建并存在于组合中。
  • 点击 IconButton 会触发 DropdownMenu 的展开和收起。
  • 每个 DropdownMenuItem 中的 onClick lambda 可让您定义用户选择菜单项时执行的操作。

结果

上述代码段会生成以下可滚动菜单:

图 3. 一个可滚动的长下拉菜单。

创建包含分隔线的较长下拉菜单

以下代码段展示了下拉菜单的更高级实现。 在此代码段中,前导图标和尾随图标会添加到菜单项中,并且分隔线会分隔菜单项组。

@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... */ }
            )
        }
    }
}

此代码在 Box 中定义了一个 DropdownMenu。

代码要点

  • leadingIcon 和 trailingIcon 参数可向 DropdownMenuItem 的开头和结尾添加图标。
  • IconButton 会触发菜单展开。
  • DropdownMenu 包含多个 DropdownMenuItem 可组合项,每个可组合项都代表一个可选择的操作。
  • HorizontalDivider 可组合项会插入一条水平线,用于分隔菜单项组。

结果

上述代码段会生成一个包含图标和分隔线的下拉菜单:

图 4. 一个下拉菜单,分为多个部分,带有前导和尾随图标。

M3 Expressive 更新

Material 3 Expressive 引入了 DropdownMenuPopup、DropdownMenuGroup 和 CheckableDropdownMenuItem 作为 DropdownMenu 和 DropdownMenuItem 的附加选项,用于创建包含分组项、间隙和可勾选状态的分段菜单。

M3 Expressive 菜单示例。
图 5. Material 3 Expressive 垂直菜单变体,带有间隙(1,左侧)和分隔线(2,右侧)。

如需详细了解菜单的 M3 Expressive 更新,请参阅 Material Design 3 菜单指南。

细分菜单

分段菜单会将相关操作分组到不同的视觉部分,各部分之间用间隙或分隔线隔开。以下代码段演示了如何使用 DropdownMenuPopup、DropdownMenuGroup 和 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 = {},
                )
            },
        )
    }
}

其他资源