下拉菜单

显示用户可以选择的操作或选项列表。

安装

以上命令仅用于单独安装。如果 @heroui/react 已全局安装，则可以跳过此步骤。

导入

HeroUI 导出 5 个与下拉菜单相关的组件

• Dropdown: 主要组件，是其他组件的包装器。此组件是 弹出框 组件的扩展，因此它接受 Popover 组件的所有属性。
• DropdownTrigger: 触发下拉菜单打开的组件。
• DropdownMenu: 包含下拉菜单项的组件。
• DropdownSection: 包含一组下拉菜单项的组件。
• DropdownItem: 代表一个下拉菜单项的组件。

用法

动态条目

Dropdown 组件遵循 Collection Components API，接受静态和动态集合。

• 静态: 上面的用法示例展示了静态实现，当预先知道完整的选项列表时可以使用。
• 动态: 当选项来自外部数据源（例如 API 调用）或随时间更新时，可以使用下面的示例。

禁用键

可以使用 disabledKeys 属性禁用 DropdownMenu 组件中的下拉菜单项。

注意: 每个项目都必须有一个唯一的键，否则禁用键将不起作用。

动作事件

您可以使用 onAction 属性来获取所选项目的键。

变体

您可以使用 DropdownMenu 组件中的 variant 属性来更改下拉菜单项的 hover 样式。

单项选择

您可以将 selectionMode 属性设置为 single，以允许用户一次只选择一个项目。

多项选择

您可以将 selectionMode 属性设置为 multiple，以允许用户一次选择多个项目。

注意：要允许空选择，您可以将 disallowEmptySelection 属性设置为 false。

使用快捷键

您可以使用 shortcut 属性为下拉菜单项添加快捷键。

注意：Dropdown 不处理快捷键事件，您需要自行处理。

使用图标

可以使用 startContent / endContent 属性向下拉菜单项添加图标。

注意：如果您使用 currentColor 作为图标颜色，图标将与项目文本具有相同的颜色。

使用描述

您可以使用 description 属性向下拉菜单项添加描述。

使用 sections

您可以使用 DropdownSection 组件对下拉菜单项进行分组。

注意：没有 title 的 sections 必须提供 aria-label 以提高可访问性。

自定义触发器

您可以使用任何组件作为下拉菜单的触发器，只需将其包裹在 DropdownTrigger 组件中即可。

更改背景幕

正如我们之前提到的，Dropdown 组件是 Popover 组件的扩展，因此它接受 Popover 组件的所有属性，包括 backdrop 属性。

路由

<DropdownItem> 组件可以与框架和客户端路由（如 Next.js 和 React Router）一起使用。请参阅 路由 指南，了解如何进行设置。

插槽

Dropdown 有 3 个带有插槽的组件：DropdownMenu、DropdownItem 和 DropdownSection 组件。

DropdownMenu

• base：菜单组件的主要包装器。此插槽包裹 topContent、bottomContent 和 list 插槽。
• list：菜单列表组件的插槽。您可以将此插槽视为 ul 插槽。
• emptyContent：当集合为空时要显示的插槽内容。

DropdownItem

• base：dropdown item 的主要插槽。它包裹所有其他插槽。
• wrapper：title 和 description 的包装器。
• title：dropdown item 的标题。
• description：dropdown item 的描述。
• shortcut：快捷键插槽。
• selectedIcon：选定图标插槽。仅在项目被选中时可见。

DropdownSection

• base：dropdown section 的主要插槽。它包裹所有其他插槽。
• heading：在 section group 顶部渲染的标题。
• group：dropdown items 的组。
• divider：在组之间渲染的分隔线。仅当 showDivider 为 true 时可见。

自定义下拉 popover

Dropdown 组件是 Popover 组件的扩展，因此您可以使用相同的插槽来自定义 dropdown。

自定义下拉菜单项样式

您可以通过使用 DropdownMenu 的 itemClasses 属性或使用 DropdownItem 插槽来自定义下拉菜单项。 itemClasses 允许您一次自定义所有项目，而插槽允许您单独自定义每个项目。

键盘交互

数据属性

DropdownItem 在 base 元素上具有以下属性

• data-disabled：当 dropdown item 被禁用时。基于 dropdown disabledKeys 属性。
• data-selected：当 dropdown item 被选中时。基于 dropdown selectedKeys 属性。
• data-hover：当 dropdown item 正在被悬停时。基于 useHover
• data-pressed：当 dropdown item 被按下时。基于 usePress
• data-focus：当 dropdown item 正在被聚焦时。基于 useFocusRing。
• data-focus-visible：当 dropdown item 正在被键盘聚焦时。基于 useFocusRing。

可访问性

• 作为带有 ARIA 的 menu 的 button 暴露给辅助技术。
• 支持单项、多项或无选择。
• 支持禁用项目。
• 支持 sections。
• 复杂的项目标签支持可访问性。
• 键盘导航支持，包括箭头键、Home/End、Page Up/Down。 有关更多详细信息，请参阅键盘交互。
• 键盘导航期间的自动滚动支持。
• 使用箭头键打开菜单的键盘支持，包括自动聚焦第一个或最后一个项目。
• Typeahead 允许通过键入文本来聚焦项目。
• 虚拟化滚动支持，以提高长列表的性能。

API

Dropdown Props

Dropdown Events

DropdownTrigger Props

DropdownMenu Props

DropdownMenu Events

DropdownSection Props

DropdownItem Props

DropdownItem Events

类型

下拉菜单项选中图标属性