---
url: /components/dropdown.md
---
# Dropdown 下拉菜单

将动作或菜单收纳进触发区弹层：支持 hover / click / contextmenu 触发与 split-button 按钮组形态，弹层 Teleport 至 body 自动定位翻转，item 点击抛出 command 事件并自动收起，另提供命令式 open / close。

键盘操作：触发器聚焦后 Enter / Space / ↓ 打开浮层（触发内容为原生可聚焦元素时依赖其原生焦点，纯文本触发由容器承接），↑↓ 在菜单项间移动焦点（跳过禁用项）、Enter / Space 选中当前项、Esc 关闭并把焦点还给触发器。

## 基础用法

触发区内容放 `#trigger` 插槽（保留下拉箭头），菜单项放在 `#dropdown` 的 eb-dropdown-menu 内；item 的 `label` / `icon` 是默认插槽的兜底，写入插槽内容时以插槽为准。

## command 事件

item 的 `command` 随事件抛出（支持字符串、数字、对象等任意类型），抛出后浮层自动收起；未设置 command 时值为 undefined。

## 触发方式与按钮组

`trigger` 支持 hover（默认，含开合延时）/ click / contextmenu（触发区右键弹出）；`split-button` 拆为主按钮 + 箭头按钮，主按钮点击触发 click 事件，此时菜单项直接写入默认插槽。

## 右键触发与弹层位置

`trigger="contextmenu"` 在触发区右键弹出（自动阻止浏览器默认菜单）；`placement` 调整弹层方位，可视空间不足时自动翻转。

## 禁用与开合延时

`disabled` 整体禁用（触发与弹出均失效，与 item 级 disabled 区分）；hover 触发下 `show-timeout` / `hide-timeout` 分别控制展开与收起延时（毫秒）。

## 命令式开关

通过模板 ref 调用 open / close 方法程序化控制浮层，`visible-change` 事件可监听显隐变化；ESC 或点击外部区域也会关闭。

## API