vue-stack-tabs 1.3.0 → 1.4.1

package/src/lib/hooks/stackTabsContext.ts

@@ -1,8 +1,9 @@
 /**
  * VueStackTabs 全局运行时上下文管理。
  *
- * 负责创建、注册、解析全局唯一的 StackTabsRuntimeContext，
- * 支持通过 Vue provide/inject 或模块级单例两种方式访问。
+ * 负责创建、注册、解析 StackTabsRuntimeContext。
+ * 业务运行时通过 Vue provide/inject 隔离；模块级回退仅保留给没有 App
+ * 容器的兼容调用（例如旧的单元测试），绝不能承载某个 Vue App 的状态。
  * 每个 Vue app 只允许注册一个 <VueStackTabs> 实例。
  */
 import type { App, DefineComponent, InjectionKey, Ref, ShallowRef } from 'vue'
@@ -77,7 +78,10 @@ export const createStackTabsRuntimeContext = (
   }
 }
 
-/** 获取当前活跃的运行时上下文（模块级单例） */
+/**
+ * 获取非 App 容器下注册的兼容上下文。
+ * @deprecated App 内的 composable 必须依赖 provide/inject，不应使用这个回退。
+ */
 export const getActiveStackTabsRuntimeContext = (): StackTabsRuntimeContext | null =>
   activeRuntimeContext
 
