Dropdown 下拉菜单

将动作或菜单折叠到下拉菜单中。

基础用法

鼠标悬停在下拉菜单上以展开更多操作。

触发元素由默认 slot 渲染，下拉部分由名为 dropdown 的 slot 渲染。默认情况下，只需将鼠标悬停在触发元素上即可显示下拉列表，无需点击。

位置

支持 6 个弹出位置。

设置 placement 属性可以让下拉菜单在不同的位置弹出。

vue

<template>
  <div class="flex flex-wrap items-center gap-4">
    <el-dropdown placement="top-start">
      <el-button> topStart </el-button>
      <template #dropdown>
        <el-dropdown-menu>
          <el-dropdown-item>The Action 1st</el-dropdown-item>
          <el-dropdown-item>The Action 2nd</el-dropdown-item>
          <el-dropdown-item>The Action 3rd</el-dropdown-item>
        </el-dropdown-menu>
      </template>
    </el-dropdown>
    <el-dropdown placement="top">
      <el-button> top </el-button>
      <template #dropdown>
        <el-dropdown-menu>
          <el-dropdown-item>The Action 1st</el-dropdown-item>
          <el-dropdown-item>The Action 2nd</el-dropdown-item>
          <el-dropdown-item>The Action 3rd</el-dropdown-item>
        </el-dropdown-menu>
      </template>
    </el-dropdown>
    <el-dropdown placement="top-end">
      <el-button> topEnd </el-button>
      <template #dropdown>
        <el-dropdown-menu>
          <el-dropdown-item>The Action 1st</el-dropdown-item>
          <el-dropdown-item>The Action 2nd</el-dropdown-item>
          <el-dropdown-item>The Action 3rd</el-dropdown-item>
        </el-dropdown-menu>
      </template>
    </el-dropdown>
    <el-dropdown placement="bottom-start">
      <el-button> bottomStart </el-button>
      <template #dropdown>
        <el-dropdown-menu>
          <el-dropdown-item>The Action 1st</el-dropdown-item>
          <el-dropdown-item>The Action 2nd</el-dropdown-item>
          <el-dropdown-item>The Action 3rd</el-dropdown-item>
        </el-dropdown-menu>
      </template>
    </el-dropdown>
    <el-dropdown placement="bottom">
      <el-button> bottom </el-button>
      <template #dropdown>
        <el-dropdown-menu>
          <el-dropdown-item>The Action 1st</el-dropdown-item>
          <el-dropdown-item>The Action 2nd</el-dropdown-item>
          <el-dropdown-item>The Action 3rd</el-dropdown-item>
        </el-dropdown-menu>
      </template>
    </el-dropdown>
    <el-dropdown placement="bottom-end">
      <el-button> bottomEnd </el-button>
      <template #dropdown>
        <el-dropdown-menu>
          <el-dropdown-item>The Action 1st</el-dropdown-item>
          <el-dropdown-item>The Action 2nd</el-dropdown-item>
          <el-dropdown-item>The Action 3rd</el-dropdown-item>
        </el-dropdown-menu>
      </template>
    </el-dropdown>
  </div>
</template>

触发对象

可使用按钮触发下拉列表。

设置 split-button 属性让触发对象生成一个按钮组，左边是普通按钮，右边是下拉菜单。如果你希望在第三项和第四项之间插入一条分割线，只需在第四项添加 divided 属性。

触发方式

点击触发对象或悬停在其上。

使用 trigger 属性。默认情况下，它是 hover。

悬停触发

点击触发

右键点击触发

vue

<template>
  <el-row class="block-col-2">
    <el-col :span="8">
      <span class="demonstration">hover to trigger</span>
      <el-dropdown>
        <span class="el-dropdown-link">
          Dropdown List<el-icon class="el-icon--right"><arrow-down /></el-icon>
        </span>
        <template #dropdown>
          <el-dropdown-menu>
            <el-dropdown-item :icon="Plus">Action 1</el-dropdown-item>
            <el-dropdown-item :icon="CirclePlusFilled">
              Action 2
            </el-dropdown-item>
            <el-dropdown-item :icon="CirclePlus">Action 3</el-dropdown-item>
            <el-dropdown-item :icon="Check">Action 4</el-dropdown-item>
            <el-dropdown-item :icon="CircleCheck">Action 5</el-dropdown-item>
          </el-dropdown-menu>
        </template>
      </el-dropdown>
    </el-col>
    <el-col :span="8">
      <span class="demonstration">click to trigger</span>
      <el-dropdown trigger="click">
        <span class="el-dropdown-link">
          Dropdown List<el-icon class="el-icon--right"><arrow-down /></el-icon>
        </span>
        <template #dropdown>
          <el-dropdown-menu>
            <el-dropdown-item :icon="Plus">Action 1</el-dropdown-item>
            <el-dropdown-item :icon="CirclePlusFilled">
              Action 2
            </el-dropdown-item>
            <el-dropdown-item :icon="CirclePlus">Action 3</el-dropdown-item>
            <el-dropdown-item :icon="Check">Action 4</el-dropdown-item>
            <el-dropdown-item :icon="CircleCheck">Action 5</el-dropdown-item>
          </el-dropdown-menu>
        </template>
      </el-dropdown>
    </el-col>
    <el-col :span="8">
      <span class="demonstration">right click to trigger</span>
      <el-dropdown trigger="contextmenu">
        <span class="el-dropdown-link">
          Dropdown List<el-icon class="el-icon--right"><arrow-down /></el-icon>
        </span>
        <template #dropdown>
          <el-dropdown-menu>
            <el-dropdown-item :icon="Plus">Action 1</el-dropdown-item>
            <el-dropdown-item :icon="CirclePlusFilled">
              Action 2
            </el-dropdown-item>
            <el-dropdown-item :icon="CirclePlus">Action 3</el-dropdown-item>
            <el-dropdown-item :icon="Check">Action 4</el-dropdown-item>
            <el-dropdown-item :icon="CircleCheck">Action 5</el-dropdown-item>
          </el-dropdown-menu>
        </template>
      </el-dropdown>
    </el-col>
  </el-row>
