@@ -256,6 +274,59 @@ export default defineComponent({
),
)}
+ {example(
+ 'useMenu',
+ `const { menuRef, menuProps, showOption } = useMenu({
+ options: [
+ { key: 'overview', label: 'Overview' },
+ {
+ key: 'reports',
+ label: 'Reports',
+ children: [
+ { key: 'daily', label: 'Daily report' },
+ { key: 'monthly', label: 'Monthly report' },
+ ],
+ },
+ ],
+ value: 'monthly',
+ expandedKeys: [],
+})
+
+// TSX
+
+ showOption('monthly')}>Reveal monthly report`,
+ () => (
+
+
+
+ showOption('monthly')}>
+ {text('menuReveal')}
+
+ (menuProps.value = null)}
+ >
+ {text('menuClear')}
+
+
+
+ {t('menuState', {
+ selected: menuProps.value ?? '—',
+ expanded: menuProps.expandedKeys?.join(', ') || '—',
+ })}
+
+
+ ),
+ )}
diff --git a/apps/docs/guide/layout.md b/apps/docs/guide/layout.md
index 486a896c..0f7462e0 100644
--- a/apps/docs/guide/layout.md
+++ b/apps/docs/guide/layout.md
@@ -41,6 +41,14 @@ updateSettingState('layoutConfig', {
在「偏好设置 → 外观 → 界面显示」开启「胶囊形页面标签」可切换标签形状。默认关闭;刷新后保留,也可随偏好文件导出和导入。
+### 页面标签与面包屑
+
+- 右键点击标签或打开右侧「标签页操作」菜单,可置顶或固定标签。置顶将标签移至最左侧,取消置顶时移到普通标签组开头。固定会阻止单个关闭和批量关闭操作。
+- 拖动标签左侧的手柄可以排序。也可聚焦手柄后按 Shift + ← 或 Shift + →。置顶标签和普通标签各自组内排序。顺序、置顶和固定状态随当前会话刷新恢复。
+- 面包屑复用菜单配置中的图标,支持 SVG 图标名和代码路由里的图片 VNode。缺少图标时使用统一的文档图标。窄屏显示当前路径项及其图标。
+
+「偏好设置 → 外观 → 界面显示」提供五个独立开关,默认全部开启。关闭固定或置顶开关会暂停对应效果并保留标签标记,重新开启后恢复生效。关闭面包屑图标开关会一并隐藏占位图标,也可单独关闭占位图标。
+
## 菜单图标
展开侧栏、移动端抽屉和顶部导航默认使用 20 px 的图标;折叠侧栏默认 22 px,方便只凭图形辨认菜单。线性图标跟随菜单状态和明暗主题变色。可在「偏好设置 → 菜单」调整「图标尺寸」与「折叠图标尺寸」,修改即时生效。紧凑和舒适预设只调整宽度、缩进和图标尺寸;折叠方式、侧栏折叠/展开、回到菜单顶部和刷新菜单也可直接操作。当前布局没有桌面侧栏时,侧栏快捷操作禁用,已配置的尺寸仍会保留。
diff --git a/apps/docs/reference/hooks.md b/apps/docs/reference/hooks.md
index 1f10166e..c3a87a55 100644
--- a/apps/docs/reference/hooks.md
+++ b/apps/docs/reference/hooks.md
@@ -2,14 +2,14 @@
模板的公开 Hooks 从 `@/hooks` 导入。与具体组件一起使用的 `useForm`、`useModal`、`useChart`、`useFlow` 从 `@/components` 导入,请看对应组件页。`useRequest` 从 `@/axios` 导入。
-| 需求 | API |
-| ---------------------------- | ---------------------------------- |
-| 跳转页面,操作标签和菜单标记 | [导航与菜单](./hooks/navigation) |
-| 内容最大化、重载或滚动 | [布局与滚动](./hooks/layout) |
-| 主题、语言、水印 | [主题与国际化](./hooks/appearance) |
-| 分页与右键菜单 | [组件交互](./hooks/interaction) |
-| 窗口尺寸、元素全屏和日期 | [窗口与日期](./hooks/browser) |
-| DOM 截图、打印 | [截图与打印](./hooks/output) |
+| 需求 | API |
+| -------------------------------------- | ---------------------------------- |
+| 封装菜单、跳转页面、操作标签和菜单标记 | [导航与菜单](./hooks/navigation) |
+| 内容最大化、重载或滚动 | [布局与滚动](./hooks/layout) |
+| 主题、语言、水印 | [主题与国际化](./hooks/appearance) |
+| 分页与右键菜单 | [组件交互](./hooks/interaction) |
+| 窗口尺寸、元素全屏和日期 | [窗口与日期](./hooks/browser) |
+| DOM 截图、打印 | [截图与打印](./hooks/output) |
需要订阅、事件或清理的 Hook 在 `setup()` 或有效的 Vue effect scope 中创建。在 DOM 挂载后或用户操作时执行截图、打印和全屏。`BasicTarget` 接受元素、ref 或 getter,解析规则和可用元素类型见[Vue 与 DOM 目标](./utils/browser#vue-目标解析)。
diff --git a/apps/docs/reference/hooks/navigation.md b/apps/docs/reference/hooks/navigation.md
index 9f6cc732..b7a37364 100644
--- a/apps/docs/reference/hooks/navigation.md
+++ b/apps/docs/reference/hooks/navigation.md
@@ -55,6 +55,53 @@ export function useTableNavigation() {
}
```
+## 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()` 等待组件接收新数据。
+
+```tsx
+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 () => (
+ <>
+
+
showOption()}>展开选中项
+ >
+ )
+ },
+})
+```
+
+工作区导航由 `useAppNavigation` 和路由菜单 Store 管理。独立菜单可用 `useMenu`,工作区菜单的键盘行为由 `useMenuKeyboard` 提供。[Naive UI Menu API](https://www.naiveui.com/zh-CN/components/menu#API)
+
## useAppRoot(兼容接口) {#useapproot}
@@ -74,14 +121,14 @@ export function useOpenWorkspace() {
操作工作区的标签页。接受 `CloseMenuTag` 的方法可传从 0 开始的索引、与标签 `fullPath` 匹配的字符串或标签对象。
-| 方法 | 行为 |
-| ---------------------------------------------------- | ------------------------------------------------------------ |
-| `getCurrentTagIndex()` | 当前标签索引;找不到返回 `-1`。 |
-| `checkCloseLeft(target)` / `checkCloseRight(target)` | 检查目标对应方向是否有标签可关。 |
-| `close(target)` | 关闭业务标签;激活项切到相邻项,最后一项关闭后进入空工作区。 |
-| `closeLeft(target)` / `closeRight(target)` | 关闭目标左侧或右侧标签。需要时切换至目标。 |
-| `closeOther(target)` | 只保留目标并激活。 |
-| `closeAll()` | 清空业务标签及其缓存,进入 `/welcome`,不依赖业务首页。 |
+| 方法 | 行为 |
+| ---------------------------------------------------- | -------------------------------------------------------------------------- |
+| `getCurrentTagIndex()` | 当前标签索引;找不到返回 `-1`。 |
+| `checkCloseLeft(target)` / `checkCloseRight(target)` | 检查目标对应方向是否有标签可关。 |
+| `close(target)` | 关闭可关闭的业务标签。关闭激活项时切到相邻项,关闭最后一项后进入空工作区。 |
+| `closeLeft(target)` / `closeRight(target)` | 关闭目标对应方向的可关闭标签。激活项被关闭时切换至目标。 |
+| `closeOther(target)` | 保留目标和固定标签,并激活目标。 |
+| `closeAll()` | 关闭可关闭标签,优先保留当前固定页面,再尝试第一个固定标签或 `/welcome`。 |
不要在存在未保存表单的工作流里直接调用批量关闭;这些方法不会替业务处理未保存确认。
@@ -114,4 +161,4 @@ export function useUnreadBadge() {
}
```
-源码:[useAppNavigation](https://github.com/XiaoDaiGua-Ray/ray-template/blob/main/apps/admin/src/hooks/template/useAppNavigation.ts) · [useAppRoot](https://github.com/XiaoDaiGua-Ray/ray-template/blob/main/apps/admin/src/hooks/template/useAppRoot.ts) · [useSiderBar](https://github.com/XiaoDaiGua-Ray/ray-template/blob/main/apps/admin/src/hooks/template/useSiderBar.ts) · [useBadge](https://github.com/XiaoDaiGua-Ray/ray-template/blob/main/apps/admin/src/hooks/template/useBadge.ts) · [useVueRouter](https://github.com/XiaoDaiGua-Ray/ray-template/blob/main/apps/admin/src/hooks/template/useVueRouter.ts)
+源码:[useMenu](https://github.com/XiaoDaiGua-Ray/ray-template/blob/main/packages/composables/src/useMenu.ts) · [useAppNavigation](https://github.com/XiaoDaiGua-Ray/ray-template/blob/main/apps/admin/src/hooks/template/useAppNavigation.ts) · [useAppRoot](https://github.com/XiaoDaiGua-Ray/ray-template/blob/main/apps/admin/src/hooks/template/useAppRoot.ts) · [useSiderBar](https://github.com/XiaoDaiGua-Ray/ray-template/blob/main/apps/admin/src/hooks/template/useSiderBar.ts) · [useBadge](https://github.com/XiaoDaiGua-Ray/ray-template/blob/main/apps/admin/src/hooks/template/useBadge.ts) · [useVueRouter](https://github.com/XiaoDaiGua-Ray/ray-template/blob/main/apps/admin/src/hooks/template/useVueRouter.ts)
diff --git a/apps/docs/reference/store/navigation.md b/apps/docs/reference/store/navigation.md
index 9b8834f3..709a8c2f 100644
--- a/apps/docs/reference/store/navigation.md
+++ b/apps/docs/reference/store/navigation.md
@@ -25,7 +25,7 @@
`depthSearchAppMenu(options, key)` 从菜单树按完整路径查找菜单项。`changeMenuModelValue` 不返回 Router 的导航 Promise;需要等待守卫结果时使用 Router 或 `navigationTo`。更新角色后还要同步服务端授权及直接路由校验,菜单过滤本身不能授权。
-`piniaMenuStore` 在 Local Storage 只持久化 `menuKey`、`collapsed`。标签列表单独使用 Session Storage 的 `appMenuTagOptions`。当前路由变化会重新同步菜单与面包屑,避免手工写缓存制造冲突。
+`piniaMenuStore` 在 Local Storage 持久化 `collapsed`。标签列表以 Session Storage 的 `appMenuTagOptions` 保存顺序及可选的 `topped`、`fixed` 标记。刷新时根据当前路由与权限恢复,访问被撤销的页面也会移出列表。当前路由变化会同步选中菜单与面包屑。
## KeepAlive Store
diff --git a/apps/docs/reference/store/setting.md b/apps/docs/reference/store/setting.md
index 511c6e32..5b7b135b 100644
--- a/apps/docs/reference/store/setting.md
+++ b/apps/docs/reference/store/setting.md
@@ -4,24 +4,26 @@
## Getters
-| Getter | 字段与默认行为 |
-| ---------------------------------------------- | ------------------------------------------------------------------------------------------ |
-| `getLayoutConfig` | `layoutConfig`,布局模式和工作区尺寸,见下表。 |
-| `getDrawerPlacement` | `drawerPlacement`,设置抽屉方向,默认 `right`。 |
-| `getPrimaryColorOverride` | Naive UI 生效的 token 覆盖,由当前风格、明暗和用户主色计算。 |
-| `getThemeStyle` / `getCustomPrimaryColor` | 界面风格与手动主色。默认 `modern`,未指定手动主色时使用风格原色。 |
-| `getAppTheme` / `getAppThemeStr` | `_appTheme` 为实际深色布尔值,`appTheme` 为 `light/dark/auto` 模式,初始 `light`。 |
-| `getLocaleLanguage` | `localeLanguage`,应用语言,默认读取历史值或系统默认配置。 |
-| `getMenuTagSwitch` / `getBreadcrumbSwitch` | `menuTagSwitch` / `breadcrumbSwitch`,默认显示标签和面包屑。 |
-| `getLockScreenSwitch` | `lockScreenSwitch`,锁屏设置弹窗显隐,默认关,不持久化。 |
-| `getCopyrightSwitch` | `copyrightSwitch`,默认显示版权区。 |
-| `getContentTransition` | `contentTransition`,路由切换动画,默认 `scale`。 |
-| `getWatermarkSwitch` / `getWatermarkConfig` | `watermarkSwitch` 默认关;配置包含文字、字体大小、行高、宽高、偏移、间隔、旋转和 `cross`。 |
-| `getAppRootRoute` | `appRootRoute`,默认 `{ name: 'Dashboard', path: '/dashboard' }`。 |
-| `getSideBarLogo` | `sideBarLogo`,`icon`、`title`、`url`、`jumpType`。默认 `logo/ray`,站内跳转到仪表盘。 |
-| `getKeepAliveConfig` | `keepAliveConfig`,默认开启、最多 10 个、排除列表为空。 |
-| `getMenuConfig` | `menuConfig`,侧栏、折叠、图标、手风琴与滚动配置。 |
-| `getColorWeakness` / `getDynamicDocumentTitle` | `colorWeakness` 默认关,`dynamicDocumentTitle` 默认开。 |
+| Getter | 字段与默认行为 |
+| ------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
+| `getLayoutConfig` | `layoutConfig`,布局模式和工作区尺寸,见下表。 |
+| `getDrawerPlacement` | `drawerPlacement`,设置抽屉方向,默认 `right`。 |
+| `getPrimaryColorOverride` | Naive UI 生效的 token 覆盖,由当前风格、明暗和用户主色计算。 |
+| `getThemeStyle` / `getCustomPrimaryColor` | 界面风格与手动主色。默认 `modern`,未指定手动主色时使用风格原色。 |
+| `getAppTheme` / `getAppThemeStr` | `_appTheme` 为实际深色布尔值,`appTheme` 为 `light/dark/auto` 模式,初始 `light`。 |
+| `getLocaleLanguage` | `localeLanguage`,应用语言,默认读取历史值或系统默认配置。 |
+| `getMenuTagSwitch` / `getBreadcrumbSwitch` | `menuTagSwitch` / `breadcrumbSwitch`,默认显示标签和面包屑。 |
+| `getMenuTagTop` / `getMenuTagFixed` / `getMenuTagDrag` | `menuTagTop` / `menuTagFixed` / `menuTagDrag`,默认启用标签置顶、固定和拖拽排序。 |
+| `getBreadcrumbIcon` / `getBreadcrumbIconFallback` | `breadcrumbIcon` / `breadcrumbIconFallback`,默认显示菜单图标和缺图时的占位图标。 |
+| `getLockScreenSwitch` | `lockScreenSwitch`,锁屏设置弹窗显隐,默认关,不持久化。 |
+| `getCopyrightSwitch` | `copyrightSwitch`,默认显示版权区。 |
+| `getContentTransition` | `contentTransition`,路由切换动画,默认 `scale`。 |
+| `getWatermarkSwitch` / `getWatermarkConfig` | `watermarkSwitch` 默认关;配置包含文字、字体大小、行高、宽高、偏移、间隔、旋转和 `cross`。 |
+| `getAppRootRoute` | `appRootRoute`,默认 `{ name: 'Dashboard', path: '/dashboard' }`。 |
+| `getSideBarLogo` | `sideBarLogo`,`icon`、`title`、`url`、`jumpType`。默认 `logo/ray`,站内跳转到仪表盘。 |
+| `getKeepAliveConfig` | `keepAliveConfig`,默认开启、最多 10 个、排除列表为空。 |
+| `getMenuConfig` | `menuConfig`,侧栏、折叠、图标、手风琴与滚动配置。 |
+| `getColorWeakness` / `getDynamicDocumentTitle` | `colorWeakness` 默认关,`dynamicDocumentTitle` 默认开。 |
`layoutConfig` 的 `mode` 为 `side`(默认)、`top`、`mixed`。`contentWidth` 默认 `fluid`,也可取 `fixed`。`contentMaxWidth` 默认 1200,限制在 640–2560;`contentPadding` 默认 16,限制在 0–48;`fixedHeader`、`fixedFooter` 默认开启。旧缓存水合时补齐字段并规范化范围。
diff --git a/packages/admin-shell/src/ShellTab.tsx b/packages/admin-shell/src/ShellTab.tsx
index 2d8aa2b5..182f59d2 100644
--- a/packages/admin-shell/src/ShellTab.tsx
+++ b/packages/admin-shell/src/ShellTab.tsx
@@ -9,6 +9,7 @@ export const ShellTab = defineComponent({
label: { type: String, required: true },
active: Boolean,
round: Boolean,
+ statusLabel: { type: String, default: '' },
closeLabel: { type: String, default: '' },
select: { type: Function as PropType<() => void>, required: true },
close: {
@@ -20,7 +21,7 @@ export const ShellTab = defineComponent({
default: void 0,
},
},
- setup(props) {
+ setup(props, { slots }) {
const setNativeCloseLabel = ({ el }: VNode) => {
if (!(el instanceof HTMLElement)) return
@@ -46,10 +47,14 @@ export const ShellTab = defineComponent({
}}
onClose={(event) => props.close?.(event.detail === 0)}
>
+ {slots.prefix?.()}