ruoyi-plus-uniapp

主题

标签视图(TagsView)系统 ​

简介 ​

标签视图系统是现代后台管理界面的重要组件，提供多标签页的管理和导航功能。该系统由 TagsView.vue（标签管理）和 ScrollPane.vue（滚动容器）两个核心组件构成，支持标签页的增删改查、右键菜单操作、自动滚动定位、深色模式适配等功能。

组件架构 ​

TagsView/
├── TagsView.vue        # 标签页管理主组件
└── ScrollPane.vue      # 水平滚动容器组件

核心组件详解 ​

TagsView.vue - 标签页管理 ​

标签页管理的核心组件，负责标签的显示、交互和生命周期管理。

组件结构 ​

vue
<template>
  <div id="tags-view-container" class="tags-view-container" ref="containerRef">
    <!-- 标签页滚动容器 -->
    <ScrollPane ref="scrollPaneRef" class="tags-view-wrapper" @scroll="handleScroll">
      <!-- 遍历所有访问过的视图标签 -->
      <router-link
        v-for="tag in visitedViews"
        :key="tag.path"
        :data-path="tag.path"
        :class="['tags-view-item', { 'active': isActive(tag) }]"
        :to="{ path: tag.path ? tag.path : '', query: tag.query }"
        @click.middle="!isAffix(tag) ? closeSelectedTag(tag) : ''"
        @contextmenu.prevent="openMenu(tag, $event)"
      >
        <!-- 标签图标 -->
        <div class="tag-icon">
          <Icon :code="tag.meta?.icon || 'nested'" />
        </div>

        <!-- 标签文本内容 -->
        <div class="tag-text">
          {{ getTagTitle(tag) }}
        </div>

        <!-- 关闭按钮 - 仅非固定标签显示 -->
        <span v-if="!isAffix(tag)" class="close-btn" @click.prevent.stop="closeSelectedTag(tag)">
          <svg class="close-icon" viewBox="0 0 24 24" fill="currentColor">
            <path d="M19 6.41L17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12z" />
          </svg>
        </span>
      </router-link>
    </ScrollPane>

    <!-- 右键上下文菜单 -->
    <ul v-show="visible" :style="{ left: left + 'px', top: top + 'px' }" class="contextmenu">
      <!-- 各种菜单项 -->
    </ul>
  </div>
</template>

核心功能实现 ​

标签状态管理

typescript
// 访问过的视图列表
const visitedViews = computed(() => useTagsViewStore().getVisitedViews())

// 检查标签是否为当前激活状态
const isActive = (r: RouteLocationNormalized): boolean => {
  return r.path === route.path
}

// 检查标签是否为固定标签（不可关闭）
const isAffix = (tag: RouteLocationNormalized) => {
  return tag?.meta && tag?.meta?.affix
}

国际化标题处理

typescript
const getTagTitle = (tag: RouteLocationNormalized) => {
  const meta = tag?.meta
  const name = tag?.name

  // 优先使用国际化键进行翻译
  if (meta?.i18nKey) {
    const i18nTitle = t(meta.i18nKey)
    // 如果翻译成功（返回值不等于键名），使用翻译结果
    if (i18nTitle !== meta.i18nKey) {
      return i18nTitle
    }
  }

  // 处理包含动态参数的标题模板
  if (meta?.title?.includes('{')) {
    try {
      return t(meta.title, meta.titleParams || {})
    } catch {
      // 解析失败时返回原始标题
      return meta.title
    }
  }

  // 降级处理：使用名称转换的标题或者原始标题
  return t(nameToTitle(name.toString()), meta?.title)
}

固定标签初始化

typescript
const filterAffixTags = (routes: RouteRecordRaw[], basePath = '') => {
  let tags: RouteLocationNormalized[] = []

  routes.forEach((route) => {
    // 检查当前路由是否为固定标签
    if (route.meta && route.meta.affix) {
      const tagPath = normalizePath(basePath + '/' + route.path)
      tags.push({
        fullPath: tagPath,
        path: tagPath,
        name: route.name as string,
        meta: { ...route.meta }
      })
    }

    // 递归处理子路由
    if (route.children) {
      const tempTags = filterAffixTags(route.children, route.path)
      if (tempTags.length >= 1) {
        tags = [...tags, ...tempTags]
      }
    }
  })

  return tags
}

