Dropdown 下拉菜单
将动作或菜单折叠到下拉菜单中。
基础用法
基础下拉
悬停在下拉菜单上以展开更多操作。
通过组件 slot 来设置下拉触发的元素以及需要通过具名 slot 为 dropdown 来设置下拉菜单。 默认情况下,只需要悬停在触发菜单的元素上即可,无需点击也会显示下拉菜单。
触发对象
可使用按钮触发下拉菜单。
设置 split-button 属性来让触发下拉元素呈现为按钮组,左边是功能按钮,右边是触发下拉菜单的按钮,设置为 true 即可。 如果你想要在第三和第四个选项之间添加一个分隔符,你只需要为第四个选项添加一个 divider 的 CSS class。
触发方式
可以配置点击激活或者悬停激活。
将 trigger 属性设置为 click 即可, 默认为 hover。
菜单隐藏方式
可以通过 hide-on-click 属性来配置。
下拉菜单默认在点击菜单项后会被隐藏,将 hide-on-click 属性设置为 false 可以关闭此功能。
指令事件
点击菜单项后会触发事件,用户可以通过相应的菜单项 key 进行不同的操作。
功能
虚拟触发 1.0.2
有时候我们希望在其他触发元素上渲染下拉框,这时可以将触发器和内容分离。
下拉方法
您可以手动打开或关闭下拉菜单。
打开(关闭)患者菜单 B 时,将自动关闭(打开)患者菜单 A。
标题与底部插槽
通过 dropdown-header / dropdown-footer 具名插槽,可以在菜单上方与下方渲染自定义内容,常用于搜索框与统计说明。两者都位于滚动容器之外,不会影响菜单的键盘导航。
传入 #dropdown-header 与 #dropdown-footer 插槽即可,插槽内容未传入时不会渲染额外的包裹节点。
样式
弹出位置
支持 6 个弹出位置。
设置 placement 属性,使下拉菜单出现在不同位置。
尺寸
Dropdown 组件提供除了默认值以外的三种尺寸,可以在不同场景下选择合适的尺寸。
使用 size 属性配置尺寸,可选的尺寸大小有: large, default, small 或 mini
留白面板
设置 spread 为 false 时,菜单两侧各留 8px 间距、菜单项不贴浮层边缘,且每个菜单项拥有独立圆角(hover 底色不贴边);默认 true 时菜单占满浮层宽度。
无障碍标记 aria-label
供自动化测试按原生节点定位:区域标记前缀取业务传入值 —— 触发区根节点 <dropdown aria-label 值>::触发区,菜单区 ul[role=menu] 为 <值>::下拉菜单区(菜单自身值优先于 dropdown 值;无值不输出);菜单项按 command 固定为 下拉菜单项::<command>,业务写在 w-dropdown-item 上的 aria-label 不生效。
可视化用例见 自动化测试 · Dropdown。
Dropdown API
Attributes
| 属性名 | 说明 | 类型 | Default |
|---|---|---|---|
| type | 菜单按钮类型,同 Button 组件一样,仅在 split-button 为 true 的情况下有效。 | enum | '' |
| size | 菜单尺寸,在 split-button 为 true 的情况下也对触发按钮生效。 | enum | '' |
| button-props | 按钮组件的 props,参考 按钮属性 | object | — |
| max-height | 菜单最大高度 | string / number | '' |
| spread | 菜单是否占满浮层宽度,设为 false 时菜单两侧各留 8px、每项独立圆角(对齐 Vue2 is-spacing 形态) | boolean | true |
| split-button | 下拉触发元素呈现为按钮组 | boolean | false |
| disabled | 是否禁用 | boolean | false |
| placement | 菜单弹出位置 | enum | bottom |
| effect | Tooltip 主题,内置了: light / dark / lighter | enum | lighter |
| trigger | 触发下拉的行为 | enum / array | hover |
| trigger-keys | 指定键盘上哪些按键可以触发操作 | array | ['Enter', 'Space', 'ArrowDown', 'NumpadEnter'] |
| virtual-triggering | 是否启用虚拟触发 | boolean | — |
| virtual-ref | 虚拟触发时下拉菜单挂载的参考元素 | object | — |
| hide-on-click | 是否在点击菜单项后隐藏菜单 | boolean | true |
| loop | 菜单项是否循环导航(聚焦到末尾后继续聚焦到开头) | boolean | true |
| show-arrow | 下拉菜单是否显示箭头 | boolean | true |
| show-timeout | 展开下拉菜单的延时,仅在 trigger 为 hover 时有效 | number | 150 |
| hide-timeout | 收起下拉菜单的延时(仅在 trigger 为 hover 时有效) | number | 150 |
| role | 下拉菜单的 ARIA 属性。 根据具体场景,您可能想要将此更改为“navigation” | enum | menu |
| tabindex | Dropdown 组件的 tabindex | number / string | 0 |
| id | 菜单 id,默认自动生成 | string | — |
| popper-class | 自定义浮层类名 | string / object | — |
| popper-style | 自定义浮层样式 | string / object | — |
| popper-options | popper.js 参数 | object | {} |
| teleported | 是否将下拉列表插入至 body 元素 | boolean | true |
| append-to | 下拉菜单挂载的容器元素 | string / object | — |
| persistent | 当下拉菜单处于非活动状态且 persistent 为 false 时,下拉菜单将被销毁 | boolean | true |
Slots
| 插槽名 | 说明 | 子标签 |
|---|---|---|
| default | 下拉菜单的内容。 注意:必须是有效的 html DOM 元素(例如 <span>、<button> 等)或 w-component,以附加监听触发器 | — |
| dropdown | 下拉列表,通常是 <w-dropdown-menu> 组件 | Dropdown-Menu |
| dropdown-header | 面板顶部区域内容,渲染在菜单容器之上;未传入时不渲染包裹节点 | — |
| dropdown-footer | 面板底部区域内容,渲染在菜单容器之下;未传入时不渲染包裹节点 | — |
Events
| 事件名 | 说明 | 类型 |
|---|---|---|
| click | split-button 为 true 时,点击左侧按钮的回调 | Function |
| command | 当下拉项被点击时触发,参数是从下拉菜单中发送的命令 | Function |
| visible-change | 当下拉菜单出现/消失时触发器, 当它出现时, 参数将是 true, 否则将是 false | Function |
Exposes
| 方法名 | 说明 | Type |
|---|---|---|
| handleOpen | 打开下拉菜单 | Function |
| handleClose | 关闭下拉菜单 | Function |
Dropdown-Menu API
Slots
| 插槽名 | 说明 | 子标签 |
|---|---|---|
| default | 下拉菜单的内容 | Dropdown-Item |
Dropdown-Item API
Attributes
| 属性名 | 说明 | Type | 默认值 |
|---|---|---|---|
| command | 派发到command回调函数的指令参数 | string / number / object | — |
| disabled | 是否禁用 | boolean | false |
| divided | 是否显示分隔符 | boolean | false |
| icon | 自定义图标 | string / Component | — |
Slots
| 插槽名 | 说明 |
|---|---|
| default | 自定义 Dropdown-Item 内容 |
| icon | 自定义图标,内容会覆盖 icon 属性 |
Copyright 2025 Winning Health 版权所有

