vue-stack-tabs 1.3.1 → 1.4.1

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 }
   )

package/src/lib/hooks/useScrollShadow.ts

@@ -0,0 +1,124 @@
+/**
+ * useScrollShadow - 为可滚动容器动态切换上下阴影类。
+ *
+ * 职责：在 scroll 事件触发时根据 scrollTop / scrollHeight 边界，
+ *       给目标元素动态加上/移除 stack-tab__shadow-inset-top / -bottom 类，
+ *       距离边界 > 阈值时显示阴影（提示用户"还能往这个方向滚"），
+ *       已贴边（距离边界 ≤ 阈值）时隐藏阴影，避免到顶/到底后阴影残留误导。
+ *
+ * 设计要点：
+ *  - 使用 passive scroll 监听，不阻塞滚动
+ *  - 使用 ResizeObserver 监视子页面缩放/尺寸变化，重新计算阴影边界
+ *  - 使用 rAF 节流，避免一帧内多次写 class
+ *  - 阈值（默认 5px）内视为已贴边（≤ 阈值）→ 隐藏阴影；超过阈值视为可继续滚动 → 显示阴影
+ *  - SSR 安全：在 document 不存在时直接返回
+ *  - 自动清理：onScopeDispose 移除监听并取消 rAF/disconnect observer
+ */
+import { onScopeDispose, type Ref } from 'vue'
+
+const SHADOW_TOP_CLASS = 'stack-tab__shadow-inset-top'
+const SHADOW_BOTTOM_CLASS = 'stack-tab__shadow-inset-bottom'
+const SHADOW_VERTICAL_CLASS = 'stack-tab__shadow-inset-vertical'
+const DEFAULT_EDGE_THRESHOLD = 5
+
+export interface UseScrollShadowOptions {
+  /** 容器元素的 ref，可以是 Ref<HTMLElement | null> 或 getter 函数 */
+  target: Ref<HTMLElement | null> | (() => HTMLElement | null)
+  /**
+   * 是否监听内容缩放/尺寸变化（默认 true）。
+   * 启用后会用 ResizeObserver 监视目标尺寸，容器或子树尺寸变化都会重新计算阴影边界。
+   */
+  watchResize?: boolean
+  /**
+   * 到顶/到底的判定阈值（px，默认 5）。
+   * 距离边界 ≤ 阈值视为已贴边（不显示阴影）；距离边界 > 阈值视为可继续滚动（显示阴影）。
+   */
+  edgeThreshold?: number
+}
+
+export interface UseScrollShadowReturn {
+  /** 手动同步一次（用于内容变化/resize 后） */
+  sync: () => void
+}
+
+const resolveTarget = (
+  target: Ref<HTMLElement | null> | (() => HTMLElement | null)
+): HTMLElement | null => (typeof target === 'function' ? target() : target.value)
+
+export const useScrollShadow = (options: UseScrollShadowOptions): UseScrollShadowReturn => {
+  if (typeof document === 'undefined') {
+    return { sync: () => undefined }
+  }
+
+  const watchResize = options.watchResize !== false
+  const edgeThreshold = Math.max(0, options.edgeThreshold ?? DEFAULT_EDGE_THRESHOLD)
+  let rafId: number | null = null
+  let attached: HTMLElement | null = null
+  let resizeObserver: ResizeObserver | null = null
+
+  const recompute = (): void => {
+    if (!attached) return
+    const target = attached
+    const { scrollTop, scrollHeight, clientHeight } = target
+    const distanceToTop = scrollTop
+    const distanceToBottom = scrollHeight - clientHeight - scrollTop
+    // 顶部阴影：表示上方还有内容，离开顶部（距离顶部 > 阈值）时显示。
+    // 底部阴影：表示下方还有内容，离开底部（距离底部 > 阈值）时显示。
+    const showTopShadow = distanceToTop > edgeThreshold
+    const showBottomShadow = distanceToBottom > edgeThreshold
+    // 注意：-top / -bottom 是两个独立 CSS 规则、作用在同一个 ::after 上，
+    // 同时加会互相覆盖（后定义的 -bottom 胜出）。因此这里互斥地只加一个类：
+    // 两侧都有内容用 -vertical，只有一侧用 -top / -bottom，贴边时都不加。
+    target.classList.toggle(SHADOW_VERTICAL_CLASS, showTopShadow && showBottomShadow)
+    target.classList.toggle(SHADOW_TOP_CLASS, showTopShadow && !showBottomShadow)
+    target.classList.toggle(SHADOW_BOTTOM_CLASS, !showTopShadow && showBottomShadow)
+  }
+
+  const schedule = (): void => {
+    if (rafId !== null) return
+    rafId = requestAnimationFrame(() => {
+      rafId = null
+      recompute()
+    })
+  }
+
+  const attach = (): void => {
+    const el = resolveTarget(options.target)
+    if (!el || el === attached) return
+    if (attached) {
+      attached.removeEventListener('scroll', schedule)
+      resizeObserver?.disconnect()
+      resizeObserver = null
+    }
+    attached = el
+    el.addEventListener('scroll', schedule, { passive: true })
+    if (watchResize && typeof ResizeObserver !== 'undefined') {
+      resizeObserver = new ResizeObserver(() => schedule())
+      resizeObserver.observe(el)
+    }
+    schedule()
+  }
+
+  const detach = (): void => {
+    if (attached) {
+      attached.removeEventListener('scroll', schedule)
+      attached.classList.remove(SHADOW_TOP_CLASS, SHADOW_BOTTOM_CLASS, SHADOW_VERTICAL_CLASS)
+      attached = null
+    }
+    resizeObserver?.disconnect()
+    resizeObserver = null
+    if (rafId !== null) {
+      cancelAnimationFrame(rafId)
+      rafId = null
+    }
+  }
+
+  // 初始挂载（target 可能是异步插入的 DOM，使用 microtask 等一帧）
+  queueMicrotask(attach)
+
+  onScopeDispose(detach)
+
+  return {
+    sync: () => schedule()
+  }
+}

