mirror of
https://gitee.com/element-plus/element-plus.git
synced 2024-12-15 09:50:58 +08:00
55348b30b6
* style: use prettier * style: just prettier format, no code changes * style: eslint fix object-shorthand, prefer-const * style: fix no-void * style: no-console
418 lines
14 KiB
Markdown
418 lines
14 KiB
Markdown
## Dropdown
|
|
|
|
Toggleable menu for displaying lists of links and actions.
|
|
|
|
### Basic usage
|
|
|
|
Hover on the dropdown menu to unfold it for more actions.
|
|
|
|
:::demo The triggering element is rendered by the default `slot`, and the dropdown part is rendered by the `slot` named `dropdown`. By default, dropdown list shows when you hover on the triggering element without having to click it.
|
|
|
|
```html
|
|
<el-dropdown>
|
|
<span class="el-dropdown-link">
|
|
Dropdown List<i class="el-icon-arrow-down el-icon--right"></i>
|
|
</span>
|
|
<template #dropdown>
|
|
<el-dropdown-menu>
|
|
<el-dropdown-item>Action 1</el-dropdown-item>
|
|
<el-dropdown-item>Action 2</el-dropdown-item>
|
|
<el-dropdown-item>Action 3</el-dropdown-item>
|
|
<el-dropdown-item disabled>Action 4</el-dropdown-item>
|
|
<el-dropdown-item divided>Action 5</el-dropdown-item>
|
|
</el-dropdown-menu>
|
|
</template>
|
|
</el-dropdown>
|
|
|
|
<style>
|
|
.el-dropdown-link {
|
|
cursor: pointer;
|
|
color: #409eff;
|
|
}
|
|
.el-icon-arrow-down {
|
|
font-size: 12px;
|
|
}
|
|
</style>
|
|
```
|
|
|
|
:::
|
|
|
|
### Triggering element
|
|
|
|
Use the button to trigger the dropdown list.
|
|
|
|
:::demo Use `split-button` to split the triggering element into a button group with the left button being a normal button and right one the actual triggering target. If you wanna insert a separator line between item three and item four, just add a class `divider` to item four.
|
|
|
|
```html
|
|
<el-dropdown>
|
|
<el-button type="primary">
|
|
Dropdown List<i class="el-icon-arrow-down el-icon--right"></i>
|
|
</el-button>
|
|
<template #dropdown>
|
|
<el-dropdown-menu>
|
|
<el-dropdown-item>Action 1</el-dropdown-item>
|
|
<el-dropdown-item>Action 2</el-dropdown-item>
|
|
<el-dropdown-item>Action 3</el-dropdown-item>
|
|
<el-dropdown-item>Action 4</el-dropdown-item>
|
|
<el-dropdown-item>Action 5</el-dropdown-item>
|
|
</el-dropdown-menu>
|
|
</template>
|
|
</el-dropdown>
|
|
<el-dropdown split-button type="primary" @click="handleClick">
|
|
Dropdown List
|
|
<template #dropdown>
|
|
<el-dropdown-menu>
|
|
<el-dropdown-item>Action 1</el-dropdown-item>
|
|
<el-dropdown-item>Action 2</el-dropdown-item>
|
|
<el-dropdown-item>Action 3</el-dropdown-item>
|
|
<el-dropdown-item>Action 4</el-dropdown-item>
|
|
<el-dropdown-item>Action 5</el-dropdown-item>
|
|
</el-dropdown-menu>
|
|
</template>
|
|
</el-dropdown>
|
|
|
|
<style>
|
|
.el-dropdown {
|
|
vertical-align: top;
|
|
}
|
|
.el-dropdown + .el-dropdown {
|
|
margin-left: 15px;
|
|
}
|
|
.el-icon-arrow-down {
|
|
font-size: 12px;
|
|
}
|
|
</style>
|
|
|
|
<script>
|
|
export default {
|
|
methods: {
|
|
handleClick() {
|
|
alert('button click')
|
|
},
|
|
},
|
|
}
|
|
</script>
|
|
<!--
|
|
<setup>
|
|
|
|
import { defineComponent } from 'vue';
|
|
|
|
export default defineComponent({
|
|
setup() {
|
|
const handleClick = () => {
|
|
alert('button click');
|
|
};
|
|
return {
|
|
handleClick,
|
|
};
|
|
},
|
|
});
|
|
|
|
</setup>
|
|
-->
|
|
```
|
|
|
|
:::
|
|
|
|
### How to trigger
|
|
|
|
Click the triggering element or hover on it.
|
|
|
|
:::demo Use the attribute `trigger`. By default, it is `hover`.
|
|
|
|
```html
|
|
<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<i class="el-icon-arrow-down el-icon--right"></i>
|
|
</span>
|
|
<template #dropdown>
|
|
<el-dropdown-menu>
|
|
<el-dropdown-item icon="el-icon-plus">Action 1</el-dropdown-item>
|
|
<el-dropdown-item icon="el-icon-circle-plus"
|
|
>Action 2</el-dropdown-item
|
|
>
|
|
<el-dropdown-item icon="el-icon-circle-plus-outline"
|
|
>Action 3</el-dropdown-item
|
|
>
|
|
<el-dropdown-item icon="el-icon-check">Action 4</el-dropdown-item>
|
|
<el-dropdown-item icon="el-icon-circle-check"
|
|
>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<i class="el-icon-arrow-down el-icon--right"></i>
|
|
</span>
|
|
<template #dropdown>
|
|
<el-dropdown-menu>
|
|
<el-dropdown-item icon="el-icon-plus">Action 1</el-dropdown-item>
|
|
<el-dropdown-item icon="el-icon-circle-plus"
|
|
>Action 2</el-dropdown-item
|
|
>
|
|
<el-dropdown-item icon="el-icon-circle-plus-outline"
|
|
>Action 3</el-dropdown-item
|
|
>
|
|
<el-dropdown-item icon="el-icon-check">Action 4</el-dropdown-item>
|
|
<el-dropdown-item icon="el-icon-circle-check"
|
|
>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<i class="el-icon-arrow-down el-icon--right"></i>
|
|
</span>
|
|
<template #dropdown>
|
|
<el-dropdown-menu>
|
|
<el-dropdown-item icon="el-icon-plus">Action 1</el-dropdown-item>
|
|
<el-dropdown-item icon="el-icon-circle-plus"
|
|
>Action 2</el-dropdown-item
|
|
>
|
|
<el-dropdown-item icon="el-icon-circle-plus-outline"
|
|
>Action 3</el-dropdown-item
|
|
>
|
|
<el-dropdown-item icon="el-icon-check">Action 4</el-dropdown-item>
|
|
<el-dropdown-item icon="el-icon-circle-check"
|
|
>Action 5</el-dropdown-item
|
|
>
|
|
</el-dropdown-menu>
|
|
</template>
|
|
</el-dropdown>
|
|
</el-col>
|
|
</el-row>
|
|
|
|
<style>
|
|
.el-dropdown-link {
|
|
cursor: pointer;
|
|
color: #409eff;
|
|
}
|
|
.el-icon-arrow-down {
|
|
font-size: 12px;
|
|
}
|
|
.demonstration {
|
|
display: block;
|
|
color: var(--el-text-color-secondary);
|
|
font-size: 14px;
|
|
margin-bottom: 20px;
|
|
}
|
|
</style>
|
|
```
|
|
|
|
:::
|
|
|
|
### Menu hiding behavior
|
|
|
|
Use `hide-on-click` to define if menu closes on clicking.
|
|
|
|
:::demo By default menu will close when you click on menu items, and it can be turned off by setting hide-on-click to false.
|
|
|
|
```html
|
|
<el-dropdown :hide-on-click="false">
|
|
<span class="el-dropdown-link">
|
|
Dropdown List<i class="el-icon-arrow-down el-icon--right"></i>
|
|
</span>
|
|
<template #dropdown>
|
|
<el-dropdown-menu>
|
|
<el-dropdown-item>Action 1</el-dropdown-item>
|
|
<el-dropdown-item>Action 2</el-dropdown-item>
|
|
<el-dropdown-item>Action 3</el-dropdown-item>
|
|
<el-dropdown-item disabled>Action 4</el-dropdown-item>
|
|
<el-dropdown-item divided>Action 5</el-dropdown-item>
|
|
</el-dropdown-menu>
|
|
</template>
|
|
</el-dropdown>
|
|
|
|
<style>
|
|
.el-dropdown-link {
|
|
cursor: pointer;
|
|
color: #409eff;
|
|
}
|
|
.el-icon-arrow-down {
|
|
font-size: 12px;
|
|
}
|
|
</style>
|
|
```
|
|
|
|
:::
|
|
|
|
### Command event
|
|
|
|
Clicking each dropdown item fires an event whose parameter is assigned by each item.
|
|
|
|
:::demo
|
|
|
|
```html
|
|
<el-dropdown @command="handleCommand">
|
|
<span class="el-dropdown-link">
|
|
Dropdown List<i class="el-icon-arrow-down el-icon--right"></i>
|
|
</span>
|
|
<template #dropdown>
|
|
<el-dropdown-menu>
|
|
<el-dropdown-item command="a">Action 1</el-dropdown-item>
|
|
<el-dropdown-item command="b">Action 2</el-dropdown-item>
|
|
<el-dropdown-item command="c">Action 3</el-dropdown-item>
|
|
<el-dropdown-item command="d" disabled>Action 4</el-dropdown-item>
|
|
<el-dropdown-item command="e" divided>Action 5</el-dropdown-item>
|
|
</el-dropdown-menu>
|
|
</template>
|
|
</el-dropdown>
|
|
|
|
<style>
|
|
.el-dropdown-link {
|
|
cursor: pointer;
|
|
color: #409eff;
|
|
}
|
|
.el-icon-arrow-down {
|
|
font-size: 12px;
|
|
}
|
|
</style>
|
|
|
|
<script>
|
|
export default {
|
|
methods: {
|
|
handleCommand(command) {
|
|
this.$message('click on item ' + command)
|
|
},
|
|
},
|
|
}
|
|
</script>
|
|
<!--
|
|
<setup>
|
|
|
|
import { defineComponent } from 'vue';
|
|
import { ElMessage } from 'element-plus';
|
|
|
|
export default defineComponent({
|
|
setup() {
|
|
|
|
const handleCommand = (command) => {
|
|
ElMessage(`click on item ${command}`);
|
|
};
|
|
return {
|
|
handleCommand,
|
|
};
|
|
},
|
|
});
|
|
|
|
</setup>
|
|
-->
|
|
```
|
|
|
|
:::
|
|
|
|
### Sizes
|
|
|
|
Besides default size, Dropdown component provides three additional sizes for you to choose among different scenarios.
|
|
|
|
:::demo Use attribute `size` to set additional sizes with `medium`, `small` or `mini`.
|
|
|
|
```html
|
|
<el-dropdown split-button type="primary">
|
|
Default
|
|
<template #dropdown>
|
|
<el-dropdown-menu>
|
|
<el-dropdown-item>Action 1</el-dropdown-item>
|
|
<el-dropdown-item>Action 2</el-dropdown-item>
|
|
<el-dropdown-item>Action 3</el-dropdown-item>
|
|
<el-dropdown-item>Action 4</el-dropdown-item>
|
|
</el-dropdown-menu>
|
|
</template>
|
|
</el-dropdown>
|
|
|
|
<el-dropdown size="medium" split-button type="primary">
|
|
Medium
|
|
<template #dropdown>
|
|
<el-dropdown-menu>
|
|
<el-dropdown-item>Action 1</el-dropdown-item>
|
|
<el-dropdown-item>Action 2</el-dropdown-item>
|
|
<el-dropdown-item>Action 3</el-dropdown-item>
|
|
<el-dropdown-item>Action 4</el-dropdown-item>
|
|
</el-dropdown-menu>
|
|
</template>
|
|
</el-dropdown>
|
|
|
|
<el-dropdown size="small" split-button type="primary">
|
|
Small
|
|
<template #dropdown>
|
|
<el-dropdown-menu>
|
|
<el-dropdown-item>Action 1</el-dropdown-item>
|
|
<el-dropdown-item>Action 2</el-dropdown-item>
|
|
<el-dropdown-item>Action 3</el-dropdown-item>
|
|
<el-dropdown-item>Action 4</el-dropdown-item>
|
|
</el-dropdown-menu>
|
|
</template>
|
|
</el-dropdown>
|
|
|
|
<el-dropdown size="mini" split-button type="primary">
|
|
Mini
|
|
<template #dropdown>
|
|
<el-dropdown-menu>
|
|
<el-dropdown-item>Action 1</el-dropdown-item>
|
|
<el-dropdown-item>Action 2</el-dropdown-item>
|
|
<el-dropdown-item>Action 3</el-dropdown-item>
|
|
<el-dropdown-item>Action 4</el-dropdown-item>
|
|
</el-dropdown-menu>
|
|
</template>
|
|
</el-dropdown>
|
|
```
|
|
|
|
:::
|
|
|
|
### Dropdown Attributes
|
|
|
|
| Attribute | Description | Type | Accepted Values | Default |
|
|
| ------------- | ---------------------------------------------------------------------------------------------------- | --------------- | ---------------------------------------------------- | ------- |
|
|
| type | menu button type, refer to `Button` Component, only works when `split-button` is true | string | — | — |
|
|
| size | menu size, also works on the split button | string | medium / small / mini | — |
|
|
| max-height | the max height of menu | string / number | — | — |
|
|
| split-button | whether a button group is displayed | boolean | — | false |
|
|
| disabled | Whether to disable | boolean | — | false |
|
|
| placement | placement of pop menu | string | top/top-start/top-end/bottom/bottom-start/bottom-end | bottom |
|
|
| trigger | how to trigger | string | hover/click/contextmenu | hover |
|
|
| hide-on-click | whether to hide menu after clicking menu-item | boolean | — | true |
|
|
| show-timeout | Delay time before show a dropdown (only works when trigger is `hover`) | number | — | 250 |
|
|
| hide-timeout | Delay time before hide a dropdown (only works when trigger is `hover`) | number | — | 150 |
|
|
| tabindex | [tabindex](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex) of Dropdown | number | — | 0 |
|
|
|
|
### Dropdown Slots
|
|
|
|
| Name | Description |
|
|
| -------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| — | content of Dropdown. Notice: Must be a valid html dom element (ex. `<span>, <button> etc.`) or `el-component`, to attach the trigger listener |
|
|
| dropdown | content of the Dropdown Menu, usually a `<el-dropdown-menu>` element |
|
|
|
|
### Dropdown Events
|
|
|
|
| Event Name | Description | Parameters |
|
|
| -------------- | ----------------------------------------------------------------- | --------------------------------------------- |
|
|
| click | if `split-button` is `true`, triggers when left button is clicked | — |
|
|
| command | triggers when a dropdown item is clicked | the command dispatched from the dropdown item |
|
|
| visible-change | triggers when the dropdown appears/disappears | true when it appears, and false otherwise |
|
|
|
|
### Dropdown-Menu Slots
|
|
|
|
| Name | Description |
|
|
| ---- | ------------------------ |
|
|
| — | content of Dropdown Menu |
|
|
|
|
### Dropdown-Item Attributes
|
|
|
|
| Attribute | Description | Type | Accepted Values | Default |
|
|
| --------- | ----------------------------------------------------------- | -------------------- | --------------- | ------- |
|
|
| command | a command to be dispatched to Dropdown's `command` callback | string/number/object | — | — |
|
|
| disabled | whether the item is disabled | boolean | — | false |
|
|
| divided | whether a divider is displayed | boolean | — | false |
|
|
| icon | icon class name | string | — | — |
|