vue-stack-tabs 0.1.51 → 1.0.0

package/src/lib/components/TabHeader/index.vue

@@ -2,30 +2,30 @@
   <div class="stack-tab__header">
     <slot name="leftButton" />
     <tab-header-scroll
-      ref="scroll"
+      ref="scrollContainerRef"
       :space="space"
       :is-scroll-wheel="isScrollWheel"
       :is-scroll-button="isScrollButton"
     >
       <template #default>
         <transition-group
-          key="tabItemTrans"
+          key="tab-list-transition"
           tag="ul"
           class="stack-tab__nav"
-          v-bind="tabTrans"
+          v-bind="tabTransitionProps"
           appear
         >
           <tab-header-item
             v-for="(item, index) in tabs"
             :key="item.id"
             :contextmenu="contextmenu"
-            :item="item"
+            :item="item as ITabItem"
             @contextmenu.prevent="
-              (e: MouseEvent) => showContextMenu(e, item as ITabItem, index, tabs.length)
+              (e: MouseEvent) => showContextMenu(e, item as unknown as ITabItem, index, tabs.length)
             "
-            @click.middle.prevent="closeTab(item as ITabItem)"
-            @close="closeTab"
-            @active="activeTab"
+            @click.middle.prevent="handleCloseTab(item as ITabItem)"
+            @close="handleCloseTab"
+            @active="handleActivateTab"
           />
         </transition-group>
       </template>
@@ -39,43 +39,52 @@
     <transition name="stack-tab-zoom" appear>
       <context-menu
         v-if="contextMenuShown"
-        key="tabMenuTrans"
+        key="context-menu-transition"
         :left="contextMenuData.left"
         :top="contextMenuData.top"
         :tab-item="contextMenuData.item as ITabItem"
         :max="contextMenuData.max"
         :index="contextMenuData.index"
+        @close="handleCloseContextMenu"
       />
     </transition>
   </div>
 </template>
 
+<!--
+  TabHeader - 标签栏头部组件
+
+  职责：展示标签列表、左右滚动、最大化按钮、右键菜单
+  依赖：useTabActions(tabs/closeTab/activeTab)、useContextMenu
+-->
 <script lang="ts" setup>
-// @ts-nocheck
 import { inject, computed, ref, nextTick } from 'vue'
-import type { TransitionProps, Ref } from 'vue'
+import type { TransitionProps } from 'vue'
 import { TabScrollMode } from '../../model/TabModel'
 import type { ITabItem } from '../../model/TabModel'
 import ContextMenu from '../ContextMenu/index.vue'
 import useContextMenu from '../../hooks/useContextMenu'
-import useTabpanel from '../../hooks/useTabpanel'
+import useTabActions from '../../hooks/useTabActions'
 import TabHeaderItem from './TabHeaderItem.vue'
 import TabHeaderScroll from './TabHeaderScroll.vue'
 import TabHeaderButton from './TabHeaderButton.vue'
 import { useI18n } from 'vue-i18n-lite'
-// @ts-ignore
 const { t } = useI18n()
+/** 是否最大化，由上层 provide */
 const maximum = inject<boolean>('maximum')
 const emit = defineEmits(['active'])
-const scroll = ref()
+/** 滚动容器 ref，用于调用 scrollIntoView / isInView */
+const scrollContainerRef = ref<InstanceType<typeof TabHeaderScroll>>()
 const { shown: contextMenuShown, contextMenuData, showContextMenu } = useContextMenu()
