Dropdown

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

安装

The above command is for individual installation only. You may skip this step if @heroui/react is already installed globally.

导入

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

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

用法

动态项

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

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

禁用键

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

注意: 确保每个项都有唯一的键，否则禁用键将无法正常工作。

操作事件

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

变体

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

单选

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

多选

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

注意: 若要允许空选，可将 disallowEmptySelection 属性设置为 false。

带快捷键

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

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

带图标

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

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

带描述

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

带分组

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

注意: 没有 title 的分组必须提供 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: 下拉菜单项的主插槽。它包装所有其他插槽。
• wrapper: title 和 description 的包装器。
• title: 下拉菜单项的标题。
• description: 下拉菜单项的描述。
• shortcut: 快捷键插槽。
• selectedIcon: 选中图标插槽。仅在项被选中时可见。

DropdownSection

• base: 下拉菜单分组的主插槽。它包装所有其他插槽。
• heading: 在分组顶部渲染的标题。
• group: 下拉菜单项的分组。
• divider: 在分组之间渲染的分隔线。仅在 showDivider 为 true 时可见。

自定义下拉菜单弹出框

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

自定义下拉菜单项样式

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

键盘交互

数据属性

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

• data-disabled: 当下拉菜单项被禁用时。基于 dropdown disabledKeys 属性。
• data-selected: 当下拉菜单项被选中时。基于 dropdown selectedKeys 属性。
• data-hover: 当下拉菜单项被悬停时。基于 useHover
• data-pressed: 当下拉菜单项被按下时。基于 usePress
• data-focus: 当下拉菜单项获得焦点时。基于 useFocusRing。
• data-focus-visible: 当通过键盘使下拉菜单项获得焦点时。基于 useFocusRing。

无障碍访问

• 使用 ARIA 作为具有 menu 的 button 暴露给辅助技术。
• 支持单选、多选或无选择。
• 支持禁用项。
• 支持分组。
• 支持复杂的项标签以实现无障碍访问。
• 支持键盘导航，包括箭头键、Home/End、Page Up/Down。有关详细信息，请参阅 键盘交互。
• 支持键盘导航期间的自动滚动。
• 支持使用箭头键打开菜单，包括自动相应地将焦点置于第一个或最后一个项。
• 支持通过键入文本来聚焦项的输入预测。
• 支持虚拟化滚动以提高长列表的性能。

API

Dropdown 属性

Dropdown 事件

DropdownTrigger 属性

DropdownMenu 属性

DropdownMenu 事件

DropdownSection 属性

DropdownItem 属性

DropdownItem 事件

类型

Dropdown Item 选中图标属性