XiaoDaiGua-Ray c2019b10e6
feat: enhance menu tags, breadcrumbs, and useMenu
Add configurable tab controls, breadcrumb icons, and interactive useMenu examples.
Batch pointer updates per frame and scope writes to the tab cache.
2026-11-19 12:25:05 +08:00

8.4 KiB
Raw Blame History

导航与菜单

从 @/hooks 导入本页 API。菜单来源、权限和路由记录见路由指南。

交互示例

::: details 查看示例源码 <<< @/../admin/src/views/demo/template-hooks/index.tsx :::

useVueRouter

::: details 查看路由示例源码 <<< @/../admin/src/views/demo/hooks/web-hooks.tsx :::

useVueRouter() 返回 { router },指向模板的共享 Vue Router 实例。当前路由用 router.currentRoute.value 读取,push、replace、back 等行为由 Vue Router 提供。它可在 setup 外取得实例。初始化后再访问依赖实际路由匹配的状态。

import { useVueRouter } from '@/hooks'

export const readQuery = () => useVueRouter().router.currentRoute.value.query

useAppNavigation

useAppNavigation().navigationTo(target, options?) 支持三类目标:

target 行为
完整路径字符串 先用 Router 解析,保留动态路径、query 和 hash。未匹配或只匹配兜底路由时返回 undefined。
AppMenuOption 按 fullPath 导航,保留参数与锚点;可用 query 覆盖同名参数。
从 0 开始的整数 从当前菜单取项,遇到父菜单沿第一个子项查到叶子。菜单需要先初始化。

NavigationToOptions.isPush 默认 true;设为 false 使用 router.replace。query 可覆盖字符串路径中的同名查询参数。成功发起时返回 Router Promise。负数、小数、非有限数和越界索引不会导航;实际结果仍受路由守卫影响。

import { useAppNavigation } from '@/hooks'

export function useTableNavigation() {
  const { navigationTo } = useAppNavigation()
  return () =>
    navigationTo('/tables/remote?tab=people', {
      isPush: false,
      query: { tab: 'orders' },
    })
}

useMenu

useMenu(options?) 封装 Naive UI 的 NMenu,可用于独立菜单示例、局部导航或选择器。传入原生菜单配置即可使用横向和纵向布局、分组、分隔线、自定义字段和渲染函数。

返回值 用途
menuRef 绑定到 NMenu 的组件引用。
menuProps 浅响应式的菜单属性,直接绑定给组件。异步加载时替换 menuProps.options。
showOption(key?) 展开指定菜单项的父级。省略 key 时展开当前选中项的父级,选中值保持原样。
deriveResponsiveState() 重新计算启用了 responsive 的横向菜单的溢出状态。

传入 value 或 expandedKeys 后,Hook 会先同步对应的属性,再调用原始更新回调。value: null 表示清除选中项,expandedKeys: [] 表示收起所有分组。省略某个属性时,由 NMenu 管理该状态并应用 defaultValue、defaultExpandedKeys 或 defaultExpandAll。组件挂载后即可调用实例方法,异步更新选项后可用 nextTick() 等待组件接收新数据。

import { useMenu } from '@/hooks'
import { NButton, NMenu } from 'naive-ui'
import { defineComponent } from 'vue'

export default defineComponent({
  setup() {
    const { menuRef, menuProps, showOption } = useMenu({
      options: [
        { key: 'overview', label: '概览' },
        {
          key: 'reports',
          label: '报表',
          children: [{ key: 'monthly', label: '月报' }],
        },
      ],
      value: 'monthly',
      expandedKeys: [],
    })

    return () => (
      <>
        <NMenu ref={menuRef} {...menuProps} />
        <NButton onClick={() => showOption()}>展开选中项</NButton>
      </>
    )
  },
})

工作区导航由 useAppNavigation 和路由菜单 Store 管理。独立菜单可用 useMenu,工作区菜单的键盘行为由 useMenuKeyboard 提供。Naive UI Menu API

useAppRoot(兼容接口)

此接口已废弃,仅为旧调用方保留历史偏好的读写。getRootRoute、getRootPath、getRootName 是计算引用,setRootRoute({ name?, path? }) 合并更新该字段;它不再控制登录落点、标签保护或关闭全部后的导航,也没有启动时首页校验。空工作区固定使用 /welcome。新代码直接通过 Router 显式导航。

import { useVueRouter } from '@/hooks'

export function useOpenWorkspace() {
  const { router } = useVueRouter()
  return () => router.replace('/welcome')
}

useSiderBar

操作工作区的标签页。接受 CloseMenuTag 的方法可传从 0 开始的索引、与标签 fullPath 匹配的字符串或标签对象。

方法 行为
getCurrentTagIndex() 当前标签索引;找不到返回 -1。
checkCloseLeft(target) / checkCloseRight(target) 检查目标对应方向是否有标签可关。
close(target) 关闭可关闭的业务标签。关闭激活项时切到相邻项,关闭最后一项后进入空工作区。
closeLeft(target) / closeRight(target) 关闭目标对应方向的可关闭标签。激活项被关闭时切换至目标。
closeOther(target) 保留目标和固定标签,并激活目标。
closeAll() 关闭可关闭标签,优先保留当前固定页面,再尝试第一个固定标签或 /welcome。

不要在存在未保存表单的工作流里直接调用批量关闭;这些方法不会替业务处理未保存确认。

import { useSiderBar } from '@/hooks'

export function useCloseActiveTag() {
  const { close, getCurrentTagIndex } = useSiderBar()
  return () => {
    const index = getCurrentTagIndex()
    if (index >= 0) close(index)
  }
}

useBadge

目标接受菜单的 fullPath 或 AppMenuOption。show(target, options?) 合并配置并显示,hidden(target) 保留原配置并隐藏,update(target, options) 只更新给出的字段。菜单未加载或未找到时不会添加标记。

AppMenuExtraOptions 支持 label(字符串或数字)、i18nLabel(翻译键)、icon(VNode)、type(Naive UI Tag 类型)、show(显隐)。使用翻译键时同步维护语言包。

import { useBadge } from '@/hooks'

export function useUnreadBadge() {
  const { show, hidden } = useBadge()
  const path = '/tables/remote'
  return (count: number) =>
    count > 0 ? show(path, { label: count, type: 'info' }) : hidden(path)
}

源码:useMenu · useAppNavigation · useAppRoot · useSiderBar · useBadge · useVueRouter