+/** 关闭右键菜单 */
+const handleCloseContextMenu = () => {
+  contextMenuShown.value = false
+}
 
 const props = withDefaults(
   defineProps<{
     space: number
-    // tab的滚动方式
     tabScrollMode?: TabScrollMode
-    // tab动画
     tabTransition?: string | TransitionProps
     contextmenu?: boolean | object
     max?: number
@@ -91,46 +100,42 @@ const props = withDefaults(
     max: 20
   }
 )
-const { removeTab, active, tabs } = useTabpanel()
+const { closeTab, activeTab, tabs } = useTabActions()
 
-// 转换tab动画
-const tabTrans = computed<TransitionProps>(() => {
-  if (typeof props.tabTransition === 'string') {
-    return {
-      name: props.tabTransition
-    } as TransitionProps
-  }
-  return props.tabTransition as TransitionProps
-})
-// 判断是否有滚动按钮
+/** 标签列表 transition 的 props，支持 string 或对象 */
+const tabTransitionProps = computed<TransitionProps>(() =>
+  typeof props.tabTransition === 'string'
+    ? ({ name: props.tabTransition } as TransitionProps)
+    : (props.tabTransition as TransitionProps)
+)
+
+/** 是否显示左右滚动按钮 */
 const isScrollButton = computed<boolean>(() => {
   return props.tabScrollMode === TabScrollMode.BOTH || props.tabScrollMode === TabScrollMode.BUTTON
 })
-// 判断是否可以使用滚轮
+/** 是否支持滚轮滚动 */
 const isScrollWheel =
   props.tabScrollMode === TabScrollMode.BOTH || props.tabScrollMode === TabScrollMode.WHEEL
 
-// 关闭前，先判断是不最先中状态
-const closeTab = (item: ITabItem) => {
-  // emit('close', item)
+/** 关闭指定标签，并关闭右键菜单 */
+const handleCloseTab = (item: ITabItem) => {
   if (item.closable) {
-    const activeId = removeTab(item.id)
-    // emit('active', activeId)
+    closeTab(item.id)
   }
   contextMenuShown.value = false
 }
 
-const activeTab = (item: ITabItem, curActiveTab: Ref<HTMLElement>, isRoute: boolean) => {
-  if (scroll.value) {
+/** 激活指定标签，滚动到可视区域，并触发路由跳转 */
+const handleActivateTab = (item: ITabItem, clickedTabElement: HTMLElement | undefined, isRoute: boolean) => {
+  if (scrollContainerRef.value && clickedTabElement) {
     nextTick(() => {
-      if (!scroll.value!.isInView(curActiveTab.value)) {
-        scroll.value!.scrollIntoView(curActiveTab.value)
+      if (!scrollContainerRef.value!.isInView(clickedTabElement)) {
+        scrollContainerRef.value!.scrollIntoView(clickedTabElement)
       }
     })
-
-    active(item.id, isRoute)
-    emit('active', item.id)
   }
+  activeTab(item.id, isRoute)
+  emit('active', item.id)
 }
 </script>
 

package/src/lib/hooks/tabPanel/evict.spec.ts

@@ -0,0 +1,85 @@
+import { describe, it, expect, beforeEach } from 'vitest'
+import {
+  markCacheForEviction,
+  markTabPagesForEviction,
+  markTabPagesForEvictionOnly,
+  addCache,
+  removeCache,
+  evictPageCache,
+  evictMarkedCaches
+} from './evict'
+import { caches, cacheIdsToEvict, tabIdsToEvict, components } from './state'
+import { Stack } from '../../model/TabModel'
+import type { ITabPage } from '../../model/TabModel'
+
+function resetState() {
+  caches.value = []
+  cacheIdsToEvict.clear()
+  tabIdsToEvict.clear()
+  components.clear()
+}
+
+beforeEach(resetState)
+
+describe('evict', () => {
+  it('addCache 添加缓存 id', () => {
+    addCache('c1')
+    expect(caches.value).toContain('c1')
+    addCache('c1')
+    expect(caches.value.filter((x) => x === 'c1')).toHaveLength(1)
+  })
+
+  it('removeCache 移除指定 id', () => {
+    addCache('c1')
+    removeCache('c1')
+    expect(caches.value).not.toContain('c1')
+  })
+
+  it('markCacheForEviction 标记待驱逐', () => {
+    markCacheForEviction('c1')
+    expect(cacheIdsToEvict.has('c1')).toBe(true)
+  })
+
+  it('markTabPagesForEviction 标记标签下所有页面并加入 tabIdsToEvict', () => {
+    const page: ITabPage = { id: 'p1', tabId: 't1', path: '/x' }
+    const stack = new Stack<ITabPage>()
+    stack.push(page)
+    const tab = { id: 't1', pages: { list: () => stack.list() } }
+    markTabPagesForEviction(tab)
+    expect(cacheIdsToEvict.has('p1')).toBe(true)
+    expect(tabIdsToEvict.has('t1')).toBe(true)
+  })
+
+  it('markTabPagesForEvictionOnly 只标记页面不标记 tab', () => {
+    const page: ITabPage = { id: 'p1', tabId: 't1', path: '/x' }
+    const stack = new Stack<ITabPage>()
+    stack.push(page)
+    const tab = { pages: { list: () => stack.list() } }
+    markTabPagesForEvictionOnly(tab)
+    expect(cacheIdsToEvict.has('p1')).toBe(true)
+    expect(tabIdsToEvict.size).toBe(0)
+  })
+
+  it('evictPageCache 立即驱逐单个缓存', () => {
+    addCache('c1')
+    components.set('c1', {} as never)
+    evictPageCache('c1')
+    expect(caches.value).not.toContain('c1')
+    expect(components.has('c1')).toBe(false)
+    expect(cacheIdsToEvict.has('c1')).toBe(false)
+  })
+
+  it('evictMarkedCaches 执行所有待驱逐', () => {
+    addCache('c1')
+    addCache('c2')
+    components.set('c1', {} as never)
+    components.set('c2', {} as never)
+    markCacheForEviction('c1')
+    markCacheForEviction('c2')
+    evictMarkedCaches()
+    expect(caches.value).not.toContain('c1')
+    expect(caches.value).not.toContain('c2')
+    expect(components.size).toBe(0)
+    expect(cacheIdsToEvict.size).toBe(0)
+  })
+})

package/src/lib/hooks/tabPanel/evict.ts

@@ -0,0 +1,57 @@
+/**
+ * tabPanel/evict - 缓存驱逐逻辑
+ *
+ * 职责：标记待驱逐缓存、执行驱逐、维护 caches/components
+ */
+import type { ITabPage } from '../../model/TabModel'
+import {
+  caches,
+  components,
+  cacheIdsToEvict,
+  tabIdsToEvict
+} from './state'
+
+/** 标记缓存为待驱逐 */
+export const markCacheForEviction = (cacheName: string) => {
+  cacheIdsToEvict.add(cacheName)
+}
+
+/** 标记标签下所有页面为可驱逐，并标记该标签（关闭场景） */
+export const markTabPagesForEviction = (tab: { id: string; pages: { list(): ITabPage[] } }) => {
+  for (const page of tab.pages.list()) markCacheForEviction(page.id)
+  tabIdsToEvict.add(tab.id)
+}
+
+/** 仅标记标签下所有页面为可驱逐（续签场景） */
+export const markTabPagesForEvictionOnly = (tab: { pages: { list(): ITabPage[] } }) => {
+  for (const page of tab.pages.list()) markCacheForEviction(page.id)
+}
+
+/** 将缓存 id 加入 caches */
+export const addCache = (cacheName: string) => {
+  if (!caches.value.includes(cacheName)) caches.value.push(cacheName)
+}
+
+/** 从 caches 中移除指定 id */
+export const removeCache = (cacheName: string) => {
+  const i = caches.value.indexOf(cacheName)
+  if (i >= 0) caches.value.splice(i, 1)
+}
+
+/** 立即驱逐单个页面缓存 */
+export const evictPageCache = (cacheName: string) => {
+  if (!cacheName) return
+  cacheIdsToEvict.delete(cacheName)
+  removeCache(cacheName)
+  components.delete(cacheName)
+}
+
+/** 执行所有待驱逐缓存的驱逐 */
+export const evictMarkedCaches = () => {
+  if (cacheIdsToEvict.size > 0) {
+    for (const cacheName of [...cacheIdsToEvict]) {
+      evictPageCache(cacheName)
+    }
+    cacheIdsToEvict.clear()
+  }
+}

package/src/lib/hooks/tabPanel/scroll.ts

@@ -0,0 +1,52 @@
+/**
+ * tabPanel/scroll - 滚动位置保存与恢复
+ *
+ * 职责：在切出/切入页面时保存和恢复滚动位置
+ */
+import { scrollPositionsByPageId } from './state'
+
+/** 恢复指定页面的滚动位置 */
+export const restoreScroller = (pageCacheId: string) => {
+  const positions = scrollPositionsByPageId.get(pageCacheId)
+  if (!positions) return
+  for (const [sel, pos] of positions) {
+    const el = document.querySelector(sel) as HTMLElement | null
+    if (el) {
+      el.scrollTop = pos.top
+      el.scrollLeft = pos.left
+    }
+  }
+}
+
+/** 保存指定页面的滚动位置 */
+export const saveScroller = (pageCacheId: string) => {
+  const positions = scrollPositionsByPageId.get(pageCacheId)
+  if (!positions) return
+  for (const sel of positions.keys()) {
+    const el = document.querySelector(sel) as HTMLElement | null
+    positions.set(sel, {
+      top: el?.scrollTop ?? 0,
+      left: el?.scrollLeft ?? 0
+    })
+  }
+}
+
+/** 移除指定页面的滚动记录 */
+export const removeScroller = (pageCacheId: string) => {
+  const positions = scrollPositionsByPageId.get(pageCacheId)
+  if (positions) {
+    positions.clear()
+    scrollPositionsByPageId.delete(pageCacheId)
+  }
+}
+
+/** 为页面注册需要记录滚动位置的选择器 */
+export const addPageScroller = (pageCacheId: string, ...selectorIds: string[]) => {
+  if (!scrollPositionsByPageId.has(pageCacheId)) {
+    scrollPositionsByPageId.set(pageCacheId, new Map<string, { top: number; left: number }>())
+  }
+  const positions = scrollPositionsByPageId.get(pageCacheId)!
+  for (const sel of selectorIds) {
+    positions.set(sel, { top: 0, left: 0 })
+  }
+}

package/src/lib/hooks/tabPanel/session.ts

@@ -0,0 +1,33 @@
+/**
+ * tabPanel/session - Session 持久化
+ *
+ * 职责：将当前激活标签保存到 sessionStorage，刷新后恢复
+ */
+import type { ITabItem } from '../../model/TabModel'
+import { Stack } from '../../model/TabModel'
+import type { ITabPage } from '../../model/TabModel'
+import { SESSION_TAB_NAME, sessionPrefix } from './state'
+
+/** 获取 sessionStorage 的 key */
+export const getSessionKey = () => sessionPrefix + SESSION_TAB_NAME
+
+/** 将当前激活的标签保存到 sessionStorage */
+export const saveActiveTabToSession = (tab: ITabItem) => {
+  if (!tab.id) return
+  window.sessionStorage.setItem(getSessionKey(), JSON.stringify(tab))
+}
+
+/** 清除 sessionStorage 中的激活标签 */
+export const clearSession = () => {
+  window.sessionStorage.removeItem(getSessionKey())
+}
+
+/** 从 sessionStorage 解析恢复的标签（含 Stack 反序列化） */
+export const restoreTabFromSession = (
+  storedJson: string | null
+): ITabItem | null => {
+  if (storedJson == null) return null
+  return JSON.parse(storedJson, (k, v) =>
+    k === 'pages' ? new Stack<ITabPage>(v) : v
+  ) as ITabItem
+}

package/src/lib/hooks/tabPanel/state.ts

@@ -0,0 +1,52 @@
+/**
+ * tabPanel/state - 标签页核心共享状态
+ *
+ * 职责：集中管理 tabs、caches、components、驱逐集合、滚动位置等
+ * 被 useTabPanel、evict、scroll、session 导入使用
+ */
+import type { ITabItem } from '../../model/TabModel'
+import { ref } from 'vue'
+
+/** 当前打开的标签列表（含每个标签的页面栈） */
+export const tabs = ref<ITabItem[]>([])
+/** 初始化时传入的默认标签（用于对比 session 恢复） */
+export const defaultTabs: ITabItem[] = []
+/** keep-alive include 数组，与 Vue 的 keep-alive :include 绑定 */
+export const caches = ref<string[]>([])
+/** 页面缓存 ID -> 包装后的 DefineComponent */
+export const components = new Map<string, import('vue').DefineComponent>()
+/** 待驱逐的页面缓存 ID 集合 */
+export const cacheIdsToEvict = new Set<string>()
+/** 待驱逐的标签 ID 集合 */
+export const tabIdsToEvict = new Set<string>()
+/** 刷新计数器，变更时触发 component :key 变化 */
+export const refreshKey = ref<number>(0)
+/** 刷新时临时加入 keep-alive exclude 的缓存 ID */
+export const excludedCacheIdsForRefresh = ref<string[]>([])
+/** pageCacheId -> Map<selector, { top, left }> 滚动位置存储 */
+export const scrollPositionsByPageId = new Map<string, Map<string, { top: number; left: number }>>()
+/** 是否已完成初始化 */
+export const isInitialized = ref<boolean>(false)
+
+/** sessionStorage 中存储当前激活标签的 key 前缀 */
+export const SESSION_TAB_NAME = 'stacktab-active-tab'
+
+/** iframe 标签 tabId -> 刷新序号，变更时触发 iframe 重载 */
+export const iframeRefreshKeys = ref<Record<string, number>>({})
+
+/** 最大标签数量，0 表示不限制 */
+export let maxTabCount = 0
+/** 是否使用页面级滚动 */
+export let useGlobalScroll = false
+/** sessionStorage key 前缀 */
+export let sessionPrefix = ''
+
+export const setMaxTabCount = (n: number) => {
+  maxTabCount = n
+}
+export const setUseGlobalScroll = (v: boolean) => {
+  useGlobalScroll = v
+}
+export const setSessionPrefix = (p: string) => {
+  sessionPrefix = p
+}

package/src/lib/hooks/useContextMenu.ts

@@ -1,6 +1,14 @@
-import { onUnmounted, onMounted, ref, reactive, nextTick } from 'vue'
+import { onUnmounted, ref, reactive, nextTick } from 'vue'
 import type { ITabItem } from '../model/TabModel'
+
+/**
+ * useContextMenu - 标签右键菜单 Hook
+ *
+ * 职责：管理右键菜单的显示/隐藏、定位，点击菜单外区域关闭
+ * 使用：TabHeader 中右键标签时调用 showContextMenu
+ */
 export default () => {
+  /** 菜单展示所需数据：当前标签、索引、坐标、最大数量 */
   const contextMenuData = reactive({
     item: {},
     index: -1,
@@ -8,38 +16,32 @@ export default () => {
     top: 0,
     max: 0
   })
+  /** 菜单是否显示 */
   const shown = ref<boolean>(false)
 
-  onMounted(() => {
-    document.addEventListener('click', clickOutSide)
-  })
+  /** 点击菜单外部时关闭菜单并移除监听 */
+  const handleClickOutside = (ev: MouseEvent) => {
+    const target = ev.target as Element
+    if (target.closest?.('.stack-tab__contextmenu')) return
+    shown.value = false
+    document.removeEventListener('click', handleClickOutside)
+  }
+
   onUnmounted(() => {
-    document.removeEventListener('click', clickOutSide)
+    document.removeEventListener('click', handleClickOutside)
   })
 
+  /** 显示右键菜单；nextTick 后设置位置与数据，避免与关闭逻辑冲突 */
   const showContextMenu = async (e: MouseEvent, item: ITabItem, index: number, max: number) => {
-    // 关闭已打开的菜单
     shown.value = false
+    document.removeEventListener('click', handleClickOutside)
 
     await nextTick(() => {
       const { clientY: top, clientX: left } = e
       shown.value = true
       Object.assign(contextMenuData, { item, index, top, left, max })
-
-      console.log('showContextMenu in callback')
+      nextTick(() => document.addEventListener('click', handleClickOutside))
     })
-
-    // .then(() => {
-
-    // })
-  }
-
-  const clickOutSide = (ev: MouseEvent) => {
-    const classList = (ev.target as Element).classList
-    if (classList.contains('stack-tab__contextmenu')) {
-      return
-    }
-    shown.value = false
   }
 
   return {

package/src/lib/hooks/useTabActions.ts

@@ -0,0 +1,148 @@
+import { useRouter } from 'vue-router'
+import { throttle } from 'throttle-debounce'
+import { defu } from 'defu'
+import { ulid } from 'ulid'
+
+import useTabPanel from './useTabPanel'
+import { encodeTabInfo } from '../utils/tabInfoEncoder'
+import { parseUrl, isCrossOriginUrl } from '../utils/urlParser'
+import type { ITabData, IframeRefreshMode } from '../model/TabModel'
+import { TabEventType, useTabEmitter } from './useTabEventBus'
+
+/** iframe 占位路由的 path，由 StackTabs 通过 setIFramePath 注入 */
+let iframePath: string
+
+/**
+ * useTabActions - 标签操作对外 Hook
+ *
+ * 职责：提供打开、关闭、刷新标签等用户级 API，内部委托 useTabPanel 执行
+ * 使用范围：业务代码、ContextMenu、TabHeader 等
+ *
+ * 主要 API：
+ * - openTab(tab, renew?) 打开或续签标签
+ * - closeTab(id) / closeAllTabs() 关闭标签
+ * - refreshTab(id) / refreshAllTabs() 刷新
+ * - activeTab(id, isRoute?) 激活标签
+ * - reset() 重置（关闭所有）
+ */
+export default function useTabActions() {
+  const router = useRouter()
+  const emitter = useTabEmitter()
+  const {
+    active,
+    hasTab,
+    refreshKey,
+    reset,
+    canAddTab,
+    renewTab,
+    getTab,
+    tabs,
+    removeTab,
+    removeAllTabs,
+    refreshTab,
+    refreshAllTabs
+  } = useTabPanel()
+
+  /** 合并默认值，生成完整 tabInfo */
+  const prepareTabInfo = (tab: ITabData): ITabData => {
+    const defaults: Partial<ITabData> = {
+      refreshable: true,
+      closable: true,
+      iframe: false
+    }
+    if (tab.iframe && tab.iframeRefreshMode === undefined) {
+      defaults.iframeRefreshMode = isCrossOriginUrl(tab.path ?? '')
+        ? ('reload' as IframeRefreshMode)
+        : ('postMessage' as IframeRefreshMode)
+    } else if (tab.iframe) {
+      defaults.iframeRefreshMode = (tab.iframeRefreshMode ?? 'postMessage') as IframeRefreshMode
+    }
+    const info = defu(tab, defaults)
+    if (!info.id) info.id = ulid()
+    return info
+  }
+
+  /** 打开新标签；renew=true 时若已存在则清空该标签的页面栈后重新打开；500ms 节流 */
+  const openTab = throttle(500, (tab: ITabData, renew = false) => {
+    return new Promise<string | undefined>((resolve, reject) => {
+      const tabInfo = prepareTabInfo(tab)
+
+      if (hasTab(tabInfo.id!) && !renew) {
+        emitter.emit(TabEventType.TAB_ACTIVE, { id: tabInfo.id! })
+        resolve(tabInfo.id)
+        return
+      }
+
+      if (tabInfo.id && renew && hasTab(tabInfo.id)) {
+        renewTab(tab)
+        const currentTab = getTab(tab.id!)
+        if (currentTab?.active) refreshKey.value++
+      }
+
+      if (!canAddTab()) {
+        reject(new Error('Max Size'))
+        return
+      }
+
+      navigateToTab(tab, tabInfo)
+      resolve(tabInfo.id)
+    })
+  })
+
+  /** 执行路由跳转到标签对应页面（普通路由或 iframe 占位路由） */
+  const navigateToTab = (tab: ITabData, tabInfo: ITabData) => {
+    const __tab = encodeTabInfo(tabInfo)
+    let query = defu({ __tab }, tab.query) as Record<string, string>
+    let path: string
+    if (!tab.iframe) {
+      const url = parseUrl(tab.path)
+      path = url.path
+      query = defu(url.query, query)
+    } else {
+      query['__src'] = encodeURIComponent(tab.path as string)
+      path = iframePath
+    }
+    router.push({ path, query })
+  }
+
+  /** 设置 iframe 占位路由的 path，由 StackTabs 在挂载时调用 */
+  const setIFramePath = (path: string) => {
+    iframePath = path
+  }
+
+  /** 获取当前页面的缓存容器 DOM（用于某些需要直接操作 DOM 的场景） */
+  const getWrapper = () => {
+    return document.getElementsByClassName('cache-page-wrapper')[0]
+  }
+
+  /** iframe 标签在新窗口打开（无法嵌入时降级） */
+  const openInNewWindow = (id: string) => {
+    const tab = getTab(id)
+    if (tab?.iframe && tab.url) {
+      window.open(tab.url, '_blank', 'noopener,noreferrer')
+    }
+  }
+
+  return {
+    // 打开
+    openTab,
+
+    // 关闭
+    closeTab: removeTab,
+    closeAllTabs: removeAllTabs,
+
+    // 刷新
+    refreshTab,
+    refreshAllTabs,
+
+    // 激活与重置
+    activeTab: active,
+    reset,
+
+    // 数据与配置
+    tabs,
+    setIFramePath,
+    getWrapper,
+    openInNewWindow
+  }
+}