diff --git a/src/layouts/default/components/DefaultLayout.vue b/src/layouts/default/components/DefaultLayout.vue index eba6c1b1..353c445b 100644 --- a/src/layouts/default/components/DefaultLayout.vue +++ b/src/layouts/default/components/DefaultLayout.vue @@ -143,7 +143,7 @@ const dynamicHeaderTab = ref(null) const openHorizontalNavGroup = ref(null) const pendingHorizontalTab = ref<{ path: string; tab: string } | null>(null) -// 提供一个方法让其他组件注册动态标签页 +/** 注册页面动态标签页，并在页面可用后应用待切换的水平导航标签。 */ const registerDynamicHeaderTab = (tab: DynamicHeaderTab) => { // 保存注册标签页的路由路径 tab.routePath = route.path @@ -152,12 +152,12 @@ const registerDynamicHeaderTab = (tab: DynamicHeaderTab) => { applyPendingHorizontalTab() } -// 提供一个方法让其他组件取消注册动态标签页 +/** 取消当前页面注册的动态标签页。 */ const unregisterDynamicHeaderTab = () => { dynamicHeaderTab.value = null } -// 标签页值更新处理 +/** 更新当前动态标签页选中值，并通知注册页面同步状态。 */ const handleTabChange = (newValue: string) => { if (dynamicHeaderTab.value) { dynamicHeaderTab.value.modelValue = newValue @@ -227,7 +227,7 @@ onUnmounted(() => { } }) -// 监听Service Worker消息 +/** 处理 Service Worker 推送的离线状态消息。 */ const handleServiceWorkerMessage = (event: MessageEvent) => { if (event.data && event.data.type === 'OFFLINE_STATUS') { if (event.data.offline) { @@ -238,7 +238,7 @@ const handleServiceWorkerMessage = (event: MessageEvent) => { } } -// 检查是否可以使用下拉手势 +/** 判断当前页面状态是否允许使用主界面下拉快捷入口手势。 */ const canUsePullGesture = () => { // 检查是否在dashboard页面 const isDashboard = route.path === '/dashboard' || route.path === '/' @@ -279,7 +279,7 @@ const { }, }) -// 根据分类获取菜单列表 +/** 根据菜单分组标题获取当前用户可见的菜单项。 */ const getMenuList = (header: string) => { // 使用国际化菜单 const menus = getNavMenus(t) @@ -287,19 +287,22 @@ const getMenuList = (header: string) => { return filteredMenus.filter((item: NavMenu) => item.header === header) } -// 返回上一页 +/** 返回浏览历史中的上一页。 */ function goBack() { history.back() } +/** 同步主题定制器变更后的布局模式。 */ function handleThemeCustomizerChange(event: Event) { themeLayout.value = (event as CustomEvent).detail.layout } +/** 打开主题定制器面板。 */ function handleThemeCustomizerOpen() { showThemeCustomizer.value = true } +/** 判断水平导航菜单项是否匹配当前路由。 */ function isHorizontalNavActive(item: NavMenu) { const targetPath = normalizeMenuPath(item.to) if (!targetPath) return false @@ -309,18 +312,22 @@ function isHorizontalNavActive(item: NavMenu) { return currentPath === targetPath || currentPath.startsWith(`${targetPath}/`) } +/** 判断水平导航分组内是否存在当前路由激活项。 */ function isHorizontalNavGroupActive(group: { items: NavMenu[] }) { return group.items.some(isHorizontalNavActive) } +/** 判断菜单项是否存在可在水平导航中展示的动态标签。 */ function hasHorizontalDynamicTabs(item: NavMenu) { return showHorizontalThemeNav.value && getHorizontalNavTabs(item).length > 0 } +/** 判断水平导航动态标签是否为当前选中项。 */ function isHorizontalDynamicTabActive(tab: DynamicHeaderTabItem) { return dynamicHeaderTab.value?.modelValue === tab.tab } +/** 切换水平导航中的动态标签，必要时先跳转到目标页面。 */ async function handleHorizontalDynamicTabSelect(item: NavMenu, tab: DynamicHeaderTabItem) { const targetPath = normalizeMenuPath(item.to) const currentPath = normalizeMenuPath(route.path) @@ -336,28 +343,34 @@ async function handleHorizontalDynamicTabSelect(item: NavMenu, tab: DynamicHeade openHorizontalNavGroup.value = null } +/** 关闭当前展开的水平导航分组菜单。 */ function closeHorizontalNavGroup() { openHorizontalNavGroup.value = null } +/** 读取可能是 Ref 的值，空值时回落到默认值。 */ function resolveMaybeRefValue(value: T | ComputedRef | undefined, fallback: T): T { return isRef(value) ? value.value : (value ?? fallback) } +/** 解析动态头部按钮颜色。 */ function resolveHeaderButtonColor(button: DynamicHeaderTabButton) { return resolveMaybeRefValue(button.color, 'gray') } +/** 解析动态头部按钮加载状态。 */ function resolveHeaderButtonLoading(button: DynamicHeaderTabButton) { return resolveMaybeRefValue(button.loading, false) } +/** 校验权限后执行动态头部按钮动作。 */ function handleHeaderButtonClick(button: DynamicHeaderTabButton) { if (!hasItemPermission(button, userPermissions.value)) return button.action?.() } +/** 获取水平导航动态标签图标，不可渲染时使用默认圆点图标。 */ function getHorizontalTabIcon(tab: DynamicHeaderTabItem) { const icon = tab.icon?.trim() @@ -370,12 +383,14 @@ function getHorizontalTabIcon(tab: DynamicHeaderTabItem) { return icon } +/** 标准化菜单路径，移除末尾斜杠并保留根路径。 */ function normalizeMenuPath(value: unknown) { if (typeof value !== 'string') return '' return value.replace(/\/$/, '') || '/' } +/** 获取水平导航菜单项可展示的标签列表。 */ function getHorizontalNavTabs(item: NavMenu): DynamicHeaderTabItem[] { const targetPath = normalizeMenuPath(item.to) @@ -386,6 +401,7 @@ function getHorizontalNavTabs(item: NavMenu): DynamicHeaderTabItem[] { return item.tabs ?? [] } +/** 在目标页面注册动态标签后应用此前暂存的标签切换。 */ function applyPendingHorizontalTab() { if (!pendingHorizontalTab.value || !hasDynamicHeaderTab.value) return @@ -399,16 +415,17 @@ function applyPendingHorizontalTab() { pendingHorizontalTab.value = null } -// 关闭插件快速访问 +/** 关闭插件快速访问面板。 */ function handleClosePluginQuickAccess() { showPluginQuickAccess.value = false } -// 点击插件后关闭 +/** 点击插件入口后关闭插件快速访问面板。 */ function handlePluginClick() { showPluginQuickAccess.value = false } +/** 将插件侧边栏菜单合并到对应的导航分组中。 */ function appendPluginSidebarMenus() { for (const { navMenu, section } of filterPluginSidebarNavEntries( pluginSidebarNavStore.items, @@ -474,15 +491,15 @@ onMounted(async () => {