Dropdown 下拉框 | semi-design-vue

代码演示

如何引入

jsx

import { Dropdown } from '@kousum/semi-ui-vue';

基本用法

demoApp.vue

demo.tsx

tsconfig.json

Import Map

xxxxxxxxxx
 
import { Dropdown, Tag } from '@kousum/semi-ui-vue';
​
function Demo() {
    return (
        <Dropdown
            render={
                <Dropdown.Menu>
                    <Dropdown.Item>Menu Item 1</Dropdown.Item>
                    <Dropdown.Item>Menu Item 2</Dropdown.Item>
                    <Dropdown.Item>Menu Item 3</Dropdown.Item>
                </Dropdown.Menu>
            }
        >
            <Tag>Hover Me</Tag>
        </Dropdown>
    );
}
​
export default Demo

Show Error

Auto Save

嵌套使用

用户可以对 Dropdown 进行嵌套使用，此类情况适合具有多个子级选项的情况。

demoApp.vue

demo.tsx

tsconfig.json

Import Map

xxxxxxxxxx
 
import { Dropdown, Tag } from '@kousum/semi-ui-vue';
​
const subDropdown = <Dropdown.Menu>
  <Dropdown.Item>Menu Item 1</Dropdown.Item>
  <Dropdown.Item>Menu Item 2</Dropdown.Item>
  <Dropdown.Item>Menu Item 3</Dropdown.Item>
</Dropdown.Menu>;
function Demo() {
​
    return (
        <div style={{ margin: '100px' }}>
            <Dropdown
                render={
                    <Dropdown.Menu>
                        <Dropdown position={'rightTop'} render={subDropdown}>
                            <Dropdown.Item>Menu Item 1</Dropdown.Item>
                        </Dropdown>
                        <Dropdown position={'leftTop'} render={subDropdown}>
                            <Dropdown.Item>Menu Item 2</Dropdown.Item>
                        </Dropdown>
                        <Dropdown.Item>Menu Item 3</Dropdown.Item>
                    </Dropdown.Menu>
                }
            >
                <Tag>Hover Me</Tag>
            </Dropdown>
        </div>
    );
}
​
export default Demo

Show Error

Auto Save

元素属性

通过设置 disabled 可以禁用某个选项
通过给 Dropdown.Item 配置 type，可以展示不同颜色的文本
通过在 Dropdown.Item 上设置 icon 可以快速配置图标

demoApp.vue

demo.tsx

tsconfig.json

Import Map

xxxxxxxxxx
 
