TinyVue NavMenu 导航菜单组件使用指南

TinyVue NavMenu 导航菜单组件使用指南

前言

导航菜单是中后台系统的核心骨架，直接影响用户能否快速定位所需功能。TinyVue 推出的 NavMenu 组件作为一款顶部水平导航菜单，具备多级子菜单、数据驱动、自定义服务加载、溢出处理、跳转前拦截等能力，同时内置 Logo 和工具栏插槽。面向企业级顶部导航栏搭建需求，该组件可提供完整解决方案。

组件介绍

NavMenu 是一款水平导航菜单组件，核心机制为数据驱动——通过 data 属性传入菜单数据即可渲染完整导航栏。该组件支持无限嵌套子菜单，可应对多层级结构需求。

核心特性

• 数据驱动：通过 data 属性一键配置菜单数据
• 自定义服务：fetch-menu-data 支持异步加载菜单数据
• 字段映射：fields 属性可自定义数据字段名，兼容后端字段差异
• 溢出处理：提供 auto、retract、fixed、hidden 四种模式，灵活控制菜单展示
• 跳转拦截：before-skip 钩子函数实现跳转前自定义逻辑
• 默认选中：default-active 属性指定当前高亮菜单项
• 扁平数据转树：parent-key 属性自动将扁平数组转换为树结构
• Logo 与工具栏插槽：支持左侧 Logo 和右侧工具栏自定义内容

基本用法

基础使用方式为通过 data 属性配置菜单数据。每个菜单项需包含 title（显示文本）、url（跳转地址）和 id（唯一标识）。子菜单使用 children 进行嵌套，支持多层结构：

数据结构

每个菜单项（IDataItem）的结构定义如下：

interface IDataItem {
  title: string    // 显示文本
  url: string      // 跳转地址
  id: string       // 唯一标识
  children: IDataItem[]  // 子菜单（可选）
}

溢出处理

当一级菜单数量超出容器宽度时，可通过 overflow 属性配置溢出处理方式，共提供四种模式：

overflow 值	说明
auto	默认值。右侧显示"更多"菜单，鼠标悬停时展示剩余菜单
fixed	左侧显示三明治折叠图标，悬停时展示所有菜单
retract	不显示任何菜单，仅显示三明治图标，悬停时展示所有菜单
hidden	未展示的菜单直接隐藏

跳转前处理

在实际应用中，菜单点击后往往需要先执行权限校验、埋点上报或前端路由跳转等操作。通过 before-skip 钩子函数可在菜单跳转前执行自定义逻辑，返回 false 可阻止默认跳转：

钩子函数参数

before-skip 接收一个 IMenuItem 对象，包含菜单的完整信息：

interface IMenuItem {
  id: string         // 菜单 ID
  title: string      // 菜单标题
  url: string        // 跳转地址
  route: string      // 路由地址
  target: string     // 打开方式
  pid: string        // 父级 ID
  isFullUrl: boolean // 是否为完整 URL
}

配合 prevent 阻止默认服务跳转

需要注意：如果使用了组件默认服务（/workspace/current）获取菜单数据，仅靠 before-skip 无法完全阻止跳转，需同时将 prevent 设为 true：

自定义菜单服务

若菜单数据需从后端 API 异步获取，可使用 fetch-menu-data 属性。该属性接收一个返回 Promise 的函数：

字段映射（fields）

实际项目中后端返回的数据字段名可能与组件默认字段不同，例如使用 name、path 等命名。此时无需手动转换数据，直接通过 fields 映射即可：

interface IFields {
  textField: string   // 文本字段名，默认 'title'
  urlField: string    // URL 字段名，默认 'url'
  key: string        // 唯一标识字段名，默认 'id'
}

自定义选中菜单

页面加载时如需默认高亮某个菜单项，可通过 default-active 属性传入对应菜单项的 id 即可实现：

扁平数据转树结构

许多后端接口返回扁平数组，通过 pid 字段标识父子关系。NavMenu 组件提供 parent-key 属性，只需指定父级标识字段，组件即可自动完成树结构转换：

Logo 插槽

导航栏左侧通常用于放置公司 Logo。通过 logo 插槽可自定义图标、文字或图片等内容：

工具栏插槽

右侧工具栏区域通过 toolbar 插槽自定义，适用于用户头像、设置按钮、消息通知等高频操作：

API 参考

Props

属性名	类型	默认值	说明
data	IDataItem[]	-	菜单数据
fetch-menu-data	() => Promise	-	自定义菜单数据加载服务
fields	IFields	{ textField: 'title', urlField: 'url', key: 'id' }	自定义数据字段映射
overflow	'auto' | 'retract' | 'fixed' | 'hidden'	'auto'	一级菜单溢出时的显示方式
before-skip	(item: IMenuItem) => boolean	-	点击跳转前的钩子函数，返回 false 阻止跳转
prevent	boolean	false	配合 before-skip 阻止默认服务的跳转行为
parent-key	string	-	父级菜单标识字段，用于扁平数组转树结构
default-active	string	-	当前选中菜单的 id

Slots

插槽名	说明
logo	菜单栏左侧 Logo 插槽
toolbar	菜单栏右侧工具栏插槽

Types

// 菜单项（跳转钩子参数）
interface IMenuItem {
  id: string
  isFullUrl: boolean
  pid: string
  route: string
  target: string
  title: string
  url: string
}// 数据项
interface IDataItem {
  title: string
  url: string
  children: IDataItem[]
}// 字段映射
interface IFields {
  textField: string
  urlField: string
  key: string
}

最佳实践

1. SPA 应用中使用 before-skip 拦截跳转

在单页应用中，菜单点击后应使用 Vue Router 进行导航而非直接跳转。通过 before-skip 拦截默认行为并调用路由的 push 方法：

2. 后端数据适配使用 fields 映射

后端字段名不匹配时无需手动修改数据，直接使用 fields 映射即可实现快速适配：

3. 扁平数据使用 parent-key 自动转树

面对后端返回的扁平数组时无需编写递归转换函数，设置 parent-key 属性即可由组件自动处理：

4. 溢出处理根据场景选择

• 桌面端宽屏：使用 overflow="auto"（默认值），超出菜单自动收入"更多"区域
• 桌面端窄屏：使用 overflow="fixed"，悬停三明治图标展开所有菜单
• 移动端：使用 overflow="retract"，仅显示三明治图标，菜单完全折叠

5. 工具栏放置高频操作

用户头像、消息通知、设置入口等高频操作建议放置在 toolbar 插槽中，与导航菜单同行展示，可有效节省垂直空间。

总结

TinyVue NavMenu 作为一款数据驱动的水平导航菜单组件，全面覆盖企业级应用场景。核心功能回顾如下：data 配置菜单数据并支持多级嵌套；fetch-menu-data 实现异步菜单加载；fields 映射非标准字段名；overflow 处理菜单溢出（auto、fixed、retract、hidden）；before-skip 拦截跳转；default-active 指定选中项；parent-key 自动转换扁平数据为树结构；logo 和 toolbar 插槽自定义左右区域。掌握上述功能后，搭建顶部导航栏将更加高效顺畅。

---