> Leaf UI 0.17.3 · Package: @ifhover/leaf-ui · Source: c3221834f84f2f48481a2054026b713456f8e5dc
> Browser documentation: https://ifhover.github.io/leaf-ui/components/dropdown.html

> For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/llms-full.txt.

# Dropdown 下拉菜单

在菜单中收纳更多操作。


## 基础用法

[](#)
通过 `items` 提供菜单操作，并使用按钮作为触发器。


更多操作

basic.tsx

复制代码

```tsx lineNumbers file="../../src/examples/dropdown/basic.tsx"
import { Button, Dropdown, Flex, Text } from '@ifhover/leaf-ui';
import { Archive, ChevronDown, Copy, Pencil } from 'lucide-react';
import { useState } from 'react';

export function DropdownBasic() {
  const [action, setAction] = useState('');
  return (
    <Flex direction="column" gap="md" align="start">
      <Dropdown
        items={[
          { key: 'edit', label: '编辑', icon: <Pencil size={14} /> },
          { key: 'copy', label: '复制', icon: <Copy size={14} /> },
          { key: 'archive', label: '归档', icon: <Archive size={14} /> },
        ]}
        onSelect={setAction}
      >
        <Button variant="outline" endIcon={<ChevronDown size={16} />}>
          更多操作
        </Button>
      </Dropdown>
      {action && <Text role="status">已选择: {action}</Text>}
    </Flex>
  );
}
```

展开代码


## 示例

### 右侧内容

通过条目的 `extra` 放置快捷键、标签等补充信息。它属于整行点击区域，不要在其中嵌套按钮或链接。


更多操作

extra.tsx

复制代码

```tsx lineNumbers file="../../src/examples/dropdown/extra.tsx"
import type { DropdownItem } from '@ifhover/leaf-ui';
import { Button, Dropdown, Flex, Tag, Text } from '@ifhover/leaf-ui';
import { ChevronDown, Copy, Download, Pencil } from 'lucide-react';
import { useState } from 'react';

const items: DropdownItem[] = [
  { key: 'edit', label: '编辑', icon: <Pencil />, extra: <Text tone="muted">Ctrl E</Text> },
  { key: 'copy', label: '复制链接', icon: <Copy />, extra: <Tag size="sm">新</Tag> },
  {
    key: 'export',
    label: '导出',
    icon: <Download />,
    extra: <Text tone="muted">CSV</Text>,
    children: [
      { key: 'all', label: '全部数据' },
      { key: 'selected', label: '当前选择' },
    ],
  },
];

export function DropdownExtra() {
  const [action, setAction] = useState('');
  return (
    <Flex direction="column" gap="md" align="start">
      <Dropdown items={items} onSelect={setAction}>
        <Button variant="outline" endIcon={<ChevronDown size={16} />}>
          更多操作
        </Button>
      </Dropdown>
      {action && <Text role="status">已选择: {action}</Text>}
    </Flex>
  );
}
```

展开代码

### 菜单尺寸

通过 Dropdown 的 `size` 设置菜单尺寸，子菜单继承该尺寸。触发按钮使用自己的 `size`。


小更多操作

默认更多操作

大更多操作

sizes.tsx

复制代码

```tsx lineNumbers file="../../src/examples/dropdown/sizes.tsx"
import { Button, Dropdown, Flex, Grid, Text } from '@ifhover/leaf-ui';
import { ChevronDown, Copy, Pencil } from 'lucide-react';

const sizes = [
  { size: 'sm', label: '小' },
  { size: 'md', label: '默认' },
  { size: 'lg', label: '大' },
] as const;

export function DropdownSizes() {
  return (
    <Flex direction="column" gap="md">
      {sizes.map(({ size, label }) => (
        <Grid
          key={size}
          role="group"
          aria-label={label}
          columns={{ xs: 1, sm: 2 }}
          gap="8px"
          align="center"
        >
          <Text tone="muted">{label}</Text>
          <Dropdown
            size={size}
            items={[
              { key: 'edit', label: '编辑', icon: <Pencil /> },
              { key: 'copy', label: '复制链接', icon: <Copy />, extra: 'Ctrl C' },
            ]}
          >
            <Button variant="outline" endIcon={<ChevronDown size={16} />}>
              更多操作
            </Button>
          </Dropdown>
        </Grid>
      ))}
    </Flex>
  );
}
```

展开代码

### 子菜单与分组

`children` 定义子菜单，`type: 'group'` 与 `label` 定义分组标题。只有选择菜单项才触发 `onSelect`，展开子菜单不会触发。


项目操作

hierarchy.tsx

复制代码

```tsx lineNumbers file="../../src/examples/dropdown/hierarchy.tsx"
import { Button, Dropdown, Flex, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function DropdownHierarchy() {
  const [action, setAction] = useState('');
  return (
    <Flex direction="column" gap="md" align="start">
      <Dropdown
        onSelect={setAction}
        items={[
          {
            key: 'project',
            type: 'group',
            label: '项目',
            children: [
              { key: 'open', label: '打开' },
              {
                key: 'export',
                label: '导出',
                children: [
                  { key: 'csv', label: 'CSV' },
                  { key: 'json', label: 'JSON' },
                ],
              },
            ],
          },
          { key: 'divider', type: 'divider' },
          { key: 'archive', label: '归档', disabled: true },
          { key: 'delete', label: '删除', danger: true },
        ]}
      >
        <Button variant="outline">项目操作</Button>
      </Dropdown>
      {action && <Text role="status">已选择: {action}</Text>}
    </Flex>
  );
}
```

展开代码

### 单选菜单

使用 `type: 'radio'`，相同 `group` 标识同一互斥组。示例通过 `checked` 和 `onCheckedChange` 管理当前视图。


切换视图当前视图: 列表

radio.tsx

复制代码

```tsx lineNumbers file="../../src/examples/dropdown/radio.tsx"
import { Button, Dropdown, Flex, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function DropdownRadio() {
  const [view, setView] = useState('list');
  return (
    <Flex direction="column" gap="md" align="start">
      <Dropdown
        items={[
          {
            key: 'list',
            label: '列表',
            type: 'radio',
            group: 'view',
            checked: view === 'list',
            onCheckedChange: () => setView('list'),
          },
          {
            key: 'grid',
            label: '网格',
            type: 'radio',
            group: 'view',
            checked: view === 'grid',
            onCheckedChange: () => setView('grid'),
          },
        ]}
      >
        <Button variant="outline">切换视图</Button>
      </Dropdown>
      <Text role="status" tone="muted">
        当前视图: {view === 'list' ? '列表' : '网格'}
      </Text>
    </Flex>
  );
}
```

展开代码

### 复选菜单

单选和复选菜单默认在选择后保持打开。通过 `closeOnSelect` 可覆盖此行为。


显示选项详情已显示

checkbox.tsx

复制代码

```tsx lineNumbers file="../../src/examples/dropdown/checkbox.tsx"
import { Button, Dropdown, Flex, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function DropdownCheckbox() {
  const [details, setDetails] = useState(true);
  return (
    <Flex direction="column" gap="md" align="start">
      <Dropdown
        items={[
          {
            key: 'details',
            label: '显示详情',
            type: 'checkbox',
            checked: details,
            onCheckedChange: setDetails,
          },
        ]}
      >
        <Button variant="outline">显示选项</Button>
      </Dropdown>
      <Text role="status" tone="muted">
        {details ? '详情已显示' : '详情已隐藏'}
      </Text>
    </Flex>
  );
}
```

展开代码

### 悬停触发

[](#)
设置 `trigger="hover"` 后，指针移入时打开。仍可聚焦按钮并按方向键打开菜单。


悬停展开

hover.tsx

复制代码

```tsx lineNumbers file="../../src/examples/dropdown/hover.tsx"
import { Button, Dropdown, Flex, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function DropdownHover() {
  const [action, setAction] = useState('');
  return (
    <Flex direction="column" gap="md" align="start">
      <Dropdown
        trigger="hover"
        items={[
          { key: 'edit', label: '编辑' },
          { key: 'copy', label: '复制' },
        ]}
        onSelect={setAction}
      >
        <Button variant="outline">悬停展开</Button>
      </Dropdown>
      {action && <Text role="status">已选择: {action}</Text>}
    </Flex>
  );
}
```

展开代码

### 右键菜单

设置 `trigger="contextMenu"` 后，在右键点击处打开。键盘用户可聚焦按钮并按 ↓ 或 ↑ 打开菜单。


在此右键点击

context-menu.tsx

复制代码

```tsx lineNumbers file="../../src/examples/dropdown/context-menu.tsx"
import { Button, Dropdown, Flex, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function DropdownContextMenu() {
  const [action, setAction] = useState('');
  return (
    <Flex direction="column" gap="md" align="start">
      <Dropdown
        trigger="contextMenu"
        items={[
          { key: 'edit', label: '编辑' },
          { key: 'copy', label: '复制' },
        ]}
        onSelect={setAction}
      >
        <Button variant="outline">在此右键点击</Button>
      </Dropdown>
      {action && <Text role="status">已选择: {action}</Text>}
    </Flex>
  );
}
```

展开代码


## API

### Dropdown API

触发器应是支持 ref 与事件的单个按钮。Escape 关闭菜单并返回触发按钮。共享浮层参数见 [PopupOptions](https://ifhover.github.io/leaf-ui/api/popup-options.md)。

| 属性                  | 类型                                                                                                                                                                   | 默认值              | 说明                               |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | -------------------------------- |
| `items`             | `readonly `[`DropdownItem`](#dropdownitem)`[]`                                                                                                                       | 必填               | 菜单项列表                            |
| `children`          | `ReactElement< ButtonHTMLAttributes<HTMLButtonElement> & { ref?: Ref<HTMLButtonElement> } >`                                                                         | 必填               | 单个按钮，支持 Leaf Button 或 button     |
| `trigger`           | `'click' \| 'hover' \| 'contextMenu' \| readonly ('click' \| 'hover' \| 'contextMenu')[]`                                                                            | `'click'`        | 触发方式；下拉菜单支持点击、悬停和右键。             |
| `disabled`          | `boolean`                                                                                                                                                            | `false`          | 禁用交互。                            |
| `size`              | `'sm' \| 'md' \| 'lg'`                                                                                                                                               | `'md'`           | 展示尺寸。                            |
| `open`              | `boolean`                                                                                                                                                            | —                | 受控的展开状态。                         |
| `defaultOpen`       | `boolean`                                                                                                                                                            | `false`          | 非受控模式的初始展开状态。                    |
| `onOpenChange`      | `(open: boolean) => void`                                                                                                                                            | —                | 展开状态变更                           |
| `onSelect`          | `(key: string) => void`                                                                                                                                              | —                | 激活叶菜单项时返回 key，包括单选和复选项；展开子菜单不触发。 |
| `placement`         | `'top-start' \| 'top-end' \| 'bottom-start' \| 'bottom-end'`                                                                                                         | `'bottom-start'` | 菜单位置；popupPlacement 优先。          |
| `popupWidth`        | `number \| string`                                                                                                                                                   | `—`              | 浮层宽度；未设置时最小 160px，并根据内容增宽。       |
| `popupMaxWidth`     | `number \| string`                                                                                                                                                   | `420`            | 浮层最大宽度，仍受视口限制。                   |
| `itemRender`        | `(item: `[`DropdownItem`](#dropdownitem)`) => ReactNode`                                                                                                             | —                | 自定义菜单项的标签内容，不替换整行。               |
| `mouseEnterDelay`   | `number`                                                                                                                                                             | `100`            | 悬停触发后等待多少毫秒再打开。                  |
| `mouseLeaveDelay`   | `number`                                                                                                                                                             | `150`            | 鼠标离开后等待多少毫秒再关闭。                  |
| `popupPlacement`    | `'top' \| 'top-start' \| 'top-end' \| 'bottom' \| 'bottom-start' \| 'bottom-end' \| 'left' \| 'left-start' \| 'left-end' \| 'right' \| 'right-start' \| 'right-end'` | —                | 浮层相对触发控件的位置。                     |
| `popupClassName`    | `string`                                                                                                                                                             | —                | 浮层的自定义类名。                        |
| `popupStyle`        | `CSSProperties`                                                                                                                                                      | —                | 浮层的自定义样式。                        |
| `popupRender`       | `(content: React.ReactNode) => React.ReactNode`                                                                                                                      | —                | 包装或补充面板内容，保留传入的内容以维持交互。          |
| `getPopupContainer` | `() => Element \| DocumentFragment`                                                                                                                                  | —                | 返回浮层的挂载容器，也可返回 ShadowRoot。       |

### DropdownItem

下拉菜单中的操作、分组或子菜单数据。

| 属性                | 类型                                                        | 默认值      | 说明                                    |
| ----------------- | --------------------------------------------------------- | -------- | ------------------------------------- |
| `key`             | `string`                                                  | 必填       | 唯一标识                                  |
| `label`           | `ReactNode`                                               | —        | 菜单项文字或分组标题。                           |
| `icon`            | `ReactNode`                                               | —        | 菜单项文字前的图标。                            |
| `extra`           | `ReactNode`                                               | —        | 条目右侧的附加内容；适合放快捷键、状态标签等非交互信息。          |
| `type`            | `'item' \| 'divider' \| 'group' \| 'checkbox' \| 'radio'` | `'item'` | 普通项、分隔线、分组、复选项或单选项。                   |
| `children`        | `readonly `[`DropdownItem`](#dropdownitem)`[]`            | —        | 菜单项列表。                                |
| `disabled`        | `boolean`                                                 | `false`  | 禁用交互。                                 |
| `danger`          | `boolean`                                                 | `false`  | 危险操作的颜色，不会禁用菜单项。                      |
| `checked`         | `boolean`                                                 | —        | 受控的勾选状态；省略时由菜单内部保存。                   |
| `group`           | `string`                                                  | —        | 单选项所属的互斥组标识。                          |
| `closeOnSelect`   | `boolean`                                                 | —        | 选择后是否关闭；默认普通项关闭，单选和复选项保持打开。           |
| `onCheckedChange` | `(checked: boolean) => void`                              | —        | 点击勾选项时返回下一勾选状态。                       |
| `href`            | `string`                                                  | —        | 链接目标。                                 |
| `target`          | `string`                                                  | —        | 链接的 target 属性，例如 \_blank；省略时在当前标签页打开。 |
| `onClick`         | `(event: MouseEvent<HTMLElement>) => void`                | —        | 点击此项时触发                               |
