Menu 菜单
网站的导航菜单,可以横着放在页头,也可以竖着放在侧边栏,支持多级子菜单和折叠。由 NsMenu、NsSubMenu、NsMenuItem 三个组件配合使用。
引入
import { NsMenu, NsSubMenu, NsMenuItem } from '@ns/ui'
基础用法
默认是纵向菜单。每个 NsMenuItem 和 NsSubMenu 都要有一个唯一的 index。default-active 指定一开始选中哪一项,点菜单项时触发 select,参数里有这一项的 index 和它所在的各级子菜单的 index。
<script setup lang="ts">
import { ref } from 'vue'
import { NsMenu, NsSubMenu, NsMenuItem } from '@ns/ui'
const selected = ref('1')
const path = ref<string[]>([])
const handleSelect = (index: string, indexPath: string[]) => {
selected.value = index
path.value = indexPath
}
</script>
<template>
<NsMenu default-active="1" style="width: 240px" @select="handleSelect">
<NsMenuItem index="1">工作台</NsMenuItem>
<NsSubMenu index="2" title="系统管理">
<NsMenuItem index="2-1">用户管理</NsMenuItem>
<NsMenuItem index="2-2">角色管理</NsMenuItem>
</NsSubMenu>
<NsMenuItem index="3">消息中心</NsMenuItem>
</NsMenu>
<p style="margin-top: 12px">
选中:{{ selected }},所在子菜单:{{ path.length ? path.join(' / ') : '无' }}
</p>
</template>
菜单方向
mode 可选 vertical(纵向,默认)和 horizontal(横向)。
- 纵向菜单竖着排,子菜单就地展开在标题下面,适合放在侧边栏。
- 横向菜单横着排,高 60px,适合放在页头。子菜单在标题下方以浮层弹出,鼠标移入 150 毫秒后打开,移出 150 毫秒后收起;多级子菜单在上一级浮层的右侧弹出。点了某个菜单项后,浮层全部收起。菜单项放不下时,菜单可以横向滚动,子菜单标题不会被压缩。
<template>
<NsSpace direction="vertical" fill size="large">
<div>
<p class="row-label">horizontal</p>
<NsMenu mode="horizontal" default-active="1">
<NsMenuItem index="1">首页</NsMenuItem>
<NsSubMenu index="2" title="产品中心">
<NsMenuItem index="2-1">产品列表</NsMenuItem>
<NsMenuItem index="2-2">产品分类</NsMenuItem>
<NsSubMenu index="2-3" title="更多">
<NsMenuItem index="2-3-1">产品统计</NsMenuItem>
<NsMenuItem index="2-3-2">产品日志</NsMenuItem>
</NsSubMenu>
</NsSubMenu>
<NsMenuItem index="3">关于我们</NsMenuItem>
</NsMenu>
</div>
<div>
<p class="row-label">vertical</p>
<NsMenu mode="vertical" default-active="1" style="width: 240px">
<NsMenuItem index="1">首页</NsMenuItem>
<NsSubMenu index="2" title="产品中心">
<NsMenuItem index="2-1">产品列表</NsMenuItem>
<NsMenuItem index="2-2">产品分类</NsMenuItem>
<NsSubMenu index="2-3" title="更多">
<NsMenuItem index="2-3-1">产品统计</NsMenuItem>
<NsMenuItem index="2-3-2">产品日志</NsMenuItem>
</NsSubMenu>
</NsSubMenu>
<NsMenuItem index="3">关于我们</NsMenuItem>
</NsMenu>
</div>
</NsSpace>
</template>
<style scoped>
.row-label {
margin: 0 0 8px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
横向菜单也可以带图标、禁用项:
<template>
<NsMenu mode="horizontal" default-active="1">
<NsMenuItem index="1" icon="home">首页</NsMenuItem>
<NsSubMenu index="2" title="产品中心" icon="apps">
<NsMenuItem index="2-1" icon="file">产品列表</NsMenuItem>
<NsMenuItem index="2-2" icon="folder">产品分类</NsMenuItem>
</NsSubMenu>
<NsMenuItem index="3" icon="bell">消息</NsMenuItem>
<NsMenuItem index="4" icon="lock" disabled>管理后台</NsMenuItem>
</NsMenu>
</template>
多级子菜单
纵向菜单里,子菜单就地展开在标题下面,点标题展开或收起,子级按层级缩进。选中某个子菜单里的项时,它所在的各级子菜单标题也会显示成激活色。
<template>
<NsMenu default-active="2-2-1" style="width: 240px">
<NsMenuItem index="1">工作台</NsMenuItem>
<NsSubMenu index="2" title="系统管理">
<NsMenuItem index="2-1">用户管理</NsMenuItem>
<NsSubMenu index="2-2" title="权限管理">
<NsMenuItem index="2-2-1">角色管理</NsMenuItem>
<NsMenuItem index="2-2-2">菜单管理</NsMenuItem>
</NsSubMenu>
</NsSubMenu>
</NsMenu>
</template>
默认展开和默认激活
default-active 指向某个子菜单里的项时,挂载后会自动展开它所在的各级子菜单(只在纵向、没有折叠时这样做)。default-openeds 指定一开始展开哪些子菜单。
这两个属性运行时修改也会生效:改 default-active 会选中新的项并展开它所在的子菜单;default-openeds 的内容变了,展开的子菜单会重置成新的列表。
<script setup lang="ts">
import { ref } from 'vue'
import { NsMenu, NsSubMenu, NsMenuItem, NsButton, NsSpace } from '@ns/ui'
const active = ref('2-1')
const openeds = ref(['3'])
</script>
<template>
<NsSpace wrap style="margin-bottom: 12px">
<NsButton @click="active = '3-2'">选中“操作日志”</NsButton>
<NsButton @click="active = '2-2'">选中“角色管理”</NsButton>
<NsButton @click="openeds = ['2', '3']">展开全部</NsButton>
<NsButton @click="openeds = []">收起全部</NsButton>
</NsSpace>
<NsMenu :default-active="active" :default-openeds="openeds" style="width: 240px">
<NsMenuItem index="1">工作台</NsMenuItem>
<NsSubMenu index="2" title="系统管理">
<NsMenuItem index="2-1">用户管理</NsMenuItem>
<NsMenuItem index="2-2">角色管理</NsMenuItem>
</NsSubMenu>
<NsSubMenu index="3" title="日志">
<NsMenuItem index="3-1">登录日志</NsMenuItem>
<NsMenuItem index="3-2">操作日志</NsMenuItem>
</NsSubMenu>
</NsMenu>
</template>
只展开一个子菜单(手风琴)
unique-opened 为 true 时,展开一个子菜单会自动收起其他不相关的子菜单,它自己的上级不受影响。下面左边是默认,可以同时展开多个;右边开了 unique-opened:
<template>
<NsSpace align="start" size="large" wrap>
<NsMenu style="width: 240px">
<NsSubMenu index="1" title="系统管理">
<NsMenuItem index="1-1">用户管理</NsMenuItem>
<NsMenuItem index="1-2">角色管理</NsMenuItem>
</NsSubMenu>
<NsSubMenu index="2" title="日志">
<NsMenuItem index="2-1">登录日志</NsMenuItem>
<NsMenuItem index="2-2">操作日志</NsMenuItem>
</NsSubMenu>
</NsMenu>
<NsMenu unique-opened style="width: 240px">
<NsSubMenu index="1" title="系统管理">
<NsMenuItem index="1-1">用户管理</NsMenuItem>
<NsMenuItem index="1-2">角色管理</NsMenuItem>
</NsSubMenu>
<NsSubMenu index="2" title="日志">
<NsMenuItem index="2-1">登录日志</NsMenuItem>
<NsSubMenu index="2-2" title="操作日志">
<NsMenuItem index="2-2-1">新增记录</NsMenuItem>
<NsMenuItem index="2-2-2">删除记录</NsMenuItem>
</NsSubMenu>
</NsSubMenu>
</NsMenu>
</NsSpace>
</template>
图标和折叠
NsMenuItem 和 NsSubMenu 的 icon 在文字前面显示一个图标(NsIcon 的 name)。collapse 为 true 时菜单宽度变成 64px,顶层的菜单项和子菜单标题只显示图标;子菜单改成在右侧以浮层弹出,悬停或点击标题打开。切到折叠时,已经展开的子菜单会全部收起。
折叠模式下顶层项要写 icon,否则只剩一块空白。
<script setup lang="ts">
import { ref } from 'vue'
import { NsMenu, NsSubMenu, NsMenuItem, NsSwitch } from '@ns/ui'
const collapsed = ref(false)
</script>
<template>
<div style="margin-bottom: 12px">
<NsSwitch v-model="collapsed" active-text="折叠" />
</div>
<NsMenu :collapse="collapsed" default-active="1">
<NsMenuItem index="1" icon="home">工作台</NsMenuItem>
<NsSubMenu index="2" title="系统管理" icon="setting">
<NsMenuItem index="2-1" icon="user">用户管理</NsMenuItem>
<NsMenuItem index="2-2" icon="users">角色管理</NsMenuItem>
</NsSubMenu>
<NsMenuItem index="3" icon="bell">消息中心</NsMenuItem>
</NsMenu>
</template>
禁用
NsMenuItem 或 NsSubMenu 的 disabled 为 true 时,点击、悬停和键盘都不起作用,Tab 键也会跳过它。子菜单里的项也可以单独禁用。
<template>
<NsMenu style="width: 240px" :default-openeds="['4']">
<NsMenuItem index="1">工作台</NsMenuItem>
<NsMenuItem index="2" disabled>数据大屏(建设中)</NsMenuItem>
<NsSubMenu index="3" title="系统管理" disabled>
<NsMenuItem index="3-1">用户管理</NsMenuItem>
</NsSubMenu>
<NsSubMenu index="4" title="日志">
<NsMenuItem index="4-1">登录日志</NsMenuItem>
<NsMenuItem index="4-2" disabled>审计日志(无权限)</NsMenuItem>
</NsSubMenu>
</NsMenu>
</template>
自定义颜色
background-color、text-color、active-text-color 分别设置菜单的背景色、文字色和选中项的文字色,横向、折叠模式下的浮层也用同样的颜色。值会写进内联样式,可以用主题变量。
<template>
<NsSpace direction="vertical" fill>
<NsMenu
mode="horizontal"
default-active="1"
background-color="var(--ns-color-primary-darker)"
text-color="var(--ns-color-white)"
active-text-color="var(--ns-color-warning)"
>
<NsMenuItem index="1" icon="home">工作台</NsMenuItem>
<NsSubMenu index="2" title="系统管理" icon="setting">
<NsMenuItem index="2-1">用户管理</NsMenuItem>
<NsMenuItem index="2-2">角色管理</NsMenuItem>
</NsSubMenu>
<NsMenuItem index="3" icon="bell">消息中心</NsMenuItem>
</NsMenu>
<NsMenu
default-active="1"
background-color="var(--ns-color-primary-darker)"
text-color="var(--ns-color-white)"
active-text-color="var(--ns-color-warning)"
style="width: 240px"
>
<NsMenuItem index="1" icon="home">工作台</NsMenuItem>
<NsSubMenu index="2" title="系统管理" icon="setting">
<NsMenuItem index="2-1">用户管理</NsMenuItem>
<NsMenuItem index="2-2">角色管理</NsMenuItem>
</NsSubMenu>
</NsMenu>
</NsSpace>
</template>
自定义标题
NsMenuItem 的文字可以写在默认插槽里,也可以写在 title 插槽里,两个都写时只显示 title 插槽。折叠模式下顶层项隐藏的就是这部分内容,图标仍然显示。
NsSubMenu 的 title 插槽替换掉图标和标题文字(右边的箭头保留)。标题行是两端对齐的,插槽里有多个元素时用一个元素包起来,否则它们会被拉开。折叠模式下组件分不清插槽里哪部分是图标、哪部分是文字,不会隐藏它,所以要折叠的菜单请用 icon 和 title 属性。
<script setup lang="ts">
import { NsMenu, NsSubMenu, NsMenuItem, NsIcon } from '@ns/ui'
</script>
<template>
<NsMenu style="width: 240px">
<NsMenuItem index="1">
<template #title>工作台</template>
</NsMenuItem>
<NsSubMenu index="2">
<template #title>
<span>
<NsIcon name="mail" />
消息中心
<span style="color: var(--ns-text-color-secondary)">(12 条未读)</span>
</span>
</template>
<NsMenuItem index="2-1">站内信</NsMenuItem>
<NsMenuItem index="2-2">系统通知</NsMenuItem>
</NsSubMenu>
</NsMenu>
</template>
路由模式
router 为 true 时,点了传了 route 的菜单项,菜单会在触发 select 之后调用 app.config.globalProperties.$router.push(route)。route 可以是路径字符串,也可以是路由对象。
组件库不依赖 vue-router,用的是应用 app.use(router) 后挂上的 $router。没有传 route 的菜单项不会跳转(不会拿 index 当路径);应用没有注册路由时也不跳转。菜单不会跟着当前路由自动切换选中项,要把当前路径绑到 default-active 上。
<script setup lang="ts">
import { useRoute } from 'vue-router'
import { NsMenu, NsMenuItem } from '@ns/ui'
const route = useRoute()
</script>
<template>
<NsMenu router :default-active="route.path" style="width: 240px">
<NsMenuItem index="/dashboard" route="/dashboard">工作台</NsMenuItem>
<NsMenuItem index="/users" :route="{ path: '/users', query: { page: 1 } }">用户管理</NsMenuItem>
</NsMenu>
</template>
浮层的自定义类名
NsSubMenu 的 popper-class 会加到子菜单的列表 ul(类名 ns-sub-menu__menu)上。横向、折叠模式下这个列表是浮层,挂在 body 下,所以:
- 样式不要写在
scoped里,要写成全局样式; - 不要用
.ns-menu .my-popup这类以菜单为祖先的后代选择器,直接用.my-popup。
<template>
<NsMenu mode="horizontal">
<NsSubMenu index="1" title="更多" popper-class="my-menu-popup">
<NsMenuItem index="1-1">帮助文档</NsMenuItem>
<NsMenuItem index="1-2">意见反馈</NsMenuItem>
</NsSubMenu>
</NsMenu>
</template>
<style>
.my-menu-popup {
min-width: 260px;
border: 1px solid var(--ns-border-color);
}
</style>
监听展开和收起
子菜单展开时触发 open,收起时触发 close,参数是这个子菜单的 index 和它的各级上级子菜单的 index。
<script setup lang="ts">
import { ref } from 'vue'
import { NsMenu, NsSubMenu, NsMenuItem } from '@ns/ui'
const log = ref('还没有展开或收起')
const handleOpen = (index: string, indexPath: string[]) => {
log.value = `open:${index},上级:${indexPath.length ? indexPath.join(' / ') : '无'}`
}
const handleClose = (index: string, indexPath: string[]) => {
log.value = `close:${index},上级:${indexPath.length ? indexPath.join(' / ') : '无'}`
}
</script>
<template>
<NsMenu style="width: 240px" @open="handleOpen" @close="handleClose">
<NsSubMenu index="1" title="系统管理">
<NsMenuItem index="1-1">用户管理</NsMenuItem>
<NsSubMenu index="1-2" title="权限管理">
<NsMenuItem index="1-2-1">角色管理</NsMenuItem>
<NsMenuItem index="1-2-2">菜单管理</NsMenuItem>
</NsSubMenu>
</NsSubMenu>
<NsSubMenu index="2" title="日志">
<NsMenuItem index="2-1">登录日志</NsMenuItem>
</NsSubMenu>
</NsMenu>
<p style="margin-top: 12px">{{ log }}</p>
</template>
通过方法展开、收起
通过 NsMenu 的 ref 调用 open(index, indexPath)、close(index, indexPath)。indexPath 是这个子菜单的各级上级子菜单的 index,顶层子菜单传 [];unique-opened 时靠它判断哪些子菜单要保留。ref 上还能读到当前选中项 activeIndex 和展开的子菜单 openedMenus。
<script setup lang="ts">
import { ref } from 'vue'
import { NsMenu, NsSubMenu, NsMenuItem, NsButton, NsSpace } from '@ns/ui'
const menuRef = ref<InstanceType<typeof NsMenu>>()
const state = ref('')
const readState = () => {
const menu = menuRef.value
if (!menu) return
const opened = Array.from(menu.openedMenus)
state.value = `activeIndex:${menu.activeIndex || '无'},openedMenus:${opened.length ? opened.join('、') : '无'}`
}
</script>
<template>
<div style="margin-bottom: 12px">
<NsSpace wrap>
<NsButton @click="menuRef?.open('2', [])">展开系统管理</NsButton>
<NsButton @click="menuRef?.close('2', [])">收起系统管理</NsButton>
<NsButton @click="readState">读取状态</NsButton>
<span>{{ state }}</span>
</NsSpace>
</div>
<NsMenu ref="menuRef" default-active="1" style="width: 240px">
<NsMenuItem index="1">工作台</NsMenuItem>
<NsSubMenu index="2" title="系统管理">
<NsMenuItem index="2-1">用户管理</NsMenuItem>
<NsMenuItem index="2-2">角色管理</NsMenuItem>
</NsSubMenu>
</NsMenu>
</template>
键盘操作
没禁用的菜单项和子菜单标题都可以用 Tab 键聚焦。
| 按键 | 作用 |
|---|---|
↑、↓ | 纵向菜单的顶层、内嵌子菜单和浮层里:在同一层的项之间循环移动焦点 |
←、→ | 横向菜单的顶层:在顶层各项之间循环移动焦点 |
Enter、空格 | 在菜单项上:选中这一项。在子菜单标题上:内嵌时展开或收起;浮层模式下打开浮层并聚焦第一项 |
↓ | 横向菜单顶层的子菜单标题上:打开浮层并聚焦第一项 |
→ | 向右弹出的子菜单标题上(多级浮层里的、折叠模式顶层的):打开浮层并聚焦第一项 |
Esc | 浮层里:收起当前这一层浮层,焦点回到它的标题 |
← | 向右弹出的浮层里:同 Esc |
NsMenu Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| mode | 'horizontal' | 'vertical' | 'vertical' | 菜单方向 |
| defaultActive | string | '' | 选中项的 index。运行时修改会选中新的项,并展开它所在的子菜单 |
| defaultOpeneds | string[] | [] | 一开始展开的子菜单的 index。内容变了时,展开的子菜单重置成新的列表 |
| collapse | boolean | false | 是否折叠(只在纵向菜单上使用)。折叠后宽 64px,顶层只显示图标 |
| backgroundColor | string | - | 菜单的背景色,浮层也用这个颜色 |
| textColor | string | - | 菜单的文字色,浮层也用这个颜色 |
| activeTextColor | string | - | 选中项和它所在子菜单标题的文字色。不传时用主色 |
| router | boolean | false | 是否在点菜单项时调用 $router.push(route)。只对传了 route 的项生效 |
| uniqueOpened | boolean | false | 是否只保持一个子菜单展开 |
NsSubMenu Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| index | string | - | 唯一标识,必填 |
| title | string | '' | 标题文字。写了 title 插槽时不显示 |
| icon | string | - | 标题前的图标名(NsIcon 的 name),折叠模式下顶层只显示它 |
| disabled | boolean | false | 是否禁用 |
| popperClass | string | '' | 加在子菜单列表 ul 上的类名。浮层挂在 body 下,样式要写成全局样式 |
NsMenuItem Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| index | string | - | 唯一标识,必填 |
| route | string | Record<string, unknown> | - | 路由目标。NsMenu 开了 router 时,点击后传给 $router.push |
| icon | string | - | 文字前的图标名(NsIcon 的 name),折叠模式下顶层只显示它 |
| disabled | boolean | false | 是否禁用 |
NsMenu Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| select | (index: string, indexPath: string[], item: MenuItemContext) | 点菜单项(或在上面按回车、空格)时触发,点的是已选中的项也触发。indexPath 是它所在的各级子菜单的 index,不包含它自己 |
| open | (index: string, indexPath: string[]) | 子菜单展开时触发。indexPath 是这个子菜单的各级上级子菜单的 index |
| close | (index: string, indexPath: string[]) | 子菜单收起时触发,参数同 open |
NsMenu Slots
| 插槽 | 作用域参数 | 说明 |
|---|---|---|
| default | - | 放 NsMenuItem、NsSubMenu |
NsSubMenu Slots
| 插槽 | 作用域参数 | 说明 |
|---|---|---|
| default | - | 子菜单里的 NsMenuItem、NsSubMenu |
| title | - | 标题内容,替换掉图标和 title 文字,右边的箭头保留 |
NsMenuItem Slots
| 插槽 | 作用域参数 | 说明 |
|---|---|---|
| default | - | 菜单项的文字 |
| title | - | 菜单项的文字,写了它时不显示默认插槽。折叠时顶层隐藏 |
NsMenu 暴露的属性和方法
通过组件的 ref 读取、调用。
| 名称 | 类型 | 说明 |
|---|---|---|
| activeIndex | string | 当前选中项的 index |
| openedMenus | Set<string> | 当前展开的子菜单的 index |
| open | (index: string, indexPath: string[]) => void | 展开子菜单并触发 open,已经展开时什么也不做。不检查禁用,也不展开上级 |
| close | (index: string, indexPath: string[]) => void | 收起子菜单并触发 close,已经收起时什么也不做 |
类型
import type {
MenuMode,
MenuRoute,
MenuProps,
SubMenuProps,
MenuItemProps,
MenuItemContext
} from '@ns/ui'
import type { Ref } from 'vue'
type MenuMode = 'horizontal' | 'vertical'
type MenuRoute = string | Record<string, unknown>
interface MenuProps {
mode?: MenuMode
defaultActive?: string
defaultOpeneds?: string[]
collapse?: boolean
backgroundColor?: string
textColor?: string
activeTextColor?: string
router?: boolean
uniqueOpened?: boolean
}
interface SubMenuProps {
index: string
title?: string
disabled?: boolean
popperClass?: string
icon?: string
}
interface MenuItemProps {
index: string
route?: MenuRoute
disabled?: boolean
icon?: string
}
/** select 事件的第三个参数 */
interface MenuItemContext {
index: string
rootMenu: MenuContext
parentMenu: SubMenuContext | null
active: Ref<boolean>
disabled: Ref<boolean>
/** 所在的各级子菜单的 index,不包含自己 */
indexPath: string[]
route?: MenuRoute
}
另外还导出了 MenuEmits、MenuContext、SubMenuContext 和注入用的 MENU_INJECTION_KEY、SUB_MENU_INJECTION_KEY,自己写和 NsMenu 配合的子组件时才用得到。
注意事项
NsMenuItem、NsSubMenu必须放在NsMenu里,单独使用会抛出错误。index在整个菜单里要唯一。重复时两项会同时显示为选中,自动展开所在子菜单时只认后挂载的那一项。default-active、default-openeds只是初始值和“外部设定值”,用户点击后的选中、展开状态保存在组件里,不会写回这两个属性。要知道当前状态,监听select、open、close,或读 ref 上的activeIndex、openedMenus。- 自动展开选中项所在子菜单的逻辑只在纵向、没有折叠时执行。
- 以下几种情况子菜单会收起,但不触发
close:横向或折叠模式下点了菜单项(浮层全部收起)、切到折叠、default-openeds的内容变了。 - 横向、折叠模式的浮层挂在
body下,用position: fixed定位,z-index是 2000,不会被菜单外层的overflow裁掉,靠近视口边缘时会翻到另一侧。 - 选中项默认是主色文字加浅主色底色,悬停时底色不变。
active-text-color只改文字色。设了background-color时,选中项的底色改成在菜单背景上叠一层半透明的底(--ns-bg-color-active),不再用浅主色底,免得和自定义的文字色搭不上;横向菜单的顶层选中项仍然只有下边框。悬停的底色不受这三个颜色属性影响。 - 菜单项的文字只显示一行,太长时显示省略号。