标签操作方法

typescript
// 添加当前路由为新标签
const addTags = () => {
  const { name } = route

  // 如果查询参数中包含标题，更新路由元信息
  if (route.query.title) {
    route.meta.title = route.query.title as string
  }

  // 有效路由名称时添加到视图存储
  if (name) {
    useTagsViewStore().addView(route as any)
  }
}

// 滚动到当前激活的标签位置
const moveToCurrentTag = async () => {
  await nextTick()
  for (const r of visitedViews.value) {
    if (r.path === route.path) {
      // 滚动到目标标签
      scrollPaneRef.value?.moveToTarget(r)
      // 如果完整路径不同则更新视图信息
      if (r.fullPath !== route.fullPath) {
        useTagsViewStore().updateVisitedView(route)
      }
    }
  }
}

右键菜单系统 ​

菜单显示控制

typescript
const openMenu = (tag: RouteLocationNormalized, e: MouseEvent) => {
  const menuMinWidth = 105 // 菜单最小宽度
  const container = containerRef.value
  if (!container) return

  // 计算菜单位置
  const offsetLeft = container.getBoundingClientRect().left
  const offsetWidth = container.offsetWidth
  const maxLeft = offsetWidth - menuMinWidth
  const l = e.clientX - offsetLeft + 15

  left.value = l > maxLeft ? maxLeft : l
  top.value = e.clientY
  visible.value = true
  selectedTag.value = tag
}

菜单操作实现

typescript
// 关闭指定标签页
const closeSelectedTag = (view: RouteLocationNormalized) => {
  closePage(view).then(({ visitedViews }: any) => {
    if (isActive(view)) {
      toLastView(visitedViews, view)
    }
  })
}

// 关闭其他标签页
const closeOthersTags = () => {
  if (selectedTag.value) {
    router.push({
      path: selectedTag.value.path,
      query: selectedTag.value.query
    }).catch(() => {})
  }

  closeOtherPage(selectedTag.value).then(() => {
    moveToCurrentTag()
  })
}

ScrollPane.vue - 滚动容器 ​

提供标签页的水平滚动功能，支持鼠标滚轮操作和自动定位。

vue
<template>
  <el-scrollbar ref="scrollContainerRef" :vertical="false" class="scroll-container" @wheel.prevent="handleMouseWheel">
    <slot />
  </el-scrollbar>
</template>

核心功能实现 ​

鼠标滚轮处理

typescript
const handleMouseWheel = (e: WheelEvent): void => {
  // 获取滚轮的滚动量，兼容不同浏览器
  const eventDelta = (e as any).wheelDelta || -e.deltaY * 40
  const wrapper = scrollWrapper.value

  if (wrapper) {
    // deltaY < 0 (往上滚动) → eventDelta > 0 → scrollLeft 减少 → 向左移动
    // deltaY > 0 (往下滚动) → eventDelta < 0 → scrollLeft 增加 → 向右移动
    wrapper.scrollLeft = wrapper.scrollLeft - eventDelta / 4
  }
}

自动滚动定位

typescript
const moveToTarget = (currentTag: RouteLocationNormalized): void => {
  // 获取容器和包装器元素
  const container = scrollContainerRef.value?.$el as HTMLElement
  const wrapper = scrollWrapper.value

  // 基础验证
  if (!container || !wrapper) {
    console.warn('ScrollPane: 容器或包装器元素未找到')
    return
  }

  const containerWidth = container.offsetWidth
  const views = visitedViews.value

  // 处理空数组情况
  if (views.length === 0) {
    console.warn('ScrollPane: 没有可访问的视图')
    return
  }

  const firstTag = views[0]
  const lastTag = views[views.length - 1]

  // 处理边界情况：第一个标签
  if (firstTag === currentTag) {
    wrapper.scrollLeft = 0
    return
  }

  // 处理边界情况：最后一个标签
  if (lastTag === currentTag) {
    wrapper.scrollLeft = wrapper.scrollWidth - containerWidth
    return
  }

  // 计算最佳滚动位置
  const currentIndex = views.findIndex((item) => item === currentTag)
  if (currentIndex !== -1) {
    calculateOptimalScrollPosition(wrapper, containerWidth, currentIndex)
  }
}

