下拉菜单

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

安装

npx nextui-cli@latest add dropdown

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

导入

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

• Dropdown: 主要组件，是其他组件的包装器。此组件是 Popover 组件的扩展，因此它接受 Popover 组件的所有 props。
• DropdownTrigger: 触发下拉菜单打开的组件。
• 下拉菜单: 包含下拉项的组件。
• 下拉部分: 包含一组下拉项的组件。
• 下拉项: 代表下拉项的组件。

用法

动态项

下拉菜单遵循 集合组件 API，接受静态和动态集合。

• 静态: 上面的用法示例展示了静态实现，当所有选项列表提前已知时可以使用。
• 动态：以下示例适用于选项来自外部数据源（例如 API 调用）或随时间更新的情况。

禁用键

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

注意：为每个项目设置一个唯一的键非常重要，否则禁用键将不起作用。

操作事件

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

变体

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

单选

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

多选

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

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

带快捷键

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

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

带图标

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

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

带描述

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

带分段

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

注意: 没有 title 的分段必须提供 aria-label 以确保可访问性。

自定义触发器

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

更改背景

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

路由

<DropdownItem> 组件与框架和客户端路由器（如 Next.js 和 React Router）一起工作。请参阅 路由 指南，了解如何设置它。

import {Dropdown, DropdownMenu, DropdownTrigger, DropdownItem, Button} from "@nextui-org/react";

function App() {
  return (
    <Dropdown>
      <DropdownTrigger>
        <Button variant="bordered">Open Menu</Button>
      </DropdownTrigger>
      <DropdownMenu aria-label="Link Actions">
        <DropdownItem key="home" href="/home">
          Home
        </DropdownItem>
        <DropdownItem key="about" href="/about">
          About
        </DropdownItem>
      </DropdownMenu>
    </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: 当下拉菜单项被禁用时。基于下拉菜单 disabledKeys 属性。
• data-selected: 当下拉菜单项被选中时。基于下拉菜单 selectedKeys 属性。
• data-hover: 当下拉菜单项被悬停时。基于 useHover
• data-pressed: 当下拉菜单项被按下时。基于 usePress
• data-focus: 当下拉菜单项被聚焦时。基于 useFocusRing.
• data-focus-visible: 当下拉菜单项使用键盘获得焦点时。基于 useFocusRing.

无障碍性

• 作为 按钮，使用 ARIA 暴露给辅助技术，并带有 菜单。
• 支持单选、多选或不选择。
• 支持禁用项目。
• 支持部分。
• 支持复杂项目标签以实现无障碍性。
• 支持键盘导航，包括箭头键、Home/End、Page Up/Down。有关更多详细信息，请参阅 键盘交互。
• 在键盘导航期间支持自动滚动。
• 支持使用箭头键打开菜单，包括自动聚焦第一个或最后一个项目。
• 支持通过输入文本来聚焦项目的联想输入。
• 支持虚拟化滚动，以提高长列表的性能。

API

下拉菜单属性

下拉事件

DropdownTrigger 属性

DropdownMenu 属性

下拉菜单事件

下拉菜单部分 Props

下拉菜单项 Props

下拉项事件

类型

下拉菜单项选中图标属性

export type DropdownItemSelectedIconProps = {
  /**
   * The current icon, usually an checkmark icon.
   */
  icon?: ReactNode;
  /**
   * The current selected status.
   */
  isSelected?: boolean;
  /**
   * The current disabled status.
   * @default false
   */
  isDisabled?: boolean;
};

type selectedIcon?: ReactNode | ((props: DropdownItemSelectedIconProps) => ReactNode) | null;