下拉菜单可让用户点击图标、文本字段或其他组件,然后从临时界面上的选项列表中进行选择。本指南介绍了如何创建基本菜单以及包含分隔线和图标的更复杂菜单。
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会触发菜单的展开和收起。
结果
创建较长的下拉菜单
如果无法一次显示所有菜单项,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中的onClicklambda 可让您定义用户选择菜单项时执行的操作。
结果
上述代码段会生成以下可滚动菜单:
创建包含分隔线的较长下拉菜单
以下代码段展示了下拉菜单的更高级实现。 在此代码段中,前导图标和尾随图标会添加到菜单项中,并且分隔线会分隔菜单项组。
@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可组合项会插入一条水平线,用于分隔菜单项组。
结果
上述代码段会生成一个包含图标和分隔线的下拉菜单:
M3 Expressive 更新
Material 3 Expressive 引入了 DropdownMenuPopup、DropdownMenuGroup 和 CheckableDropdownMenuItem 作为 DropdownMenu 和 DropdownMenuItem 的附加选项,用于创建包含分组项、间隙和可勾选状态的分段菜单。
如需详细了解菜单的 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 = {}, ) }, ) } }
其他资源
- Material Design:菜单