Translation in progress
This page hasn't been translated into English yet, so the content below is in Chinese. The code examples work the same way.
Dropdown 下拉菜单
悬停、点击或右键某个元素时,在旁边弹出一组可选的操作。由三个组件配合使用:NsDropdown 是外层,NsDropdownMenu 是菜单列表,NsDropdownItem 是菜单项。也可以显示成分裂按钮:左边是主操作,右边的箭头展开其余操作。
引入
import { NsDropdown, NsDropdownMenu, NsDropdownItem } from '@ns/ui'
基础用法
触发元素放在默认插槽里,菜单放在 dropdown 插槽里。每个菜单项用 command 带一个标识,点击后 NsDropdown 触发 command 事件并把这个标识传出来。默认悬停触发。
<script setup lang="ts">
import { ref } from 'vue'
import { NsDropdown, NsDropdownMenu, NsDropdownItem, NsButton } from '@ns/ui'
const last = ref<string | number | undefined>()
const handleCommand = (command: string | number | undefined) => {
last.value = command
}
</script>
<template>
<NsDropdown @command="handleCommand">
<NsButton>下拉菜单</NsButton>
<template #dropdown>
<NsDropdownMenu>
<NsDropdownItem command="one">选项一</NsDropdownItem>
<NsDropdownItem command="two">选项二</NsDropdownItem>
<NsDropdownItem command="logout" divided>退出</NsDropdownItem>
</NsDropdownMenu>
</template>
</NsDropdown>
<p style="margin-top: 12px">command:{{ last ?? '还没有点' }}</p>
</template>
触发方式
trigger 有三种:
hover(默认):鼠标移入 150 毫秒后显示,移出 150 毫秒后收起。鼠标可以从触发元素移进菜单。click:点击触发元素切换显示。contextmenu:在触发元素上点右键显示(会拦掉浏览器自带的右键菜单)。
不管哪种触发方式,菜单显示着的时候点菜单和触发元素以外的地方、按 Esc 都会收起。
<template>
<NsSpace wrap align="start">
<NsDropdown trigger="hover">
<NsButton>悬停触发(hover)</NsButton>
<template #dropdown>
<NsDropdownMenu>
<NsDropdownItem>新建</NsDropdownItem>
<NsDropdownItem>编辑</NsDropdownItem>
</NsDropdownMenu>
</template>
</NsDropdown>
<NsDropdown trigger="click">
<NsButton>点击触发(click)</NsButton>
<template #dropdown>
<NsDropdownMenu>
<NsDropdownItem>新建</NsDropdownItem>
<NsDropdownItem>编辑</NsDropdownItem>
</NsDropdownMenu>
</template>
</NsDropdown>
<NsDropdown trigger="contextmenu">
<div class="area">在这里点右键(contextmenu)</div>
<template #dropdown>
<NsDropdownMenu>
<NsDropdownItem>复制</NsDropdownItem>
<NsDropdownItem>粘贴</NsDropdownItem>
</NsDropdownMenu>
</template>
</NsDropdown>
</NsSpace>
</template>
<style scoped>
.area {
display: flex;
align-items: center;
justify-content: center;
width: 220px;
height: 80px;
border: 1px dashed var(--ns-border-color);
border-radius: var(--ns-border-radius);
color: var(--ns-text-color-secondary);
}
</style>
位置
placement 有 12 个取值(top、bottom、left、right,各自可以加 -start、-end),默认 bottom-start。菜单和触发元素的间距固定是 8px。
指定的方向放不下时自动翻到反方向;菜单超出视口边缘时会被推回视口内;菜单项太多、一侧放不下时菜单里出现滚动条。点下面的按钮看效果:
<template>
<div class="placements">
<div class="placements__row placements__row--center">
<NsDropdown trigger="click" placement="top-start">
<NsButton>top-start</NsButton>
<template #dropdown>
<NsDropdownMenu>
<NsDropdownItem>选项一</NsDropdownItem>
<NsDropdownItem>选项二</NsDropdownItem>
</NsDropdownMenu>
</template>
</NsDropdown>
<NsDropdown trigger="click" placement="top">
<NsButton>top</NsButton>
<template #dropdown>
<NsDropdownMenu>
<NsDropdownItem>选项一</NsDropdownItem>
<NsDropdownItem>选项二</NsDropdownItem>
</NsDropdownMenu>
</template>
</NsDropdown>
<NsDropdown trigger="click" placement="top-end">
<NsButton>top-end</NsButton>
<template #dropdown>
<NsDropdownMenu>
<NsDropdownItem>选项一</NsDropdownItem>
<NsDropdownItem>选项二</NsDropdownItem>
</NsDropdownMenu>
</template>
</NsDropdown>
</div>
<div class="placements__row placements__row--between">
<NsSpace direction="vertical" align="start">
<NsDropdown trigger="click" placement="left-start">
<NsButton>left-start</NsButton>
<template #dropdown>
<NsDropdownMenu>
<NsDropdownItem>选项一</NsDropdownItem>
<NsDropdownItem>选项二</NsDropdownItem>
</NsDropdownMenu>
</template>
</NsDropdown>
<NsDropdown trigger="click" placement="left">
<NsButton>left</NsButton>
<template #dropdown>
<NsDropdownMenu>
<NsDropdownItem>选项一</NsDropdownItem>
<NsDropdownItem>选项二</NsDropdownItem>
</NsDropdownMenu>
</template>
</NsDropdown>
<NsDropdown trigger="click" placement="left-end">
<NsButton>left-end</NsButton>
<template #dropdown>
<NsDropdownMenu>
<NsDropdownItem>选项一</NsDropdownItem>
<NsDropdownItem>选项二</NsDropdownItem>
</NsDropdownMenu>
</template>
</NsDropdown>
</NsSpace>
<NsSpace direction="vertical" align="end">
<NsDropdown trigger="click" placement="right-start">
<NsButton>right-start</NsButton>
<template #dropdown>
<NsDropdownMenu>
<NsDropdownItem>选项一</NsDropdownItem>
<NsDropdownItem>选项二</NsDropdownItem>
</NsDropdownMenu>
</template>
</NsDropdown>
<NsDropdown trigger="click" placement="right">
<NsButton>right</NsButton>
<template #dropdown>
<NsDropdownMenu>
<NsDropdownItem>选项一</NsDropdownItem>
<NsDropdownItem>选项二</NsDropdownItem>
</NsDropdownMenu>
</template>
</NsDropdown>
<NsDropdown trigger="click" placement="right-end">
<NsButton>right-end</NsButton>
<template #dropdown>
<NsDropdownMenu>
<NsDropdownItem>选项一</NsDropdownItem>
<NsDropdownItem>选项二</NsDropdownItem>
</NsDropdownMenu>
</template>
</NsDropdown>
</NsSpace>
</div>
<div class="placements__row placements__row--center">
<NsDropdown trigger="click" placement="bottom-start">
<NsButton>bottom-start</NsButton>
<template #dropdown>
<NsDropdownMenu>
<NsDropdownItem>选项一</NsDropdownItem>
<NsDropdownItem>选项二</NsDropdownItem>
</NsDropdownMenu>
</template>
</NsDropdown>
<NsDropdown trigger="click" placement="bottom">
<NsButton>bottom</NsButton>
<template #dropdown>
<NsDropdownMenu>
<NsDropdownItem>选项一</NsDropdownItem>
<NsDropdownItem>选项二</NsDropdownItem>
</NsDropdownMenu>
</template>
</NsDropdown>
<NsDropdown trigger="click" placement="bottom-end">
<NsButton>bottom-end</NsButton>
<template #dropdown>
<NsDropdownMenu>
<NsDropdownItem>选项一</NsDropdownItem>
<NsDropdownItem>选项二</NsDropdownItem>
</NsDropdownMenu>
</template>
</NsDropdown>
</div>
</div>
</template>
<style scoped>
.placements {
max-width: 520px;
margin: 0 auto;
}
.placements__row {
display: flex;
gap: var(--ns-spacing-2);
}
.placements__row--center {
justify-content: center;
}
.placements__row--between {
justify-content: space-between;
margin: var(--ns-spacing-3) 0;
}
</style>
菜单项:图标、禁用、分割线
icon 在文字前面显示一个图标(NsIcon 的 name),disabled 禁用这一项(点了不触发 command),divided 在这一项上方加一条分割线。
<template>
<NsDropdown trigger="click">
<NsButton>更多操作</NsButton>
<template #dropdown>
<NsDropdownMenu>
<NsDropdownItem command="edit" icon="edit">编辑</NsDropdownItem>
<NsDropdownItem command="copy" icon="copy">复制</NsDropdownItem>
<NsDropdownItem command="share" icon="share" disabled>分享</NsDropdownItem>
<NsDropdownItem command="download" icon="download">下载</NsDropdownItem>
<NsDropdownItem command="delete" icon="trash" divided>删除</NsDropdownItem>
</NsDropdownMenu>
</template>
</NsDropdown>
</template>
不同尺寸
size 可选 large、default、small,改的是菜单项的高度、字号和左右内边距,菜单的圆角和阴影三档一样。不写时跟随 NsConfigProvider 的 size,再没有就是 default。触发元素是你自己放的,它的尺寸要自己写(例如 NsButton 的 size)。
<template>
<NsSpace wrap>
<NsDropdown size="large" trigger="click">
<NsButton size="large">大型(large)</NsButton>
<template #dropdown>
<NsDropdownMenu>
<NsDropdownItem icon="edit">编辑</NsDropdownItem>
<NsDropdownItem icon="copy">复制</NsDropdownItem>
<NsDropdownItem icon="trash" divided>删除</NsDropdownItem>
</NsDropdownMenu>
</template>
</NsDropdown>
<NsDropdown size="default" trigger="click">
<NsButton>默认(default)</NsButton>
<template #dropdown>
<NsDropdownMenu>
<NsDropdownItem icon="edit">编辑</NsDropdownItem>
<NsDropdownItem icon="copy">复制</NsDropdownItem>
<NsDropdownItem icon="trash" divided>删除</NsDropdownItem>
</NsDropdownMenu>
</template>
</NsDropdown>
<NsDropdown size="small" trigger="click">
<NsButton size="small">小型(small)</NsButton>
<template #dropdown>
<NsDropdownMenu>
<NsDropdownItem icon="edit">编辑</NsDropdownItem>
<NsDropdownItem icon="copy">复制</NsDropdownItem>
<NsDropdownItem icon="trash" divided>删除</NsDropdownItem>
</NsDropdownMenu>
</template>
</NsDropdown>
</NsSpace>
</template>
| 项目 | large | default | small |
|---|---|---|---|
| 菜单项高 | 40px(行高 24px) | 约 36px(行高 1.4) | 28px(行高 20px) |
| 字号 | 16px | 14px | 12px |
| 左右内边距 | 16px | 12px | 8px |
| 图标 | 18px | 16px | 14px |
和 NsSelect 同尺寸的下拉选项一致。
根据数据生成菜单项
NsDropdown 没有 items 这类属性,菜单项用 v-for 渲染。
<script setup lang="ts">
import { NsDropdown, NsDropdownMenu, NsDropdownItem, NsButton } from '@ns/ui'
const items = [
{ command: 'edit', label: '编辑', icon: 'edit' },
{ command: 'copy', label: '复制', icon: 'copy' },
{ command: 'archive', label: '归档', icon: 'folder', disabled: true },
{ command: 'delete', label: '删除', icon: 'trash', divided: true }
]
</script>
<template>
<NsDropdown trigger="click">
<NsButton>操作</NsButton>
<template #dropdown>
<NsDropdownMenu>
<NsDropdownItem
v-for="item in items"
:key="item.command"
:command="item.command"
:icon="item.icon"
:disabled="item.disabled"
:divided="item.divided"
>
{{ item.label }}
</NsDropdownItem>
</NsDropdownMenu>
</template>
</NsDropdown>
</template>
点击菜单项后不收起
默认点一个菜单项后菜单收起。hide-on-click 设为 false 时保持打开,可以连续点。
<script setup lang="ts">
import { ref } from 'vue'
import { NsDropdown, NsDropdownMenu, NsDropdownItem, NsButton, NsSpace } from '@ns/ui'
const count = ref(0)
</script>
<template>
<NsSpace wrap>
<NsDropdown trigger="click" @command="count++">
<NsButton>点一项就收起(默认)</NsButton>
<template #dropdown>
<NsDropdownMenu>
<NsDropdownItem command="a">选项一</NsDropdownItem>
<NsDropdownItem command="b">选项二</NsDropdownItem>
</NsDropdownMenu>
</template>
</NsDropdown>
<NsDropdown trigger="click" :hide-on-click="false" @command="count++">
<NsButton>连续操作(hide-on-click=false)</NsButton>
<template #dropdown>
<NsDropdownMenu>
<NsDropdownItem command="a">点我不会收起</NsDropdownItem>
<NsDropdownItem command="b">可以连续点</NsDropdownItem>
</NsDropdownMenu>
</template>
</NsDropdown>
<span>已点 {{ count }} 次</span>
</NsSpace>
</template>
禁用
disabled 为 true 时不响应悬停、点击、右键和键盘,外层容器也不再是 Tab 停靠点。正在显示时被禁用会立即收起。触发元素本身的禁用样式要自己加(例如给里面的按钮也加 disabled)。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsCheckbox, NsDropdown, NsDropdownItem, NsDropdownMenu, NsSpace } from '@ns/ui'
const disabled = ref(true)
</script>
<template>
<NsSpace wrap>
<NsCheckbox v-model="disabled">禁用</NsCheckbox>
<NsDropdown :disabled="disabled">
<NsButton :disabled="disabled">悬停触发</NsButton>
<template #dropdown>
<NsDropdownMenu>
<NsDropdownItem>选项一</NsDropdownItem>
</NsDropdownMenu>
</template>
</NsDropdown>
<NsDropdown trigger="click" :disabled="disabled">
<NsButton :disabled="disabled">点击触发</NsButton>
<template #dropdown>
<NsDropdownMenu>
<NsDropdownItem>选项一</NsDropdownItem>
</NsDropdownMenu>
</template>
</NsDropdown>
</NsSpace>
</template>
受控显示
用 v-model:visible 时,用户的操作会更新绑定的变量,外部改变量也能打开、关闭。菜单实际显示或收起时触发 visible-change。
<script setup lang="ts">
import { ref } from 'vue'
import { NsDropdown, NsDropdownMenu, NsDropdownItem, NsButton, NsCheckbox, NsSpace } from '@ns/ui'
const visible = ref(false)
const changeCount = ref(0)
</script>
<template>
<NsSpace wrap>
<NsDropdown v-model:visible="visible" trigger="click" @visible-change="changeCount++">
<NsButton>点我切换</NsButton>
<template #dropdown>
<NsDropdownMenu>
<NsDropdownItem>选项一</NsDropdownItem>
<NsDropdownItem>选项二</NsDropdownItem>
</NsDropdownMenu>
</template>
</NsDropdown>
<NsCheckbox v-model="visible">外部开关</NsCheckbox>
<span>visible-change 触发了 {{ changeCount }} 次</span>
</NsSpace>
</template>
通过方法控制
通过组件的 ref 调用 show()、hide(),ref 上的 visible 是菜单当前是否显示。
<script setup lang="ts">
import { ref } from 'vue'
import { NsDropdown, NsDropdownMenu, NsDropdownItem, NsButton, NsSpace } from '@ns/ui'
const dropdownRef = ref<InstanceType<typeof NsDropdown>>()
</script>
<template>
<NsSpace wrap>
<NsButton @click="dropdownRef?.show()">show()</NsButton>
<NsButton @click="dropdownRef?.hide()">hide()</NsButton>
<NsDropdown ref="dropdownRef" trigger="click">
<NsButton type="primary">目标菜单</NsButton>
<template #dropdown>
<NsDropdownMenu>
<NsDropdownItem>选项一</NsDropdownItem>
<NsDropdownItem>选项二</NsDropdownItem>
</NsDropdownMenu>
</template>
</NsDropdown>
<span>visible:{{ dropdownRef?.visible ?? false }}</span>
</NsSpace>
</template>
菜单项的点击事件
点菜单项时先触发 click,再触发 command,参数都是这一项的 command。禁用的项两个都不触发。分裂按钮(split-button)的菜单项也一样;它左边主按钮的点击是另一个事件 button-click,见下面的“分裂按钮”。
<script setup lang="ts">
import { ref } from 'vue'
import { NsDropdown, NsDropdownMenu, NsDropdownItem, NsButton } from '@ns/ui'
const logs = ref<string[]>([])
const handleClick = (command: string | number | undefined) => {
logs.value = [`click(${command})`]
}
const handleCommand = (command: string | number | undefined) => {
logs.value.push(`command(${command})`)
}
</script>
<template>
<NsDropdown trigger="click" @click="handleClick" @command="handleCommand">
<NsButton>点菜单项</NsButton>
<template #dropdown>
<NsDropdownMenu>
<NsDropdownItem command="edit">编辑</NsDropdownItem>
<NsDropdownItem :command="2">command 是数字 2</NsDropdownItem>
<NsDropdownItem>没写 command</NsDropdownItem>
<NsDropdownItem command="share" disabled>禁用的项</NsDropdownItem>
</NsDropdownMenu>
</template>
</NsDropdown>
<p style="margin-top: 12px">{{ logs.length ? logs.join(' → ') : '还没有点' }}</p>
</template>
分裂按钮
加上 split-button,触发元素换成两个连在一起的按钮:
- 左边是主操作按钮,文字写在默认插槽里。点它触发
button-click事件(参数是鼠标事件),不展开菜单;菜单开着时点它会先收起菜单。 - 右边是只有向下箭头的按钮,点它(
trigger="click")或把鼠标移上去(trigger="hover",默认)才展开菜单。 - 选中菜单项和普通下拉菜单一样触发
click、command,不触发button-click,所以@button-click里只会是主操作。
适合“有一个最常用的操作,几个相关的操作收进菜单”的场景,例如“保存 ▾ → 保存并新建、保存为草稿”。箭头按钮只有图标,读屏软件读的是它的 aria-label,默认“更多操作”,用 arrow-label 改成更具体的说法。
<script setup lang="ts">
import { ref } from 'vue'
import { NsDropdown, NsDropdownMenu, NsDropdownItem, NsSpace } from '@ns/ui'
const logs = ref<string[]>([])
const handleSave = (event: MouseEvent) => {
logs.value = [`button-click:保存(${event.type})`, ...logs.value].slice(0, 5)
}
const handleCommand = (command: string | number | undefined) => {
logs.value = [`command:${command}`, ...logs.value].slice(0, 5)
}
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsDropdown
split-button
type="primary"
trigger="click"
arrow-label="更多保存方式"
@button-click="handleSave"
@command="handleCommand"
>
保存
<template #dropdown>
<NsDropdownMenu>
<NsDropdownItem command="save-new" icon="plus">保存并新建</NsDropdownItem>
<NsDropdownItem command="save-draft" icon="file">保存为草稿</NsDropdownItem>
<NsDropdownItem command="save-copy" icon="copy" divided>另存为副本</NsDropdownItem>
</NsDropdownMenu>
</template>
</NsDropdown>
<span>{{
logs.length ? logs.join(',') : '点左边的“保存”或右边的箭头试试(最新的在前)'
}}</span>
</NsSpace>
</template>
按钮类型
type 设两个按钮的颜色,取值和 NsButton 的 type 一样,共 7 种。彩色的两个按钮之间用浅一档的颜色画出分隔线;default 的两个按钮共用中间那条边框。不写时取 NsConfigProvider 的 button.type,再没有就是 default。
<script setup lang="ts">
import { ref } from 'vue'
import { NsDropdown, NsDropdownMenu, NsDropdownItem, NsSpace } from '@ns/ui'
const types = ['default', 'primary', 'success', 'warning', 'danger', 'info', 'help'] as const
const last = ref('')
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<NsDropdown
v-for="type in types"
:key="type"
split-button
trigger="click"
:type="type"
@button-click="last = `${type}:button-click`"
@command="last = `${type}:command(${$event})`"
>
{{ type }}
<template #dropdown>
<NsDropdownMenu>
<NsDropdownItem command="save-new">保存并新建</NsDropdownItem>
<NsDropdownItem command="save-draft">保存为草稿</NsDropdownItem>
</NsDropdownMenu>
</template>
</NsDropdown>
</NsSpace>
<span>最近一次:{{ last || '还没有点' }}</span>
</NsSpace>
</template>
尺寸
size 同时决定两个按钮和菜单的尺寸:按钮高 40 / 32 / 24px,和同尺寸的 NsButton 一样;菜单项的高度、字号见上面的“不同尺寸”。不写时跟随 NsConfigProvider 的 size,再没有就是 default。
<script setup lang="ts">
import { ref } from 'vue'
import { NsDropdown, NsDropdownMenu, NsDropdownItem, NsSpace } from '@ns/ui'
const last = ref('')
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<NsDropdown
split-button
type="primary"
size="large"
trigger="click"
@button-click="last = 'large:button-click'"
@command="last = `large:command(${$event})`"
>
大型(large)
<template #dropdown>
<NsDropdownMenu>
<NsDropdownItem command="save-new" icon="plus">保存并新建</NsDropdownItem>
<NsDropdownItem command="save-draft" icon="file">保存为草稿</NsDropdownItem>
</NsDropdownMenu>
</template>
</NsDropdown>
<NsDropdown
split-button
type="primary"
trigger="click"
@button-click="last = 'default:button-click'"
@command="last = `default:command(${$event})`"
>
默认(default)
<template #dropdown>
<NsDropdownMenu>
<NsDropdownItem command="save-new" icon="plus">保存并新建</NsDropdownItem>
<NsDropdownItem command="save-draft" icon="file">保存为草稿</NsDropdownItem>
</NsDropdownMenu>
</template>
</NsDropdown>
<NsDropdown
split-button
type="primary"
size="small"
trigger="click"
@button-click="last = 'small:button-click'"
@command="last = `small:command(${$event})`"
>
小型(small)
<template #dropdown>
<NsDropdownMenu>
<NsDropdownItem command="save-new" icon="plus">保存并新建</NsDropdownItem>
<NsDropdownItem command="save-draft" icon="file">保存为草稿</NsDropdownItem>
</NsDropdownMenu>
</template>
</NsDropdown>
</NsSpace>
<span>最近一次:{{ last || '还没有点' }}</span>
</NsSpace>
</template>
禁用
disabled 同时禁用两个按钮:变成禁用样式,点击、悬停、按键都没反应,也不再是 Tab 停靠点。菜单显示着的时候被禁用会立即收起。
<script setup lang="ts">
import { ref } from 'vue'
import { NsCheckbox, NsDropdown, NsDropdownMenu, NsDropdownItem, NsSpace } from '@ns/ui'
const disabled = ref(true)
const count = ref(0)
</script>
<template>
<NsSpace wrap>
<NsCheckbox v-model="disabled">禁用</NsCheckbox>
<NsDropdown split-button :disabled="disabled" trigger="click" @click="count++">
提交
<template #dropdown>
<NsDropdownMenu>
<NsDropdownItem command="submit-close">提交并关闭</NsDropdownItem>
</NsDropdownMenu>
</template>
</NsDropdown>
<NsDropdown split-button type="primary" :disabled="disabled" trigger="click" @click="count++">
保存
<template #dropdown>
<NsDropdownMenu>
<NsDropdownItem command="save-new">保存并新建</NsDropdownItem>
</NsDropdownMenu>
</template>
</NsDropdown>
<span>主按钮被点了 {{ count }} 次</span>
</NsSpace>
</template>
触发方式
分裂按钮的 trigger 只作用在右边的箭头按钮上,主按钮怎么都不会展开菜单:
hover(默认):鼠标移到箭头按钮上 150 毫秒后展开,移出后收起,可以从箭头按钮移进菜单。点箭头按钮不切换显示,和普通模式的hover一样。click:点箭头按钮切换显示。contextmenu:在按钮上点右键弹菜单没有意义,分裂按钮不支持,按click处理,开发环境下在控制台给出[NsUI]开头的警告。
不管哪种触发方式,焦点在箭头按钮上时按 Enter、空格、↓ 都会打开菜单并把焦点移到第一项,见下面的“键盘操作”。
<script setup lang="ts">
import { ref } from 'vue'
import { NsDropdown, NsDropdownMenu, NsDropdownItem, NsSpace } from '@ns/ui'
const last = ref('')
const visible = ref<Record<string, boolean>>({ hover: false, click: false })
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<NsDropdown
split-button
trigger="hover"
@button-click="last = 'hover:button-click'"
@command="last = `hover:command(${$event})`"
@visible-change="visible.hover = $event"
>
悬停箭头(hover)
<template #dropdown>
<NsDropdownMenu>
<NsDropdownItem command="edit">编辑</NsDropdownItem>
<NsDropdownItem command="copy">复制</NsDropdownItem>
</NsDropdownMenu>
</template>
</NsDropdown>
<NsDropdown
split-button
trigger="click"
@button-click="last = 'click:button-click'"
@command="last = `click:command(${$event})`"
@visible-change="visible.click = $event"
>
点击箭头(click)
<template #dropdown>
<NsDropdownMenu>
<NsDropdownItem command="edit">编辑</NsDropdownItem>
<NsDropdownItem command="copy">复制</NsDropdownItem>
</NsDropdownMenu>
</template>
</NsDropdown>
</NsSpace>
<span>
最近一次:{{ last || '还没有点' }};菜单显示:hover {{ visible.hover }}、click
{{ visible.click }}
</span>
</NsSpace>
</template>
键盘操作
| 按键 | 焦点在触发元素上 | 焦点在菜单项上 |
|---|---|---|
Enter、空格 | 打开菜单,焦点移到第一项 | 选中当前项 |
↓ | 打开菜单并把焦点移到第一项 | 移到下一项,到底后回到第一项 |
↑ | - | 移到上一项,到顶后回到最后一项 |
Home、End | - | 移到第一项、最后一项 |
Esc | 收起菜单 | 收起菜单,焦点回到触发元素 |
Tab | 按浏览器默认行为移到下一个元素 | 收起菜单,焦点从触发元素继续往后走 |
被禁用的菜单项会被跳过。Enter、空格打开菜单指的是焦点在外层容器上的时候;焦点在容器里面的按钮上时,按下去等于点了一下这个按钮。
分裂按钮没有外层容器这个停靠点,两个按钮各占一个 Tab 位置:
| 按键 | 焦点在主按钮上 | 焦点在箭头按钮上 |
|---|---|---|
Enter、空格 | 触发 button-click | 打开菜单,焦点移到第一项(菜单已经开着时只把焦点移过去) |
↓ | - | 打开菜单,焦点移到第一项 |
Esc | 菜单开着时收起菜单 | 菜单开着时收起菜单 |
Tab、Shift+Tab | 在两个按钮之间移动 | 在两个按钮之间移动 |
焦点在菜单项上时的按键和上表一样;按 Esc、Tab 或选中一项后,焦点回到箭头按钮。箭头按钮带 aria-haspopup="menu"、随菜单显示变化的 aria-expanded 和 aria-label(默认“更多操作”,用 arrow-label 改)。
NsDropdown Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| trigger | 'hover' | 'click' | 'contextmenu' | 'hover' | 触发方式。分裂按钮时只作用在箭头按钮上,contextmenu 按 click 处理 |
| placement | DropdownPlacement | 'bottom-start' | 菜单出现的位置,12 个取值见“类型”。放不下时自动翻到反方向。分裂按钮时按整个按钮组定位 |
| disabled | boolean | false | 是否禁用。分裂按钮时两个按钮一起禁用 |
| hideOnClick | boolean | true | 点击菜单项后是否收起菜单 |
| tabindex | number | 0 | 触发元素外层容器的 tabindex。分裂按钮时设在两个按钮上 |
| visible | boolean | - | 是否显示,支持 v-model:visible。不传时由组件自己管理 |
| size | 'large' | 'default' | 'small' | - | 菜单尺寸,分裂按钮的两个按钮也用这个尺寸。不写时跟随 NsConfigProvider 的 size,再没有就是 default |
| splitButton | boolean | false | 显示成分裂按钮:左边是主按钮(文字来自默认插槽),点它触发 button-click;右边是箭头按钮,按 trigger 展开菜单 |
| type | ButtonType | - | 分裂按钮两个按钮的类型,取值同 NsButton 的 type。只在 splitButton 时生效;不写时取 NsConfigProvider 的 button.type |
| arrowLabel | string | '更多操作' | 分裂按钮箭头按钮的 aria-label(读屏软件读出的名称)。只在 splitButton 时生效 |
NsDropdown Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| command | (command: string | number | undefined) | 点击菜单项(或在上面按回车、空格)时触发,参数是这一项的 command。禁用的项不触发 |
| click | (command: string | number | undefined) | 点击菜单项时触发,在 command 之前,参数相同 |
| visible-change | (visible: boolean) | 菜单实际显示状态变化时触发,包括外部改 visible 引起的变化;状态没变时不触发 |
| update:visible | (value: boolean) | 传了 visible 时,用户的操作要改变显示状态时触发 |
| button-click | (event: MouseEvent) | 分裂按钮(split-button)左边的主按钮被点击时触发,不展开菜单;菜单开着时先收起菜单。普通模式不触发 |
NsDropdown Slots
| 插槽 | 作用域参数 | 说明 |
|---|---|---|
| default | - | 触发元素;分裂按钮时是左边主按钮的内容 |
| dropdown | - | 菜单内容,一般放一个 NsDropdownMenu |
NsDropdown 暴露的属性和方法
通过组件的 ref 调用。
| 方法 | 参数 | 返回值 | 说明 |
|---|---|---|---|
| show | - | void | 显示菜单。传了 visible 时只触发 update:visible(true) |
| hide | - | void | 收起菜单。传了 visible 时只触发 update:visible(false) |
ref 上还有一个只读的 visible(boolean),表示菜单当前是否显示。
NsDropdownMenu Slots
NsDropdownMenu 没有属性和事件。
| 插槽 | 作用域参数 | 说明 |
|---|---|---|
| default | - | 菜单项(NsDropdownItem) |
NsDropdownItem Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| command | string | number | - | 这一项的标识,点击后通过 command 事件传出去 |
| disabled | boolean | false | 是否禁用 |
| divided | boolean | false | 是否在这一项上方显示分割线 |
| icon | string | - | 文字前面的图标名(NsIcon 的 name) |
NsDropdownItem Slots
| 插槽 | 作用域参数 | 说明 |
|---|---|---|
| default | - | 菜单项的内容 |
类型
import type {
DropdownTrigger,
DropdownPlacement,
DropdownSize,
DropdownProps,
DropdownItemProps
} from '@ns/ui'
type DropdownTrigger = 'hover' | 'click' | 'contextmenu'
type DropdownSize = 'large' | 'default' | 'small'
type DropdownPlacement =
| 'top'
| 'top-start'
| 'top-end'
| 'bottom'
| 'bottom-start'
| 'bottom-end'
| 'left'
| 'left-start'
| 'left-end'
| 'right'
| 'right-start'
| 'right-end'
interface DropdownProps {
trigger?: DropdownTrigger
placement?: DropdownPlacement
disabled?: boolean
hideOnClick?: boolean
tabindex?: number
visible?: boolean
size?: DropdownSize
splitButton?: boolean
// 'primary' | 'success' | 'warning' | 'danger' | 'info' | 'help' | 'default',从 NsButton 导出
type?: ButtonType
arrowLabel?: string
}
interface DropdownItemProps {
command?: string | number
disabled?: boolean
divided?: boolean
icon?: string
}
另外还导出了 DropdownMenuProps(空接口)、DropdownEmits、DropdownContext 和注入用的 DROPDOWN_INJECTION_KEY,自己写和 NsDropdown 配合的子组件时才用得到。
注意事项
NsDropdownItem必须放在NsDropdown里,单独使用会抛出错误。- 菜单项没有写
command时,command和click事件的参数是undefined。 - 要知道点了哪一项,监听
NsDropdown的command,不要在NsDropdownItem上写@click:禁用的菜单项不会触发command,但写在它上面的@click仍会触发。 v-model:visible绑定的变量已经会随用户的操作更新,不要再在触发元素上自己写点击事件去切换它,否则一次点击会被处理两次(开了又关)。要从别处打开、关闭,改这个变量或调用show()/hide()。- 只写
:visible、不接收update:visible时,显示与否完全由外部决定,用户的操作不起作用。 trigger="contextmenu"时菜单按触发元素定位(默认在它的左下方),不是出现在鼠标点的位置。- 触发元素外面会包一层可以聚焦的
div。里面放按钮时,按 Tab 会先停在这层div上,再停在按钮上;不想要外层这个停靠点时传:tabindex="-1"。分裂按钮没有这层div,tabindex设在两个按钮上。 - 分裂按钮主按钮的点击是
button-click,不是click:click和普通下拉菜单一样表示点了菜单项,写成@click的“保存”在主按钮上不会触发。 - 分裂按钮的两个按钮由组件自己渲染,默认插槽里只放主按钮的文字(可以带
NsIcon),不要再放NsButton。 - 菜单挂在
body下,用position: fixed定位,显示期间会跟着页面、滚动容器的滚动和窗口缩放重新定位。 - 放在对话框、抽屉里时,菜单显示着按 Esc 只收起菜单,不会把对话框、抽屉一起关掉。