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.
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),不再用浅主色底,免得和自定义的文字色搭不上;横向菜单的顶层选中项仍然只有下边框。悬停的底色不受这三个颜色属性影响。 - 菜单项的文字只显示一行,太长时显示省略号。