---
url: https://ain.hmgf.hxcn.space/contribution/project-components/dropdown.md
description: HeroUI 风格下拉菜单组件，支持图标项、分组分隔符、hover/click 触发、受控状态和自定义最小宽度。
---

# Dropdown 组件

`Dropdown` 适合做操作菜单、工具栏下拉和带图标的选择列表。

## 基础用法

```md
<Dropdown :items="[{ text: '复制', icon: 'copy' }, { text: '重命名', icon: 'edit' }, { text: '删除', icon: 'trash', action: () => {} }]" placement="bottom-start">
  <template #trigger>
    <LinkButton text="操作菜单" variant="outline" />
  </template>
</Dropdown>
```

## Items 结构

`items` 数组中每项支持以下字段：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `text` | `string` | 显示文本 |
| `icon` | `string` | 图标名（配合 `#icon-{name}` 插槽使用） |
| `link` | `string` | 点击后跳转链接 |
| `action` | `() => void` | 点击后执行的回调函数 |
| `disabled` | `boolean` | 禁用该项 |
| `active` | `boolean` | 高亮激活状态 |
| `divider` | `boolean` | 作为分隔线渲染（text/icon 等字段被忽略） |

## 带图标项

```vue
<Dropdown :items="iconItems" placement="bottom-start">
  <template #trigger>
    <LinkButton text="带图标菜单" variant="outline" />
  </template>
  <template #icon-copy>
    <svg ...><!-- copy icon --></svg>
  </template>
  <template #icon-external>
    <svg ...><!-- external link icon --></svg>
  </template>
</Dropdown>
```

## 受控状态

```md
<script setup>
import { ref } from 'vue'
const controlledOpen = ref(false)
const controlledItems = [{ text: '选项一', action: () => {} }, ...]
</script>

<Dropdown v-model:open="controlledOpen" :items="controlledItems" placement="bottom">
  <template #trigger>
    <LinkButton :text="controlledOpen ? '关闭菜单' : '打开菜单'" variant="outline" />
  </template>
</Dropdown>
```

`v-model:open` 控制菜单的打开状态。

## Hover 触发

`trigger="hover"` 使菜单在鼠标悬停时打开，移出时关闭。

## 自定义尺寸

`:min-width` 控制面板最小宽度（默认 `180px`）。

## Placements

## Props

| 参数 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `items` | `DropdownItem[]` | `[]` | 菜单项数组 |
| `placement` | `bottom \| bottom-start \| bottom-end \| top \| top-start \| top-end` | `bottom-start` | 面板弹出位置 |
| `trigger` | `click \| hover \| both` | `click` | 触发方式 |
| `disabled` | `boolean` | `false` | 禁用下拉菜单 |
| `maxHeight` | `number` | `320` | 面板最大高度（px） |
| `minWidth` | `number` | `180` | 面板最小宽度（px） |

## DropdownItem 类型

```ts
export interface DropdownItem {
  text?: string
  link?: string
  icon?: string
  action?: () => void
  divider?: boolean
  disabled?: boolean
  active?: boolean
}
```

## Emits

| 事件 | 参数 | 说明 |
| --- | --- | --- |
| `select` | `item: DropdownItem` | 用户点击菜单项时触发 |
| `update:open` | `open: boolean` | 配合 `v-model:open` 使用 |