状态管理集成 ​

TagsViewStore 集成 ​

typescript
// 标签视图存储的主要方法
const tagsViewStore = useTagsViewStore()

// 访问的视图列表
const visitedViews = computed(() => tagsViewStore.getVisitedViews())

// 标签操作方法
tagsViewStore.addView(route)           // 添加视图
tagsViewStore.updateVisitedView(route) // 更新视图
tagsViewStore.delView(view)           // 删除视图
tagsViewStore.delOthersViews(view)    // 删除其他视图
tagsViewStore.delAllViews()           // 删除所有视图

路由集成 ​

typescript
// 路由变化监听
watch(route, () => {
  addTags()        // 添加新标签
  moveToCurrentTag() // 移动到当前标签
})

// 组件挂载时的初始化操作
onMounted(() => {
  initTags() // 初始化固定标签
  addTags()  // 添加当前路由标签
})

功能特性 ​

多标签管理 ​

  • 自动添加：路由变化时自动添加新标签
  • 智能去重：相同路径标签自动合并
  • 状态保持：标签状态持久化存储
  • 批量操作：支持关闭其他、左侧、右侧、全部标签

右键菜单 ​

  • 丰富操作：刷新、关闭、批量关闭等操作
  • 智能显示：根据标签位置和类型显示不同菜单项
  • 边界处理：菜单位置自动调整防止超出边界
  • 权限控制：固定标签不显示关闭选项

滚动支持 ​

  • 鼠标滚轮：支持水平滚动操作
  • 自动定位：新标签自动滚动到可视区域
  • 智能计算：最佳滚动位置算法
  • 边界处理：首尾标签的特殊处理

国际化支持 ​

  • 动态标题：支持多语言标签标题
  • 参数模板：支持动态参数的标题模板
  • 降级处理：国际化失败时的兜底方案

最佳实践 ​

推荐做法 ​

  1. 合理设置固定标签

    typescript
    // 重要页面设为固定标签
{
  meta: { 
    affix: true,
    title: '首页'
  }
}

  2. 标签标题国际化

    typescript
    {
  meta: {
    title: 'User Management',
    i18nKey: 'menu.user.management'
  }
}

  3. 合理的标签数量限制

    typescript
    // 限制最大标签数量
const MAX_TAGS = 10

避免做法 ​

  1. 过多的固定标签

    typescript
    // ❌ 避免设置过多固定标签
{ meta: { affix: true } } // 只对重要页面使用

  2. 忽略滚动性能

    typescript
    // ❌ 直接操作scrollLeft
wrapper.scrollLeft = newPosition

// ✅ 使用平滑滚动
wrapper.scrollTo({ left: newPosition, behavior: 'smooth' })

故障排除 ​

常见问题 ​

  1. 标签不显示

    • 检查路由配置中的 name 属性
    • 确认 hidden: true 设置
    • 验证标签视图开关状态

  2. 滚动不工作

    • 检查容器宽度设置
    • 确认滚动条隐藏样式
    • 验证事件监听器绑定

  3. 右键菜单位置错误

    • 检查容器边界计算
    • 确认菜单尺寸配置
    • 验证定位算法

总结 ​

标签视图系统通过 TagsView 和 ScrollPane 两个组件的协作，为用户提供了功能完整、体验流畅的多标签页管理方案。系统支持丰富的交互功能、智能的滚动定位、完善的右键菜单等特性，是现代化后台管理系统的重要组成部分。