展示类 · Dropdown
下拉框
向下弹出的菜单。

代码演示

如何引入

基本用法

嵌套使用

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

元素属性

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

弹出位置

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

触发方式

默认是移入触发,可通过获取焦点,点击或自定义事件触发菜单展开。

触发事件

点击菜单项后可触发不同鼠标事件,支持 onClickonMouseEnteronMouseLeaveonContextMenu

分组组合

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

Json 用法

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

API 参考

属性说明类型默认值版本
autoAdjustOverflow弹出层被遮挡时是否自动调整方向booleantrue
closeOnEsc在 trigger 或 弹出层按 Esc 键是否关闭面板,受控时不生效booleantrue | 2.13.0
className下拉弹层外层样式类名string
children触发弹出层的 Trigger 元素ReactNode
clickToHide在弹出层内点击时是否自动关闭弹出层boolean0.24.0
contentClassName下拉菜单根元素类名string
getPopupContainer指定父级 DOM,弹层将会渲染至该 DOM 中,自定义需要设置 position: relativefunction():HTMLElement() => document.body
mouseEnterDelay鼠标移入 Trigger 后,延迟显示的时间,单位毫秒(仅当 trigger 为 hover/focus 时生效)number50
mouseLeaveDelay鼠标移出弹出层后,延迟消失的时间,单位毫秒(仅当 trigger 为 hover/focus 时生效)number50
menu通过传入 JSON Array 来快速配置 Dropdown 内容Array<DropdownMenuItem>[]1.12.0
position弹出菜单的位置,常用:"bottom", "bottomLeft", "bottomRight",更多详见Tooltip 位置string"bottom"
render弹出层的内容,由 Dropdown.MenuDropdown.ItemDropdown.Title 构成ReactNode
rePosKey可以更新该项值手动触发弹出层的重新定位string | number
spacing弹出层与 Trigger 元素(即 Dropdown children)的距离,单位 pxnumber4
style弹出层内联样式object
showTick是否自动在 active 的 Dropdown.Item 项左侧展示表示选中的勾booleanfalse0.26.0
stopPropagation是否阻止弹出层上的点击事件冒泡booleanfalse0.34.0
trigger触发下拉的行为,可选 "hover", "focus", "click", "custom"string"hover"
visible是否显示菜单,需配合 trigger custom 使用boolean
zIndex弹出层 z-index 值number1050
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下拉弹层菜单样式类名string0.28.0
children下拉弹层菜单包裹的子元素,一般为 Dropdown.ItemDropdown.TitleReactNode
style下拉弹层菜单样式object0.28.0
属性说明类型默认值版本
active当前项是否处于激活态,激活态时左侧有 √,字体加粗,颜色加深。当 Dropdown 的 showTick 为 false 时,即使 Dropdown.Item 的 active 为 true,√ 也不会展示boolfalse
className样式类名string
disabled是否禁用菜单booleanfalse
icon图标ReactNode1.16.0
style内联样式object
type类型,可选值:"primary"、"secondary"、"tertiary"、"warning"、"danger"string"tertiary"
onClick单击触发的回调事件function
onMouseEnterMouseEnter 触发的回调事件function
onMouseLeaveMouseLeave 触发的回调事件function
onContextMenu点击鼠标右键触发的回调事件function1.6.0
属性说明类型默认值
className样式类名string""
style内联样式object{}
属性说明类型默认值
node按钮类型,可选:titleitemdividerstring
name菜单文本,标题或 Item 的内容string
其他属性与 Title、Item、Divider 属性对应

Accessibility

ARIA

  • Dropdown.Menu role 设置为 menuaria-orientatio 设置为 vertical
  • Dropdown.Item role 设置为 menuitem
  • 键盘和焦点

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

设计变量

© 2021 Semi Design. All rights reserved.

京ICP备19058139号-13浙公网安备 33011002016131号

Designed & Developed with love by Douyin FE & MED