import { Dropdown, Button } from '@kousum/semi-ui-vue';
import { IconBox, IconSimilarity, IconSetting, IconForward, IconColorPalette, IconRefresh, IconSearch, IconBranch } from '@kousum/semi-icons-vue';
​
function Demo() {
    return (
        <div>
            <Dropdown
                trigger="custom"
                position="bottomLeft"
                visible
                render={
                    <Dropdown.Menu>
                        <Dropdown.Item icon={<IconBox />}>Menu Item 1</Dropdown.Item>
                        <Dropdown.Item icon={<IconSetting />}>Menu Item 2</Dropdown.Item>
                        <Dropdown.Item disabled icon={<IconForward />}>
                            Menu Item 3
                        </Dropdown.Item>
                        <Dropdown.Item icon={<IconBranch />} type="primary">
                            primary
                        </Dropdown.Item>
                        <Dropdown.Item icon={<IconColorPalette />} type="secondary">
                            secondary
                        </Dropdown.Item>
                        <Dropdown.Item icon={<IconRefresh />} type="tertiary">
                            tertiary
                        </Dropdown.Item>
                        <Dropdown.Item icon={<IconSearch />} type="warning">
                            warning
                        </Dropdown.Item>
                        <Dropdown.Item
                            icon={<IconSimilarity style={{ color: 'var(--semi-color-tertiary)' }} />}
                            type="danger"

Show Error

Auto Save

弹出位置

支持的位置同 Tooltip，常用的是："bottom", "bottomLeft", "bottomRight" 这三种。

demoApp.vue

demo.tsx

tsconfig.json

Import Map

xxxxxxxxxx
 
import { Dropdown, Tag } from '@kousum/semi-ui-vue';
​
function Demo() {
    return (
        <div>
            <Dropdown
                position={'bottom'}
                render={
                    <Dropdown.Menu>
                        <Dropdown.Item>Menu Item 1</Dropdown.Item>
                        <Dropdown.Item>Menu Item 2</Dropdown.Item>
                        <Dropdown.Item>Menu Item 3</Dropdown.Item>
                    </Dropdown.Menu>
                }
            >
                <Tag>Bottom</Tag>
            </Dropdown>
            <br />
            <br />
            <Dropdown
                position={'bottomLeft'}
                render={
                    <Dropdown.Menu>
                        <Dropdown.Item>Menu Item 1</Dropdown.Item>
                        <Dropdown.Item>Menu Item 2</Dropdown.Item>
                        <Dropdown.Item>Menu Item 3</Dropdown.Item>
                    </Dropdown.Menu>
                }
            >
                <Tag>bottomLeft</Tag>
            </Dropdown>
            <br />
            <br />
            <Dropdown
                position={'bottomRight'}

Show Error

Auto Save

触发方式

默认是移入触发，可通过获取焦点(focus)，点击(click)或自定义事件触发菜单展开。
contextMenu方式在 v2.42 后提供

demoApp.vue

demo.tsx

tsconfig.json

Import Map

xxxxxxxxxx
 
import { Dropdown, Tag, Input, Button } from '@kousum/semi-ui-vue';
​
function Demo() {
    return (
        <div>
            <Dropdown
                trigger={'hover'}
                position={'bottomLeft'}
                render={
                    <Dropdown.Menu>
                        <Dropdown.Item>Menu Item 1</Dropdown.Item>
                        <Dropdown.Item>Menu Item 2</Dropdown.Item>
                        <Dropdown.Item>Menu Item 3</Dropdown.Item>
                    </Dropdown.Menu>
                }
            >
                <Tag>Hover me</Tag>
            </Dropdown>
            <br />
            <br />
            <Dropdown
                trigger={'focus'}
                position={'bottomLeft'}
                render={
                    <Dropdown.Menu tabIndex={-1}>
                        <Dropdown.Item>Menu Item 1</Dropdown.Item>
                        <Dropdown.Item>Menu Item 2</Dropdown.Item>
                        <Dropdown.Item>Menu Item 3</Dropdown.Item>
                    </Dropdown.Menu>
                }
            >
                <div style={{
                    border: '1px solid var(--semi-color-border)',
                    borderRadius: 4,
                    height: 36,
                    width: 220

Show Error

Auto Save

触发事件

点击菜单项后可触发不同鼠标事件，支持 onClick，onMouseEnter， onMouseLeave 和 onContextMenu。

demoApp.vue

demo.tsx

tsconfig.json

Import Map

xxxxxxxxxx
 
import { Dropdown, Button, Toast } from '@kousum/semi-ui-vue';
import { defineComponent } from 'vue';
​
​
​
const DropdownEvents = defineComponent(()=>{
​
  function click(value) {
    Toast.info({ content: 'You clicked me!' });
  }
​
  function mouseEnter(value) {
    Toast.info({ content: 'Nice to meet you!' });
  }
​
  function mouseLeave(value) {
    Toast.info({ content: 'See ya!' });
  }
​
  function rightClick(value) {
    Toast.info({ content: 'Right clicked!' });
  }
​
  return ()=> {
    return (
      <Dropdown
        trigger={'click'}
        position={'bottomLeft'}
        render={
          <Dropdown.Menu>
            <Dropdown.Item onClick={click}>1: click me!</Dropdown.Item>
            <Dropdown.Item onMouseenter={mouseEnter}>2: mouse enter</Dropdown.Item>
            <Dropdown.Item onMouseleave={mouseLeave}>3: mouse leave</Dropdown.Item>
            <Dropdown.Item onContextmenu={rightClick}>4: right click</Dropdown.Item>
          </Dropdown.Menu>
        }
      >
        <Button>Click me</Button>
      </Dropdown>
    );
  }

Show Error

Auto Save

分组组合

使用 Dropdown.Divider 可以插入分割线使用 Dropdown.Title 可以插入分组名组合使用 Dropdown.Title、Dropdown.Divider、Dropdown.Item。

demoApp.vue

demo.tsx

tsconfig.json

Import Map

xxxxxxxxxx
 
import { Dropdown, Button, Toast } from '@kousum/semi-ui-vue';
import { defineComponent } from 'vue';
​
​
const Demo = defineComponent(()=>{
​
  return ()=> {
    return (
      <Dropdown
        trigger={'click'}
        showTick
        position={'bottomLeft'}
        render={
          <Dropdown.Menu>
            <Dropdown.Title>分组1</Dropdown.Title>
            <Dropdown.Item type="primary">primary</Dropdown.Item>
            <Dropdown.Item type="secondary">secondary</Dropdown.Item>
            <Dropdown.Divider />
            <Dropdown.Title>分组2</Dropdown.Title>
            <Dropdown.Item type="tertiary">tertiary</Dropdown.Item>
            <Dropdown.Item type="warning" active>
              warning
            </Dropdown.Item>
            <Dropdown.Item type="danger">danger</Dropdown.Item>
          </Dropdown.Menu>
        }
      >
        <Button>Click me</Button>
      </Dropdown>
    );
  }
})
export default Demo

Show Error

Auto Save

Json 用法

可以通过 menu 属性，传入 JSON Array 快速配置出下拉框菜单

demoApp.vue

demo.tsx

tsconfig.json

Import Map

xxxxxxxxxx
 
import { Dropdown, Button } from '@kousum/semi-ui-vue';
​
function DropdownEvents() {
    const menu = [
        { node: 'title', name: '分组1' },
        { node: 'item', name: 'primary1', type: 'primary', onClick: () => console.log('click primary') },
        { node: 'item', name: 'secondary', type: 'secondary' },
        { node: 'divider' },
        { node: 'title', name: '分组2' },
        { node: 'item', name: 'tertiary', type: 'tertiary' },
        { node: 'item', name: 'warning', type: 'warning', active: true },
        { node: 'item', name: 'danger', type: 'danger' },
    ];
    return (
        <Dropdown trigger={'click'} showTick position={'bottomLeft'} menu={menu}>
            <Button>Click me</Button>
        </Dropdown>
    );
}
export default DropdownEvents

Show Error

Auto Save

API 参考

属性	说明	类型	默认值	版本
autoAdjustOverflow	弹出层被遮挡时是否自动调整方向	boolean	true
closeOnEsc	在 trigger 或弹出层按 Esc 键是否关闭面板，受控时不生效	boolean	true ｜ 2.13.0
className	下拉弹层外层样式类名	string
children	触发弹出层的 Trigger 元素	ReactNode
clickToHide	在弹出层内点击时是否自动关闭弹出层	boolean		0.24.0
contentClassName	下拉菜单根元素类名	string
getPopupContainer	指定父级 DOM，弹层将会渲染至该 DOM 中，自定义需要设置 `position: relative` 这会改变浮层 DOM 树位置，但不会改变视图渲染位置。	function():HTMLElement	() => document.body
keepDOM	关闭时是否保留内部组件 DOM 不销毁	boolean	false	2.31.0
margin	弹出层计算溢出时的增加的冗余值，详见issue#549，作用同 Tooltip margin	number\|object		2.25.0
mouseEnterDelay	鼠标移入 Trigger 后，延迟显示的时间，单位毫秒（仅当 trigger 为 hover/focus 时生效）	number	50
mouseLeaveDelay	鼠标移出弹出层后，延迟消失的时间，单位毫秒（仅当 trigger 为 hover/focus 时生效）	number	50
menu	通过传入 JSON Array 来快速配置 Dropdown 内容	Array<DropdownMenuItem>	[]	1.12.0
position	弹出菜单的位置，常用："bottom", "bottomLeft", "bottomRight"，更多详见Tooltip 位置	string	"bottom"
render	弹出层的内容，由 `Dropdown.Menu` 及 `Dropdown.Item`、`Dropdown.Title` 构成	ReactNode
rePosKey	可以更新该项值手动触发弹出层的重新定位	string \| number
spacing	弹出层与 Trigger 元素（即 Dropdown children）的距离，单位 px	number	4
style	弹出层内联样式	object
showTick	是否自动在 active 的 Dropdown.Item 项左侧展示表示选中的勾	boolean	false	0.26.0
stopPropagation	是否阻止弹出层上的点击事件冒泡	boolean	false	0.34.0
trigger	触发下拉的行为，可选 "hover", "focus", "click", "custom", "contextMenu"(v2.42后提供)	string	"hover"
visible	是否显示菜单，需配合 trigger custom 使用	boolean	无
zIndex	弹出层 z-index 值	number	1050
onClickOutSide	当弹出层处于展示状态，点击非Children、非弹出层内部区域时的回调（仅trigger为custom、click时有效）	function(e:event)		2.1.0
onEscKeyDown	在 trigger 或弹出层按 Esc 键时调用	function(e:event)		2.13.0
onVisibleChange	弹出层显示状态改变时的回调	function(visible: boolean)

属性	说明	类型	版本
className	下拉弹层菜单样式类名	string	0.28.0
children	下拉弹层菜单包裹的子元素，一般为 `Dropdown.Item` 或 `Dropdown.Title`	ReactNode
style	下拉弹层菜单样式	object	0.28.0

属性	说明	类型	默认值	版本
active	当前项是否处于激活态，激活态时左侧有 √，字体加粗，颜色加深。当 Dropdown 的 showTick 为 false 时，即使 Dropdown.Item 的 active 为 true，√ 也不会展示	bool	false
className	样式类名	string
disabled	是否禁用菜单	boolean	false
icon	图标	ReactNode		1.16.0
style	内联样式	object
type	类型，可选值："primary"、"secondary"、"tertiary"、"warning"、"danger"	string	"tertiary"
onClick	单击触发的回调事件	function	无
onMouseEnter	MouseEnter 触发的回调事件	function	无
onMouseLeave	MouseLeave 触发的回调事件	function	无
onContextMenu	点击鼠标右键触发的回调事件	function	无	1.6.0

属性	说明	类型	默认值
className	样式类名	string	""
style	内联样式	object	`{}`

DropdownMenuItem

属性	说明	类型
node	按钮类型，可选：`title`，`item`，`divider`	string
name	菜单文本，标题或 Item 的内容	string
其他属性与 Title、Item、Divider 属性对应

Accessibility

ARIA

Dropdown.Menu role 设置为 menu，aria-orientatio 设置为 vertical
Dropdown.Item role 设置为 menuitem
键盘和焦点
Dropdown 的触发器可被聚焦，目前支持 3 种触发方式：
- 触发方式设置为 hover 或 focus 时：鼠标悬浮或聚焦时打开 Dropdown，Dropdown 打开后，用户可以使用 下箭头 将焦点移动到Dropdown 内
- 触发方式设置为 click 时：点击触发器或聚焦时使用 Enter 或 Space 键可以打开 Dropdown，此时焦点自动聚焦到 Dropdown 中的第一个非禁用项上
当焦点位于 Dropdown 内的菜单项上时：
- 键盘用户可以使用键盘 上箭头 或 下箭头 切换可交互元素
- 使用 Enter 键或 Space 键可以激活聚焦的菜单项, 若菜单项绑定了onClick，事件会被触发
键盘用户可以通过按 Esc 关闭 Dropdown，关闭后焦点返回到触发器上
键盘交互暂未完整支持嵌套场景

文案规范

下拉框内选项内容需要表述准确且包含信息，使用户在浏览时更加容易在选项中选择
使用语句式的大小写，并且简洁明了地书写选项
如果是动作选项，使用动词或者动词短语来描述用户选择该选项后会发生的动作。举个例子，"Move", "Log time", or "Hide labels"
不使用介词

✅ 推荐用法	❌ 不推荐用法

设计变量

radius

color

spacing

width

other

height

font

animation

变量	默认值	用法
$radius-dropdown	var(--semi-border-radius-medium)	下拉菜单圆角大小

显示第 1 条-第 1 条，共 1 条

变量	默认值	用法
$color-dropdown-bg-default	var(--semi-color-bg-3)	下拉菜单背景颜色
$color-dropdown_title-text-default	var(--semi-color-text-2)	下拉菜单分组标题文字颜色
$color-dropdown_item-text-default	var(--semi-color-text-0)	下拉菜单项文字颜色
$color-dropdown_item-bg-hover	var(--semi-color-fill-0)	下拉菜单项背景颜色 - 悬浮
$color-dropdown_item-bg-active	var(--semi-color-fill-1)	下拉菜单项背景颜色 - 按下
$color-dropdown_item_danger-text-default	var(--semi-color-danger)	下拉菜单项背景颜色 - 悬浮
$color-dropdown_item_secondary-text-default	var(--semi-color-secondary)	二级菜单项文字颜色
$color-dropdown_item_warning-text-default	var(--semi-color-warning)	警告菜单项文字颜色
$color-dropdown_item_tertiary-text-default	var(--semi-color-tertiary)	第三菜单项文字颜色
$color-dropdown_item_primary-text-default	var(--semi-color-primary)	主要菜单项文字颜色

显示第 1 条-第 10 条，共 13 条

变量	默认值	用法
$spacing-dropdown_menu-paddingY	$spacing-extra-tight	下拉菜单垂直内边距
$spacing-dropdown_menu-paddingX	0	下拉菜单水平内边距
$spacing-dropdown_title-paddingTop	$spacing-tight	下拉菜单分组标题顶部内边距
$spacing-dropdown_title-paddingBottom	$spacing-extra-tight	下拉菜单分组标题底部内边距
$spacing-dropdown_title-paddingLeft	$spacing-base	下拉菜单分组标题左侧内边距
$spacing-dropdown_title-paddingRight	$spacing-base	下拉菜单分组标题右侧内边距
$spacing-dropdown_title_withTick-paddingLeft	31px	可选中的下拉菜单，分组标题左侧内边距
$spacing-dropdown_item_withTick-paddingLeft	$spacing-base-tight	可选中弄的下拉菜单项，对勾 icon 左侧内边距
$spacing-dropdown_item-paddingY	$spacing-tight	下拉菜单项垂直内边距
$spacing-dropdown_item-paddingX	$spacing-base	下拉菜单项水平内边距

显示第 1 条-第 10 条，共 13 条

变量	默认值	用法
$width-dropdown	280px	菜单最大宽度

变量	默认值	用法
$size-dropdown-icon-width	12px	菜单项图标宽度
$size-dropdown-icon-height	12px	菜单项图标高度

变量	默认值	用法
$height-dropdown_seperator	1px	菜单项分隔线宽度

变量	默认值	用法
$font-dropdown_item_active-fontWeight	600	选中菜单项字重

变量	默认值	用法
$transition_duration-dropdown_item-bg	var(--semi-transition_duration-none)	下拉菜单项-背景颜色-动画持续时间
$transition_function-dropdown_item-bg	var(--semi-transition_function-easeOut)	下拉菜单项-背景颜色-过渡曲线
$transition_delay-dropdown_item-bg	0ms	下拉菜单项-背景颜色-延迟时间

显示第 1 条-第 3 条，共 3 条

FAQ

为什么 Dropdown 浮层在靠近屏幕边界宽度不够时，丢失宽度意外换行?
在 chromium 104 后对于屏幕边界文本宽度不够时的换行渲染策略发生变化，详细原因可查看 issue #1022，semi侧已经在v2.17.0版本修复了这个问题。

代码演示 ​

如何引入 ​

基本用法 ​

嵌套使用 ​

元素属性 ​

弹出位置 ​

触发方式 ​

触发事件 ​

分组组合 ​

Json 用法 ​

API 参考 ​

Dropdown ​

Dropdown.Menu ​

Dropdown.Item ​

Dropdown.Title ​

DropdownMenuItem ​

Accessibility ​

ARIA ​

键盘和焦点 ​

文案规范 ​

设计变量 ​

FAQ ​

相关物料 ​

代码演示

如何引入

基本用法

嵌套使用

元素属性

弹出位置

触发方式

触发事件

分组组合

Json 用法

API 参考

Dropdown

Dropdown.Menu

Dropdown.Item

Dropdown.Title

DropdownMenuItem

Accessibility

ARIA

键盘和焦点

文案规范

设计变量

FAQ

相关物料