@@ -86,22 +90,21 @@ export const registerStackTabsRuntimeContext = (
   context: StackTabsRuntimeContext,
   options: RegisterStackTabsRuntimeContextOptions = {}
 ): boolean => {
-  if (!activeRuntimeContext) {
-    activeRuntimeContext = context
-  }
-
   if (options.app && !runtimeContextOwnersByApp.has(options.app)) {
     runtimeContextOwnersByApp.add(options.app)
     return true
   }
 
-  if (
-    !options.app &&
-    activeRuntimeContext === context &&
-    !isFallbackRuntimeContextOwnerRegistered
-  ) {
-    isFallbackRuntimeContextOwnerRegistered = true
-    return true
+  if (!options.app) {
+    if (!activeRuntimeContext) {
+      activeRuntimeContext = context
+      isFallbackRuntimeContextOwnerRegistered = true
+      return true
+    }
+    if (activeRuntimeContext === context && !isFallbackRuntimeContextOwnerRegistered) {
+      isFallbackRuntimeContextOwnerRegistered = true
+      return true
+    }
   }
 
   const isProduction = options.isProduction ?? import.meta.env.PROD
@@ -118,13 +121,15 @@ export const unregisterStackTabsRuntimeContext = (
   context: StackTabsRuntimeContext,
   options: UnregisterStackTabsRuntimeContextOptions = {}
 ): void => {
-  if (options.app) runtimeContextOwnersByApp.delete(options.app)
-  if (!options.app && activeRuntimeContext === context)
-    isFallbackRuntimeContextOwnerRegistered = false
+  if (options.app) {
+    runtimeContextOwnersByApp.delete(options.app)
+    return
+  }
+  if (activeRuntimeContext === context) isFallbackRuntimeContextOwnerRegistered = false
   if (activeRuntimeContext === context) activeRuntimeContext = null
 }
 
-/** 解析当前可用的运行时上下文，优先使用 inject，回退到模块单例 */
+/** 解析当前可用的运行时上下文，优先使用 inject，兼容回退仅限非 App 容器。 */
 export const resolveStackTabsRuntimeContext = (): StackTabsRuntimeContext => {
   const injected = hasInjectionContext() ? inject(stackTabsContextKey, null) : null
   const context = injected ?? activeRuntimeContext

package/src/lib/hooks/tabPanel/pageComponentFactory.tsx

@@ -0,0 +1,142 @@
+/**
+ * 页面缓存组件工厂。
+ *
+ * 将 keep-alive 包装、VNode 注入和页面激活生命周期从 tab 状态编排中隔离，
+ * 使 useTabPanel 只负责领域状态与路由协调。
+ */
+import {
+  cloneVNode,
+  defineComponent,
+  onActivated,
+  onDeactivated,
+  onMounted,
+  onUnmounted,
+  ref,
+  shallowRef
+} from 'vue'
+import type { DefineComponent, PropType, VNode } from 'vue'
+import type { ITabBase, ITabItem } from '../../model/TabModel'
+import PageLoading from '../../components/PageLoading.vue'
+import type { StackTabsRuntimeContext } from '../stackTabsContext'
+import { useScrollShadow } from '../useScrollShadow'
+
+interface PageComponentFactoryOptions {
+  runtimeContext: StackTabsRuntimeContext
+  getTab: (id: string) => ITabItem | null
+  addCache: (cacheName: string) => void
+  evictMarkedCaches: () => void
+  addPageScroller: (pageId: string, ...selectors: string[]) => void
+  saveScroller: (pageId: string) => void
+  restoreScroller: (pageId: string) => void
+  removeScroller: (pageId: string) => void
+}
+
+export const createPageComponentFactory = (options: PageComponentFactoryOptions) => {
+  const {
+    runtimeContext,
+    getTab,
+    addCache,
+    evictMarkedCaches,
+    addPageScroller,
+    saveScroller,
+    restoreScroller,
+    removeScroller
+  } = options
+  const { components, tabIdsToEvict } = runtimeContext
+
+  const resolvePageComponent = (ctx: { cacheName: string; tabInfo: ITabBase }): DefineComponent => {
+    const { cacheName, tabInfo } = ctx
+    const existing = components.get(cacheName)
+    if (existing) {
+      addCache(cacheName)
+      return existing
+    }
+
+    const cacheComponent = defineComponent<{ vnode?: VNode }>({
+      name: cacheName,
+      props: {
+        vnode: {
+          type: Object as PropType<VNode>,
+          required: false,
+          default: undefined
+        }
+      },
+      emits: ['onLoaded'],
+      setup(props, context) {
+        const localBackParams = ref<Record<string, unknown> | null>(null)
+        const lastVnode = shallowRef<VNode | null | undefined>(null)
+        const lastCloned = shallowRef<VNode | null>(null)
+        const lastBackParams = shallowRef<Record<string, unknown> | null>(null)
+        const pageRoot = ref<HTMLElement | null>(null)
+
+        const checkAndConsumeBackParams = () => {
+          try {
+            const tab = getTab(tabInfo.id!)
+            const top = tab?.pages.peek()
+            if (top && top.id === cacheName && top._backParams) {
+              localBackParams.value = { ...top._backParams }
+              delete top._backParams
+            } else {
+              localBackParams.value = null
+            }
+          } catch {
+            localBackParams.value = null
+          }
+        }
+
+        onMounted(() => {
+          context.emit('onLoaded')
+          addPageScroller(cacheName, `#W-${cacheName}`)
+          checkAndConsumeBackParams()
+        })
+        onDeactivated(() => saveScroller(cacheName))
+        onActivated(() => {
+          context.emit('onLoaded')
+          restoreScroller(cacheName)
+          evictMarkedCaches()
+          tabIdsToEvict.clear()
+          checkAndConsumeBackParams()
+        })
+        onUnmounted(() => removeScroller(cacheName))
+
+        // 给 .cache-page-wrapper 挂滚动阴影，确保 keep-alive 的 suspended/deactivated 生命周期下表现一致
+        useScrollShadow({ target: pageRoot })
+
+        return () => {
+          const vnode = props.vnode
+          const backParams = localBackParams.value
+          if (vnode !== lastVnode.value || backParams !== lastBackParams.value) {
+            lastCloned.value = vnode
+              ? cloneVNode(vnode, {
+                  tId: tabInfo.id,
+                  pId: cacheName,
+                  ...(backParams ? { _back: backParams } : {})
+                })
+              : null
+            lastVnode.value = vnode
+            lastBackParams.value = backParams
+          }
+          return (
+            <div
+              ref={pageRoot}
+              class="cache-page-wrapper"
+              id={`W-${cacheName}`}
+              style={[
+                runtimeContext.useGlobalScroll.value ? 'overflow:auto' : 'overflow:hidden',
+                'height: 100%'
+              ]}
+            >
+              {lastCloned.value}
+              <PageLoading tabId={tabInfo.id!} />
+            </div>
+          )
+        }
+      }
+    }) as DefineComponent
+    components.set(cacheName, cacheComponent)
+    addCache(cacheName)
+    return cacheComponent
+  }
+
+  return { resolvePageComponent }
+}

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

@@ -4,6 +4,7 @@
  * 活动普通页面保持 cache id 稳定，只递增页面级刷新版本；非活动页面可直接替换缓存。
  */
 import type { Ref } from 'vue'
+import { triggerRef } from 'vue'
 import type { ITabItem } from '../../model/TabModel'
 
 export interface TabPanelRefreshApi {
@@ -56,6 +57,8 @@ export const createTabPanelRefresh = (
 
     if (tab.active) {
       currentPage.refreshVersion = (currentPage.refreshVersion ?? 0) + 1
+      // 通知 activePageRefreshVersion 这类依赖 tabs.value 的计算属性重新计算
+      triggerRef(tabs)
       return
     }
 

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

@@ -2,6 +2,8 @@
  * tabPanel/scroll - 滚动位置保存与恢复
  *
  * 职责：基于当前 StackTabsRuntimeContext 在切出/切入页面时保存和恢复滚动位置。
+ * 优化：用 MutationObserver 缓存 [data-stack-tab-scroll] 元素列表，
+ *       避免每次 deactivate 都全量 querySelectorAll。
  */
 import type { StackTabsRuntimeContext } from '../stackTabsContext'
 
@@ -10,6 +12,8 @@ export interface TabPanelScrollApi {
   saveScroller: (pageCacheId: string) => void
   removeScroller: (pageCacheId: string) => void
   addPageScroller: (pageCacheId: string, ...selectorIds: string[]) => void
+  /** 主动失效某页面的滚动元素缓存，例如外部强制刷新缓存页时 */
+  invalidateAutoScrollCache: (pageCacheId: string) => void
 }
 
 const resolveScrollElement = (selector: string): HTMLElement | null =>
@@ -17,6 +21,73 @@ const resolveScrollElement = (selector: string): HTMLElement | null =>
     ? document.getElementById(selector.slice(1))
     : (document.querySelector(selector) as HTMLElement | null)
 
+const AUTO_SCROLLER_PREFIX = '__stack-tab-auto-scroll__:'
+
+interface AutoScrollCache {
+  elements: HTMLElement[]
+  observer: MutationObserver | null
+}
+
+/**
+ * 在 pageRoot 上挂一个 MutationObserver，自动维护 [data-stack-tab-scroll] 元素列表；
+ * 列表变化时无需上层主动失效，下次读到的就是最新值。
+ */
+const createAutoScrollCache = (pageRoot: HTMLElement): AutoScrollCache => {
+  const collect = (): HTMLElement[] =>
+    Array.from(pageRoot.querySelectorAll<HTMLElement>('[data-stack-tab-scroll]'))
+
+  const cache: AutoScrollCache = {
+    elements: collect(),
+    observer: null
+  }
+
+  if (typeof MutationObserver !== 'undefined') {
+    cache.observer = new MutationObserver(() => {
+      cache.elements = collect()
+    })
+    // 仅监听子树增删与属性变化，不监听字符数据，减少开销。
+    cache.observer.observe(pageRoot, {
+      childList: true,
+      subtree: true,
+      attributes: true,
+      attributeFilter: ['data-stack-tab-scroll']
+    })
+  }
+
+  return cache
+}
+
+const autoScrollCaches = new Map<string, AutoScrollCache>()
+
+const getAutoScrollCache = (pageCacheId: string): AutoScrollCache | null => {
+  const pageRoot = document.getElementById(`W-${pageCacheId}`)
+  if (!pageRoot) {
+    autoScrollCaches.delete(pageCacheId)
+    return null
+  }
+
+  let cache = autoScrollCaches.get(pageCacheId)
+  if (!cache) {
+    cache = createAutoScrollCache(pageRoot)
+    autoScrollCaches.set(pageCacheId, cache)
+  } else {
+    // 防御：检查 pageRoot 是否已被替换（极端情况：同一 pageCacheId 重新挂载）
+    if (cache.elements.length === 0 && cache.observer) {
+      cache.elements = Array.from(pageRoot.querySelectorAll<HTMLElement>('[data-stack-tab-scroll]'))
+    }
+  }
+  return cache
+}
+
+const getAutoScrollerKey = (index: number): string => `${AUTO_SCROLLER_PREFIX}${index}`
+
+const resolveAutoScrollElement = (pageCacheId: string, key: string): HTMLElement | null => {
+  const index = Number(key.slice(AUTO_SCROLLER_PREFIX.length))
+  if (!Number.isInteger(index)) return null
+  const cache = getAutoScrollCache(pageCacheId)
+  return cache?.elements[index] ?? null
+}
+
 export const createTabPanelScroll = (context: StackTabsRuntimeContext): TabPanelScrollApi => {
   const { scrollPositionsByPageId } = context
 
@@ -25,7 +96,9 @@ export const createTabPanelScroll = (context: StackTabsRuntimeContext): TabPanel
     if (!positions) return
 
     for (const [selector, position] of positions) {
-      const element = resolveScrollElement(selector)
+      const element = selector.startsWith(AUTO_SCROLLER_PREFIX)
+        ? resolveAutoScrollElement(pageCacheId, selector)
+        : resolveScrollElement(selector)
       if (element) {
         element.scrollTop = position.top
         element.scrollLeft = position.left
@@ -37,8 +110,23 @@ export const createTabPanelScroll = (context: StackTabsRuntimeContext): TabPanel
     const positions = scrollPositionsByPageId.get(pageCacheId)
     if (!positions) return
 
+    // 与当前页面 DOM 同步自动标记的容器；移除的元素不保留过期位置。
+    for (const key of positions.keys()) {
+      if (key.startsWith(AUTO_SCROLLER_PREFIX)) positions.delete(key)
+    }
+    const cache = getAutoScrollCache(pageCacheId)
+    const elements = cache?.elements ?? []
+    elements.forEach((element, index) => {
+      positions.set(getAutoScrollerKey(index), {
+        top: element.scrollTop,
+        left: element.scrollLeft
+      })
+    })
+
     for (const selector of positions.keys()) {
-      const element = resolveScrollElement(selector)
+      const element = selector.startsWith(AUTO_SCROLLER_PREFIX)
+        ? resolveAutoScrollElement(pageCacheId, selector)
+        : resolveScrollElement(selector)
       positions.set(selector, {
         top: element?.scrollTop ?? 0,
         left: element?.scrollLeft ?? 0
@@ -48,10 +136,16 @@ export const createTabPanelScroll = (context: StackTabsRuntimeContext): TabPanel
 
   const removeScroller = (pageCacheId: string): void => {
     const positions = scrollPositionsByPageId.get(pageCacheId)
-    if (!positions) return
-
-    positions.clear()
-    scrollPositionsByPageId.delete(pageCacheId)
+    if (positions) {
+      positions.clear()
+      scrollPositionsByPageId.delete(pageCacheId)
+    }
+    // 同步卸载 MutationObserver，避免页面被驱逐后 observer 仍持有 DOM 引用。
+    const cache = autoScrollCaches.get(pageCacheId)
+    if (cache) {
+      cache.observer?.disconnect()
+      autoScrollCaches.delete(pageCacheId)
+    }
   }
 
   const addPageScroller = (pageCacheId: string, ...selectorIds: string[]): void => {
@@ -64,10 +158,19 @@ export const createTabPanelScroll = (context: StackTabsRuntimeContext): TabPanel
     }
   }
 
+  const invalidateAutoScrollCache = (pageCacheId: string): void => {
+    const cache = autoScrollCaches.get(pageCacheId)
+    if (!cache) return
+    cache.elements = []
+    cache.observer?.disconnect()
+    autoScrollCaches.delete(pageCacheId)
+  }
+
   return {
     restoreScroller,
     saveScroller,
     removeScroller,
-    addPageScroller
+    addPageScroller,
+    invalidateAutoScrollCache
   }
 }

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

@@ -33,12 +33,38 @@ export const createTabPanelSession = (context: StackTabsRuntimeContext): TabPane
   let writeVersion = 0
   let writeScheduled = false
 
+  /**
+   * 写入 sessionStorage，捕获隐私模式（QuotaExceededError）等异常，
+   * 避免在受限浏览器环境下抛出未处理错误。SSR 环境无 window 时直接跳过。
+   */
+  const safeSetItem = (key: string, value: string): void => {
+    if (typeof window === 'undefined') return
+    try {
+      window.sessionStorage.setItem(key, value)
+    } catch (error) {
+      if (!import.meta.env.PROD) {
+        console.warn('[vue-stack-tabs] Failed to write sessionStorage:', error)
+      }
+    }
+  }
+
+  const safeRemoveItem = (key: string): void => {
+    if (typeof window === 'undefined') return
+    try {
+      window.sessionStorage.removeItem(key)
+    } catch (error) {
+      if (!import.meta.env.PROD) {
+        console.warn('[vue-stack-tabs] Failed to clear sessionStorage:', error)
+      }
+    }
+  }
+
   const flushPendingWrite = () => {
     writeScheduled = false
     const write = pendingWrite
     pendingWrite = null
     if (!write || write.version !== writeVersion) return
-    window.sessionStorage.setItem(getSessionKey(), JSON.stringify(write.tab))
+    safeSetItem(getSessionKey(), JSON.stringify(write.tab))
   }
 
   const invalidatePendingWrite = () => {
@@ -56,7 +82,7 @@ export const createTabPanelSession = (context: StackTabsRuntimeContext): TabPane
 
   const clearSession = (): void => {
     invalidatePendingWrite()
-    window.sessionStorage.removeItem(getSessionKey())
+    safeRemoveItem(getSessionKey())
   }
 
   const restoreActiveTabSession = (storedJson: string | null): void => {
@@ -65,7 +91,7 @@ export const createTabPanelSession = (context: StackTabsRuntimeContext): TabPane
       return
     }
     invalidatePendingWrite()
-    window.sessionStorage.setItem(getSessionKey(), storedJson)
+    safeSetItem(getSessionKey(), storedJson)
   }
 
   const restoreTabFromSession = (storedJson: string | null): ITabItem | null => {

package/src/lib/hooks/useContextMenu.ts

@@ -19,29 +19,75 @@ export default () => {
   /** 菜单是否显示 */
   const shown = ref<boolean>(false)
 
-  /** 点击菜单外部时关闭菜单并移除监听 */
+  /** 关闭菜单并清理全局事件。 */
+  const hideContextMenu = () => {
+    shown.value = false
+    document.removeEventListener('click', handleClickOutside)
+    document.removeEventListener('focusin', handleDocumentFocusIn, true)
+    window.removeEventListener('blur', handleWindowBlur)
+  }
+
+  /**
+   * 记录最近一次 showContextMenu 触发的时间戳。contextmenu 派发后部分浏览器
+   * 会再派发一次 click 事件；如果 click 时间与 contextmenu 太近，则忽略本次 click，
+   * 避免菜单刚显示就被自身点击触发 handleClickOutside 关闭。
+   * 同时也是上一轮 await nextTick() 双跳方案之外的兜底：nextTick 在极端时序下
+   * 仍可能晚于同一帧的 click 派发。
+   */
+  let lastContextMenuAt = 0
+  /** 触发菜单后 BUBBLE_GUARD_MS 毫秒内的 click 视为「同一手势」，不关闭菜单 */
+  const BUBBLE_GUARD_MS = 250
+
+  /** 点击菜单外部时关闭菜单。 */
   const handleClickOutside = (ev: MouseEvent) => {
     const target = ev.target as Element
     if (target.closest?.('.stack-tab__contextmenu')) return
-    shown.value = false
-    document.removeEventListener('click', handleClickOutside)
+    // 同一手势的 click 仍在守卫窗口内，跳过关闭判断。
+    if (Date.now() - lastContextMenuAt < BUBBLE_GUARD_MS) return
+    hideContextMenu()
+  }
+
+  /**
+   * iframe 内的点击不会冒泡到父页面，但 iframe 自身会在父文档中获得焦点。
+   * 捕获 focusin 仅处理该元素，避免 window.blur 干扰菜单内部的焦点管理。
+   */
+  const handleDocumentFocusIn = (event: FocusEvent) => {
+    if (event.target instanceof HTMLIFrameElement) hideContextMenu()
+  }
+
+  /**
+   * 部分浏览器不会把 iframe 内部点击的 focusin 派发到父文档；此时父窗口
+   * 会失焦。等待焦点完成切换后，只在 activeElement 确实为 iframe 时收起。
+   */
+  const handleWindowBlur = () => {
+    window.requestAnimationFrame(() => {
+      if (document.activeElement instanceof HTMLIFrameElement) hideContextMenu()
+    })
   }
 
   onUnmounted(() => {
-    document.removeEventListener('click', handleClickOutside)
+    hideContextMenu()
   })
 
-  /** 显示右键菜单；nextTick 后设置位置与数据，避免与关闭逻辑冲突 */
+  /** 显示右键菜单；nextTick 后设置位置与数据，再下一拍挂载外部点击监听，避免与关闭逻辑冲突 */
   const showContextMenu = async (e: MouseEvent, item: ITabItem, index: number, max: number) => {
+    // 先更新守卫时间戳，确保紧随其后的 click 事件被 handleClickOutside 忽略。
+    lastContextMenuAt = Date.now()
     shown.value = false
     document.removeEventListener('click', handleClickOutside)
+    document.removeEventListener('focusin', handleDocumentFocusIn, true)
+    window.removeEventListener('blur', handleWindowBlur)
 
-    await nextTick(() => {
-      const { clientY: top, clientX: left } = e
-      shown.value = true
-      Object.assign(contextMenuData, { item, index, top, left, max })
-      nextTick(() => document.addEventListener('click', handleClickOutside))
-    })
+    await nextTick()
+    const { clientY: top, clientX: left } = e
+    shown.value = true
+    Object.assign(contextMenuData, { item, index, top, left, max })
+
+    // 等下一拍再挂载 click 监听，避免本次触发 showContextMenu 的同一 click 事件被立即关闭。
+    await nextTick()
+    document.addEventListener('click', handleClickOutside)
+    document.addEventListener('focusin', handleDocumentFocusIn, true)
+    window.addEventListener('blur', handleWindowBlur)
   }
 
   return {

package/src/lib/hooks/useIframeManager.ts

@@ -4,7 +4,7 @@
  * 统一管理所有 iframe 标签的 src 计算、加载状态追踪、超时检测、
  * 刷新控制、DOM ref 收集，以及 postMessage 通信。
  */
-import { computed, onBeforeUnmount, reactive, watch, type Ref } from 'vue'
+import { computed, nextTick, onBeforeUnmount, reactive, watch, type Ref } from 'vue'
 import type { ITabData, ITabItem } from '../model/TabModel'
 import { toSafeTabUrl } from '../utils/urlParser'
 import { getPostMessageTargetOrigin, isStackTabsOpenTabMessage } from '../utils/stackTabsMessage'
@@ -34,6 +34,9 @@ export function useIframeManager(options: UseIframeManagerOptions) {
   const iframeEverActivated = reactive<Record<string, boolean>>({})
 
   const appendIframeRefreshKey = (src: string, refreshKey: number): string => {
+    // 仅当 refreshKey > 0 时附加查询参数：
+    // - 初次激活（key=0）保留干净的 URL，便于用户阅读和书签
+    // - 后续 reload / 重试时附加，用于强制浏览器破坏 iframe 缓存
     if (refreshKey <= 0 || src === 'about:blank') return src
 
     const hashIndex = src.indexOf('#')
@@ -113,7 +116,11 @@ export function useIframeManager(options: UseIframeManagerOptions) {
       ...iframeRefreshKeys.value,
       [frameId]: (iframeRefreshKeys.value[frameId] ?? 0) + 1
     }
-    setIframeLoading(frameId, { force: true })
+    // 等下一拍再设置 loading 状态，让 refreshKey watcher 先把新 src 反映到 DOM 上，
+    // 避免 loading 遮罩先于 src 变化显示，造成视觉抖动。
+    nextTick(() => {
+      setIframeLoading(frameId, { force: true })
+    })
   }
 
   const shouldShowIframeLoading = (frameId: string) =>
@@ -148,6 +155,15 @@ export function useIframeManager(options: UseIframeManagerOptions) {
           delete iframeElRefs[id]
         }
       }
+      // 同步清理已不再属于任何 iframe tab 的 refreshKey，避免长会话下 Map 持续膨胀。
+      if (activeIds.size < Object.keys(iframeRefreshKeys.value).length) {
+        const next: Record<string, number> = {}
+        for (const id of activeIds) {
+          const key = iframeRefreshKeys.value[id]
+          if (typeof key === 'number') next[id] = key
+        }
+        iframeRefreshKeys.value = next
+      }
     },
     { immediate: true }
   )