</template>

<script lang="ts" setup>
import {
  ArrowDown,
  Check,
  CircleCheck,
  CirclePlus,
  CirclePlusFilled,
  Plus,
} from '@element-plus/icons-vue'
</script>

<style scoped>
.block-col-2 .demonstration {
  display: block;
  color: var(--el-text-color-secondary);
  font-size: 14px;
  margin-bottom: 20px;
}

.block-col-2 .el-dropdown-link {
  display: flex;
  align-items: center;
}
</style>

使用 hide-on-click 来定义菜单在点击后是否关闭。

默认情况下，点击菜单项后菜单将关闭，可以通过将 hide-on-click 设置为 false 来关闭此行为。

指令事件

点击每个下拉项都会触发一个事件，该参数由每个项目分配。

你可以通过手动使用 handleOpen 或 handleClose 来打开或关闭下拉菜单。

打开（关闭）下拉列表 2 将关闭（打开）下拉列表 1。

尺寸

除了默认尺寸外，下拉菜单组件还提供了三种可选尺寸，以便在不同场景下使用。

使用 size 属性来设置不同大小的文本，可选值为 large, default 或 small。

虚拟触发 2.11.3

有时我们想在其他触发元素上渲染下拉菜单，我们可以将触发器和内容分开。

右键点击

名称	描述	类型	默认值
type	菜单按钮类型，参考 `Button` 组件，仅在 `split-button` 为 true 时有效	`枚举`	''
size	菜单尺寸，同时也对分割按钮生效	`枚举`	''
button-props	按钮组件的属性，参考按钮属性	`object`	—
max-height	菜单的最大高度	`string` / `number`	''
split-button	是否显示按钮组	`boolean`	false
disabled	是否禁用	`boolean`	false
placement	弹出菜单的位置	`枚举`	bottom
effect	Tooltip 的主题，内置主题：`dark` / `light`	`enum` / `string`	light
trigger	触发方式	`enum` / `array`	悬浮时
trigger-keys 2.9.1	指定键盘上的哪些键在按下时可以触发	`array`	`['Enter', 'Space', 'ArrowDown', 'NumpadEnter']`
virtual-triggering 2.11.3	指示是否启用虚拟触发	`boolean`	—
virtual-ref 2.11.3	指示下拉菜单挂载的参考元素	`HTMLElement`	—
hide-on-click	点击菜单项后是否隐藏菜单	`boolean`	true
show-arrow 2.11.3	tooltip 内容是否包含箭头	`boolean`	true
show-timeout	显示下拉菜单前的延迟时间（仅在 trigger 为 `hover` 时有效）	`number`	150
hide-timeout	隐藏下拉菜单前的延迟时间（仅在 trigger 为 `hover` 时有效）	`number`	150
role	下拉菜单的 ARIA role 属性。根据使用场景，你可能需要将其更改为 'navigation'	`枚举`	menu
tabindex	Dropdown 的 tabindex	`number` / `string`	0
popper-class	下拉菜单的自定义类名	`string` / `object`	''
popper-style 2.11.5	下拉菜单的自定义样式	`string` / `object`	—
popper-options	popper.js 参数	`object`	`{modifiers: [{name: 'computeStyles',options: {gpuAcceleration: false}}]}`
teleported 2.2.20	下拉弹出框是否插入至 body 元素	`boolean`	true
append-to 2.13.0	下拉内容追加到哪个元素	`CSSSelector` / `HTMLElement`	—
persistent 2.9.5	当下拉菜单不活跃且 `persistent` 为 `false` 时，下拉菜单将被销毁	`boolean`	true

名称	描述	子标签
default	Dropdown 的内容。注意：必须是有效的 HTML DOM 元素（例如 `<span>, <button> 等`）或 `el-component`，以便绑定触发监听器	—
dropdown	下拉菜单的内容，通常是一个 `<el-dropdown-menu>` 元素	Dropdown-Menu

名称	描述	类型
click	如果 `split-button` 为 `true`，则在点击左侧按钮时触发	`Function`
command	点击下拉项时触发，参数是下拉项派发的 command	`Function`
visible-change	下拉菜单出现/消失时触发，出现时参数为 true，否则为 false	`Function`

方法	描述	类型
handleOpen	打开下拉菜单	`Function`
handleClose	关闭下拉菜单	`Function`

名称	描述	子标签
default	下拉菜单的内容	Dropdown-Item

名称	描述	类型	默认值
command	派发到 Dropdown 的 `command` 回调的指令	`string` / `number` / `object`	—
disabled	该项是否被禁用	`boolean`	false
divided	是否显示分割线	`boolean`	false
icon	自定义图标	`string` / `Component`	—