代码演示
如何引入
基本用法
嵌套使用
用户可以对
Dropdown
进行嵌套使用,此类情况适合具有多个子级选项的情况。元素属性
通过设置
通过给
通过在
disabled
可以禁用某个选项通过给
Dropdown.Item
配置 type
,可以展示不同颜色的文本通过在
Dropdown.Item
上设置 icon
可以快速配置图标弹出位置
支持的位置同 Tooltip,常用的是:"bottom", "bottomLeft", "bottomRight" 这三种。
触发方式
默认是移入触发,可通过获取焦点,点击或自定义事件触发菜单展开。
触发事件
点击菜单项后可触发不同鼠标事件,支持
onClick
,onMouseEnter
, onMouseLeave
和 onContextMenu
。分组组合
使用
Dropdown.Divider
可以插入分割线使用 Dropdown.Title
可以插入分组名组合使用 Dropdown.Title
、Dropdown.Divider
、Dropdown.Item
。Json 用法
可以通过 menu 属性,传入 JSON Array 快速配置出下拉框菜单
API 参考
Dropdown
属性 | 说明 | 类型 | 默认值 | 版本 |
---|---|---|---|---|
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 | function():HTMLElement | () => document.body | |
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" | 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) |
Dropdown.Menu
属性 | 说明 | 类型 | 默认值 | 版本 |
---|---|---|---|---|
className | 下拉弹层菜单样式类名 | string | 0.28.0 | |
children | 下拉弹层菜单包裹的子元素,一般为 Dropdown.Item 或 Dropdown.Title | ReactNode | ||
style | 下拉弹层菜单样式 | object | 0.28.0 |
Dropdown.Item
属性 | 说明 | 类型 | 默认值 | 版本 |
---|---|---|---|---|
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 |
Dropdown.Title
属性 | 说明 | 类型 | 默认值 |
---|---|---|---|
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 中的第一个非禁用项上
- 触发方式设置为 hover 或 focus 时:鼠标悬浮或聚焦时打开 Dropdown,Dropdown 打开后,用户可以使用
- 当焦点位于 Dropdown 内的菜单项上时:
- 键盘用户可以使用键盘
上箭头
或下箭头
切换可交互元素 - 使用
Enter
键 或Space
键可以激活聚焦的菜单项, 若菜单项绑定了onClick,事件会被触发
- 键盘用户可以使用键盘
- 键盘用户可以通过按
Esc
关闭 Dropdown,关闭后焦点返回到触发器上 - 键盘交互暂未完整支持嵌套场景