下拉菜单

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

安装

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

导入

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

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

用法

动态项

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

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

禁用键

可以使用 disabledKeys 属性来禁用下拉菜单项，该属性用于 DropdownMenu 组件。

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

操作事件

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

变体

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

单选

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

多选

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

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

带有快捷键

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

注意：下拉菜单不处理快捷键事件，您需要自己处理。

带有图标

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

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

带有描述

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

带有节

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

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

自定义触发器

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

更改背景

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

路由

<DropdownItem> 组件适用于框架和客户端路由器，例如 Next.js 和 React Router。请参阅 路由 指南，了解如何进行设置。

插槽

下拉菜单有 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：当下拉菜单项被禁用时。基于下拉菜单的 disabledKeys 属性。
• data-selected：当下拉菜单项被选中时。基于下拉菜单的 selectedKeys 属性。
• data-hover：当鼠标悬停在下拉菜单项上时。基于 useHover。
• data-pressed：当下拉菜单项被按下时。基于 usePress。
• data-focus：当下拉菜单项获得焦点时。基于 useFocusRing。
• data-focus-visible：当使用键盘导航使下拉菜单项获得焦点时。基于 useFocusRing。

辅助功能

• 作为带有 ARIA 的 menu 的 button 公开给辅助技术。
• 支持单选、多选或不选。
• 支持禁用项。
• 支持节。
• 支持用于辅助功能的复杂项标签。
• 支持键盘导航，包括箭头键、Home/End、Page Up/Down 键。有关详细信息，请参阅键盘交互。
• 支持键盘导航期间自动滚动。
• 支持使用箭头键打开菜单的键盘支持，包括自动聚焦到第一个或最后一个项。
• 支持通过输入文本来聚焦项的预输入功能。
• 支持虚拟化滚动，以在长列表情况下提高性能。

API

下拉菜单属性

下拉菜单事件

下拉菜单触发器属性

下拉菜单属性

下拉菜单事件

下拉菜单节属性

下拉菜单项属性

下拉菜单项事件

类型

下拉菜单项选中图标属性