Dropdown 下拉菜单
将动作或菜单折叠到下拉菜单中。
基础用法
悬停在下拉菜单上以展开更多操作。
通过组件 slot 来设置下拉触发的元素以及需要通过具名 slot 为 dropdown 来设置下拉菜单。默认情况下，只需要悬停在触发菜单的元素上即可，无需点击也会显示下拉菜单。
export function DropdownBasicUsage() { return ( <ElDropdown menu={<Actions />}> <DropdownLink> Dropdown List <ElIcon className="el-icon--right"> <ArrowDown /> </ElIcon> </DropdownLink> </ElDropdown> );}
位置
支持 6 个位置。
设置 placement 属性，使下拉菜单出现在不同位置。
export function DropdownPlacements() { return ( <div className={`${styles.row} ${styles.gap4}`}> {([ ["top-start", "topStart"], ["top", "top"], ["top-end", "topEnd"], ["bottom-start", "bottomStart"], ["bottom", "bottom"], ["bottom-end", "bottomEnd"], ] as const).map(([placement, label]) => ( <ElDropdown key={placement} placement={placement} menu={<Actions />}> <ElButton>{label}</ElButton> </ElDropdown> ))} </div> );}
触发对象
可使用按钮触发下拉菜单。
设置 split-button 属性来让触发下拉元素呈现为按钮组，左边是功能按钮，右边是触发下拉菜单的按钮，设置为 true 即可。如果你想要在第三和第四个选项之间添加一个分隔符，你只需要为第四个选项添加一个 divided 的属性。
export function DropdownTriggeringElement() { return ( <div className={styles.row}> <ElDropdown menu={<Actions />}> <ElButton type="primary"> Dropdown List <ElIcon className="el-icon--right"> <ArrowDown /> </ElIcon> </ElButton> </ElDropdown> <ElDropdown splitButton type="primary" className={styles.ml15} onButtonClick={() => message("button click")} menu={<Actions />} > <>Dropdown List</> </ElDropdown> </div> );}
触发方式
可以配置点击激活或者悬停激活。
将 trigger 属性设置为 click 即可，默认为 hover。
export function DropdownHowToTrigger() { const triggers = [ ["hover", "hover to trigger"], ["click", "click to trigger"], ["contextmenu", "right click to trigger"], ] as const; return ( <ElRow className={styles.columns}> {triggers.map(([trigger, label]) => ( <ElCol key={trigger} span={8}> <span className={styles.demonstration}>{label}</span> <ElDropdown trigger={trigger} menu={<IconActions />}> <span className={`el-dropdown-link ${styles.linkPlain}`}> Dropdown List <ElIcon className="el-icon--right"> <ArrowDown /> </ElIcon> </span> </ElDropdown> </ElCol> ))} </ElRow> );}
菜单隐藏方式
可以通过 hide-on-click 属性来配置。
下拉菜单默认在点击菜单项后会被隐藏，将 hide-on-click 属性设置为 false 可以关闭此功能。
export function DropdownMenuHidingBehavior() { return ( <ElDropdown hideOnClick={false} menu={<Actions dividedLast />}> <DropdownLink> Dropdown List <ElIcon className="el-icon--right"> <ArrowDown /> </ElIcon> </DropdownLink> </ElDropdown> );}
指令事件
点击菜单项后会触发事件，用户可以通过相应的菜单项 key 进行不同的操作。
export function DropdownCommandEvent() { return ( <ElDropdown onCommand={(command) => message(`click on item ${String(command)}`)} menu={ <ElDropdownMenu> <ElDropdownItem command="a">Action 1</ElDropdownItem> <ElDropdownItem command="b">Action 2</ElDropdownItem> <ElDropdownItem command="c">Action 3</ElDropdownItem> <ElDropdownItem command="d" disabled>Action 4</ElDropdownItem> <ElDropdownItem command="e" divided>Action 5</ElDropdownItem> </ElDropdownMenu> } > <DropdownLink> Dropdown List <ElIcon className="el-icon--right"> <ArrowDown /> </ElIcon> </DropdownLink> </ElDropdown> );}
下拉方法
您可以手动使用 手动打开 或 手动关闭下拉菜单以打开或关闭
open(close) the Dropdown list2 will close(open) the Dropdown List1.
Dropdown List1
Dropdown List2
export function DropdownMethods() { const dropdownRef = useRef<DropdownExpose | null>(null); return ( <> <div className={styles.methods}> <p>open(close) the Dropdown list2 will close(open) the Dropdown List1.</p> </div> <div className={styles.showButton}> <ElButton onClick={() => dropdownRef.current?.handleOpen()}>show</ElButton> </div> <ElDropdown ref={dropdownRef} trigger="contextmenu" className={styles.mr30} menu={<Actions />} > <span className={`el-dropdown-link ${styles.link}`}>Dropdown List1</span> </ElDropdown> <ElDropdown trigger="contextmenu" menu={<Actions />} onVisibleChange={(visible) => { if (visible) dropdownRef.current?.handleClose(); else dropdownRef.current?.handleOpen(); }} > <span className={`el-dropdown-link ${styles.link}`}>Dropdown List2</span> </ElDropdown> </> );}
尺寸
Dropdown 组件提供除了默认值以外的三种尺寸，可以在不同场景下选择合适的尺寸。
使用 size 属性配置尺寸，可选的尺寸大小有: large, default 或 small
export function DropdownSizes() { return ( <> <ElDropdown size="large" splitButton type="primary" menu={<Actions />}> <>Large</> </ElDropdown> <ElDropdown splitButton type="primary" className={styles.ml15} menu={<Actions />} > <>Default</> </ElDropdown> <ElDropdown size="small" splitButton type="primary" className={styles.ml15} menu={<Actions />} > <>Small</> </ElDropdown> </> );}
虚拟触发2.11.3
有时候我们想把 dropdown 的触发元素放在别的地方，而不需要写在一起，这时候就可以使用虚拟触发。
export function DropdownVirtualTrigger() { const dropdownRef = useRef<DropdownExpose | null>(null); const positionRef = useRef({ x: 0, y: 0 }); const [virtualRef] = useState(() => ({ getBoundingClientRect: () => new DOMRect(positionRef.current.x, positionRef.current.y, 0, 0), })); return ( <> <div onClick={() => dropdownRef.current?.handleClose()} onContextMenu={(event) => { const { clientX, clientY } = event; positionRef.current = { x: clientX, y: clientY }; event.preventDefault(); dropdownRef.current?.handleOpen(); }} > <ElCard className={styles.virtualCard} bodyClass="card-body"> Right click </ElCard> </div> <ElDropdown ref={dropdownRef} virtualTriggering virtualRef={virtualRef} showArrow={false} trigger="contextmenu" placement="bottom-start" menu={<IconActions />} /> </> );}
Dropdown API
Dropdown Attributes
| 属性名 | 说明 | 类型 | 默认值 |
|---|
| menu | 菜单内容，即 ElDropdownMenu | ReactElement | — |
| trigger | 触发方式，可传数组组合 | enum / array | hover |
| trigger-keys | 键盘触发键 | array | — |
| placement | 弹出位置 | enum | bottom |
| effect | 主题 | enum | light |
| split-button | 是否使用分裂按钮 | boolean | false |
| type | 按钮类型，仅 splitButton 时有效 | string | — |
| size | 尺寸，同时作用于分裂按钮 | enum | — |
| hide-on-click | 点击菜单项后是否关闭 | boolean | true |
| disabled | 是否禁用 | boolean | false |
| show-arrow | 是否显示箭头 | boolean | true |
| show-timeout | hover 触发的显示延迟 | number | 150 |
| hide-timeout | hover 触发的隐藏延迟 | number | 150 |
| max-height | 弹层最大高度 | string / number | — |
| role | 弹层 ARIA role | enum | menu |
| tabindex | 触发元素的 tabindex | number / string | 0 |
| popper-class / popper-style | 弹层类名 / 样式 | string / object | — |
| teleported | 是否挂载到 appendTo | boolean | true |
| append-to | 挂载目标 | string / HTMLElement | — |
| persistent | 不可见时是否保留 DOM | boolean | true |
| virtual-triggering | 是否启用虚拟触发 | boolean | false |
| virtual-ref | 虚拟触发参照物 | HTMLElement / object | — |
| visible | 受控显示状态 | boolean | — |
| z-index | 层级 | number | — |
Dropdown Slots
| 插槽名 | 说明 | React 写法 |
|---|
| default | 触发元素，必须是可接收事件的元素 | children |
| dropdown | 菜单内容，通常是 ElDropdownMenu | menu 属性 |
Dropdown Events
| 事件名 | 说明 | 参数 |
|---|
| onCommand | 点击菜单项 | Function |
| onButtonClick | 分裂按钮左半部分点击 | Function |
| onVisibleChange | 显隐状态变化 | Function |
Dropdown Exposes
| 方法 | 说明 |
|---|
| handleOpen() | 打开菜单 |
| handleClose() | 关闭菜单 |
| handleToggle() | 切换菜单显隐 |
| 插槽名 | 说明 | React 写法 |
|---|
| default | 菜单项列表 | children |
DropdownItem Attributes
| 属性名 | 说明 | 类型 | 默认值 |
|---|
| command | 指令，点击时传给 onCommand | string / number / object | — |
| disabled | 是否禁用 | boolean | false |
| divided | 是否显示分割线 | boolean | false |
| icon | 图标 | ReactNode | — |
DropdownItem Slots
| 插槽名 | 说明 | React 写法 |
|---|
| default | 菜单项内容 | children |
| icon | 自定义图标，会覆盖 icon 属性 | icon 属性 |