package/src/lib/hooks/useTabActions.ts

@@ -11,7 +11,7 @@ import {
 } from '../utils/urlParser'
 import type { ITabData, IframeRefreshMode } from '../model/TabModel'
 import { runNavigationTransaction } from './tabPanel/navigationTransaction'
-import { resolveStackTabsRuntimeContext } from './stackTabsContext'
+import { resolveStackTabsRuntimeContext, type StackTabsRuntimeContext } from './stackTabsContext'
 
 /**
  * useTabActions - 标签操作对外 Hook
@@ -26,9 +26,9 @@ import { resolveStackTabsRuntimeContext } from './stackTabsContext'
  * - activeTab(id, isRoute?) 激活标签
  * - reset() 重置（关闭所有）
  */
-export default function useTabActions() {
+export default function useTabActions(providedRuntimeContext?: StackTabsRuntimeContext) {
   const router = useRouter()
-  const runtimeContext = resolveStackTabsRuntimeContext()
+  const runtimeContext = providedRuntimeContext ?? resolveStackTabsRuntimeContext()
   const {
     active,
     hasTab,
@@ -43,7 +43,7 @@ export default function useTabActions() {
     removeAllTabs,
     refreshTab,
     refreshAllTabs
-  } = useTabPanel()
+  } = useTabPanel(runtimeContext)
 
   /** 合并默认值，生成完整 tabInfo */
   const prepareTabInfo = (tab: ITabData): ITabData => {
@@ -80,7 +80,7 @@ export default function useTabActions() {
       let refreshKeySnapshot: number | undefined
 
       if (tabInfo.id && renew && isExistingTab) {
-        const currentTab = getTab(tab.id!)
+        const currentTab = getTab(tabInfo.id!)
         rollbackRenew = renewTab(tab)
         if (currentTab?.active) {
           refreshKeySnapshot = refreshKey.value
@@ -143,9 +143,19 @@ export default function useTabActions() {
     runtimeContext.iframePath.value = path
   }
 
-  /** 获取当前页面的缓存容器 DOM（用于某些需要直接操作 DOM 的场景） */
-  const getWrapper = () => {
-    return document.getElementsByClassName('cache-page-wrapper')[0]
+  /**
+   * 获取缓存页面容器。
+   * 不传参数时保留旧行为并返回第一个容器；多标签场景应传 tabId 或 pageId，
+   * 避免因 DOM 排序而取得错误页面。
+   */
+  const getWrapper = (
+    target: { tabId?: string; pageId?: string } = {}
+  ): HTMLElement | undefined => {
+    if (typeof document === 'undefined') return undefined
+    const pageId =
+      target.pageId ?? (target.tabId ? getTab(target.tabId)?.pages.peek()?.id : undefined)
+    if (pageId) return document.getElementById(`W-${pageId}`) ?? undefined
+    return document.querySelector<HTMLElement>('.cache-page-wrapper') ?? undefined
   }
 
   /** iframe 标签在新窗口打开（无法嵌入时降级） */

package/src/lib/hooks/useTabEventBus.ts

@@ -7,7 +7,7 @@
 import type { InjectionKey } from 'vue'
 import { hasInjectionContext, inject } from 'vue'
 import type { Emitter, EventType } from 'mitt'
-import { resolveStackTabsRuntimeContext } from './stackTabsContext'
+import { resolveStackTabsRuntimeContext, type StackTabsRuntimeContext } from './stackTabsContext'
 
 declare module '@vue/runtime-core' {
   export interface ComponentCustomProperties {
@@ -35,7 +35,9 @@ export interface TabEventPayloadMap extends Record<EventType, unknown> {
 export const tabEmitterKey: InjectionKey<Emitter<TabEventPayloadMap>> = Symbol('tabEmitter')
 
 /** 获取标签事件总线，用于组件间通信 */
-export const useTabEmitter = (): Emitter<TabEventPayloadMap> => {
+export const useTabEmitter = (
+  runtimeContext?: StackTabsRuntimeContext
+): Emitter<TabEventPayloadMap> => {
   const injected = hasInjectionContext() ? inject(tabEmitterKey, null) : null
-  return injected ?? resolveStackTabsRuntimeContext().eventBus
+  return injected ?? runtimeContext?.eventBus ?? resolveStackTabsRuntimeContext().eventBus
 }