vue-stack-tabs 2.2.0 → 2.3.0

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

@@ -5,15 +5,17 @@
  * 使 useTabPanel 只负责领域状态与路由协调。
  */
 import {
-  Transition,
   cloneVNode,
   defineComponent,
+  nextTick,
   onActivated,
+  onBeforeUnmount,
   onDeactivated,
   onMounted,
   onUnmounted,
   ref,
-  shallowRef
+  shallowRef,
+  watch
 } from 'vue'
 import type { DefineComponent, PropType, VNode } from 'vue'
 import type { ITabBase } from '../../model/TabModel'
@@ -35,6 +37,36 @@ interface PageComponentFactoryOptions {
   removeScroller: (pageId: string) => void
 }
 
+const parseTimeList = (value: string): number[] =>
+  value.split(',').map((item) => Number.parseFloat(item.trim()) || 0)
+
+/** 读取元素当前 transition 的总时长（秒转毫秒），用于等待离场/入场结束。 */
+const getTransitionDurationMs = (element: HTMLElement): number => {
+  if (typeof window === 'undefined') return 0
+  const style = window.getComputedStyle(element)
+  const durations = parseTimeList(style.transitionDuration || '0s')
+  const delays = parseTimeList(style.transitionDelay || '0s')
+  if (durations.length === 0) return 0
+  return (
+    Math.max(
+      ...durations.map((duration, index) => duration + (delays[index % delays.length] ?? 0))
+    ) * 1000
+  )
+}
+
+/** 等待下一帧，让刚添加的 transition 起始样式先生效。 */
+const nextFrame = (): Promise<void> =>
+  new Promise((resolve) => {
+    if (typeof requestAnimationFrame === 'function') requestAnimationFrame(() => resolve())
+    else setTimeout(resolve, 16)
+  })
+
+/** 用户开启「减少动态效果」时直接切换页面，不执行转场。 */
+const prefersReducedMotion = (): boolean =>
+  typeof window !== 'undefined' &&
+  typeof window.matchMedia === 'function' &&
+  window.matchMedia('(prefers-reduced-motion: reduce)').matches
+
 export const createPageComponentFactory = (options: PageComponentFactoryOptions) => {
   const {
     runtimeContext,
@@ -59,8 +91,9 @@ export const createPageComponentFactory = (options: PageComponentFactoryOptions)
     }
 
     /**
-     * 页面壳组件：作为 Transition 的直接子节点，承接刷新时的 key 变化，
+     * 页面壳组件：承接刷新时的 key 变化，让页面重建发生在缓存 wrapper 内部，
      * 避免直接修改 router-view 页面 vnode 的 key 破坏 keep-alive 的实例复用。
+     * 不额外渲染元素，页面可以是单根，也可以是多根节点（Fragment）。
      */
     const PageShell = defineComponent({
       name: `${cacheName}-shell`,
@@ -110,24 +143,156 @@ export const createPageComponentFactory = (options: PageComponentFactoryOptions)
         const lastVnode = shallowRef<VNode | null | undefined>(null)
         const lastCloned = shallowRef<VNode | null>(null)
         const lastBackParams = shallowRef<Record<string, unknown> | null>(null)
-        const lastRefreshVersion = shallowRef<number>(0)
         const pageRoot = ref<HTMLElement | null>(null)
         /**
-         * 转场期间临时把 wrapper 的 overflow 锁为 hidden。
-         * 内部 Transition 的 translateX 作用于页面根元素，若 wrapper 是 overflow:auto，
-         * 位移会让内容短暂溢出并闪出滚动条。
+         * 实际渲染的刷新版本。
+         *
+         * 刷新时先把 wrapper（真实元素，兼容多根节点页面）作为动画主体执行离场，
+         * 离场结束再提升该值重建页面，最后执行入场；因此它会短暂落后于
+         * props.refreshVersion。外层 keep-alive key 保持不变，避免实例累积。
          */
-        const isTransitioning = ref(false)
-        let transitionCount = 0
-        const beginTransition = () => {
-          transitionCount++
-          isTransitioning.value = true
+        const renderedRefreshVersion = ref(props.refreshVersion ?? 0)
+
+        let refreshDisposed = false
+        let isFlushingRefresh = false
+        let queuedRefreshVersion: number | null = null
+        let refreshTimer: ReturnType<typeof setTimeout> | null = null
+        let cancelRefreshWait: (() => void) | null = null
+        let appliedTransitionName = ''
+
+        const clearRefreshTimer = () => {
+          if (refreshTimer === null) return
+          clearTimeout(refreshTimer)
+          refreshTimer = null
         }
-        const endTransition = () => {
-          transitionCount = Math.max(0, transitionCount - 1)
-          if (transitionCount === 0) isTransitioning.value = false
+
+        const removeRefreshClasses = () => {
+          const element = pageRoot.value
+          const name = appliedTransitionName
+          if (!element || !name) return
+          element.classList.remove(
+            `${name}-leave-active`,
+            `${name}-leave-to`,
+            `${name}-enter-active`,
+            `${name}-enter-from`
+          )
+          appliedTransitionName = ''
         }
 
+        /**
+         * 等待一段 transition 结束；transitionend 不可用时用时长兜底。
+         * 元素可能同时有多个过渡属性（opacity / transform），任意一个结束即可。
+         */
+        const waitForRefreshEnd = (duration: number): Promise<void> =>
+          new Promise((resolve) => {
+            const element = pageRoot.value
+            if (!element || duration <= 0) {
+              resolve()
+              return
+            }
+            let settled = false
+            const finish = () => {
+              if (settled) return
+              settled = true
+              cancelRefreshWait = null
+              clearRefreshTimer()
+              element.removeEventListener('transitionend', handleEnd)
+              resolve()
+            }
+            const handleEnd = (event: TransitionEvent) => {
+              if (event.target === element) finish()
+            }
+            cancelRefreshWait = finish
+            element.addEventListener('transitionend', handleEnd)
+            refreshTimer = setTimeout(finish, duration + 80)
+          })
+
+        /**
+         * 执行一次完整的刷新转场：旧内容离场 → 提升版本重建页面 → 新内容入场。
+         *
+         * 动画类名沿用 Vue Transition 的约定（`${name}-leave-active` 等），
+         * 因此自定义页面过渡 CSS 仍然有效；动画主体是缓存 wrapper 本身，
+         * 页面是单根还是多根（Fragment）都不影响。
+         */
+        const runRefreshAnimation = async (targetVersion: number): Promise<void> => {
+          const element = pageRoot.value
+          const name = props.transitionName
+          if (!element || !name || prefersReducedMotion()) {
+            renderedRefreshVersion.value = targetVersion
+            return
+          }
+
+          appliedTransitionName = name
+          element.classList.add(`${name}-leave-active`)
+          const leaveDuration = getTransitionDurationMs(element)
+          if (leaveDuration <= 0) {
+            removeRefreshClasses()
+            renderedRefreshVersion.value = targetVersion
+            return
+          }
+
+          // 先让 leave-active 生效，再添加 leave-to，触发离场过渡。
+          await nextFrame()
+          if (refreshDisposed) {
+            removeRefreshClasses()
+            return
+          }
+          element.classList.add(`${name}-leave-to`)
+          await waitForRefreshEnd(leaveDuration)
+          removeRefreshClasses()
+          if (refreshDisposed) return
+
+          renderedRefreshVersion.value = targetVersion
+          await nextTick()
+          if (refreshDisposed) return
+
+          appliedTransitionName = name
+          // 先把元素落到入场起点（不加 transition，避免从离场终点反向缓动），
+          // 再启用 enter-active，下一帧移除 enter-from，形成标准的入场过渡。
+          element.classList.add(`${name}-enter-from`)
+          void element.offsetWidth
+          element.classList.add(`${name}-enter-active`)
+          const enterDuration = getTransitionDurationMs(element)
+          if (enterDuration <= 0) {
+            removeRefreshClasses()
+            return
+          }
+
+          await nextFrame()
+          if (refreshDisposed) {
+            removeRefreshClasses()
+            return
+          }
+          element.classList.remove(`${name}-enter-from`)
+          await waitForRefreshEnd(enterDuration)
+          removeRefreshClasses()
+        }
+
+        const flushRefreshQueue = async (): Promise<void> => {
+          if (isFlushingRefresh) return
+          isFlushingRefresh = true
+          try {
+            while (!refreshDisposed && queuedRefreshVersion !== null) {
+              const targetVersion = queuedRefreshVersion
+              queuedRefreshVersion = null
+              if (targetVersion === renderedRefreshVersion.value) continue
+              await runRefreshAnimation(targetVersion)
+            }
+          } finally {
+            isFlushingRefresh = false
+          }
+        }
+
+        watch(
+          () => props.refreshVersion ?? 0,
+          (nextVersion) => {
+            if (nextVersion === renderedRefreshVersion.value && queuedRefreshVersion === null)
+              return
+            queuedRefreshVersion = nextVersion
+            void flushRefreshQueue()
+          }
+        )
+
         const checkAndConsumeBackParams = () => {
           localBackParams.value = consumeBackParams(tabInfo.id!, cacheName)
         }
@@ -135,67 +300,71 @@ export const createPageComponentFactory = (options: PageComponentFactoryOptions)
         onMounted(() => {
           context.emit('onLoaded')
           addPageScroller(cacheName, `#W-${cacheName}`)
+          // 新页面经 Transition(out-in) 挂载时，setup 后的 microtask 可能早于 ref 赋值；
+          // 挂载后重新 sync，确保 scroll shadow 监听与阴影类目标正确绑定。
+          scrollShadow.sync()
           checkAndConsumeBackParams()
         })
-        onDeactivated(() => saveScroller(cacheName))
+        onDeactivated(() => {
+          scrollShadow.clear()
+          saveScroller(cacheName)
+        })
         onActivated(() => {
           context.emit('onLoaded')
           restoreScroller(cacheName)
+          scrollShadow.sync()
           evictMarkedCaches()
           clearTabEvictionMarks()
           checkAndConsumeBackParams()
         })
+        onBeforeUnmount(() => {
+          refreshDisposed = true
+          queuedRefreshVersion = null
+          cancelRefreshWait?.()
+          clearRefreshTimer()
+          removeRefreshClasses()
+        })
         onUnmounted(() => removeScroller(cacheName))
 
-        // 给 .stack-tab__cache-page-wrapper 挂滚动阴影，确保 keep-alive 的 suspended/deactivated 生命周期下表现一致
-        useScrollShadow({ target: pageRoot })
+        // 阴影类挂到不被刷新动画 transform 的 panel 上；滚动监听仍绑定 wrapper。
+        // 否则 ::after 的绝对定位包含块会随 transform 变化，顶部阴影会错位/消失。
+        const scrollShadow = useScrollShadow({
+          target: pageRoot,
+          classTarget: () => pageRoot.value?.parentElement ?? null
+        })
 
         return () => {
           const vnode = props.vnode
           const backParams = localBackParams.value
-          const refreshVersion = props.refreshVersion ?? 0
-          if (
-            vnode !== lastVnode.value ||
-            backParams !== lastBackParams.value ||
-            refreshVersion !== lastRefreshVersion.value
-          ) {
-            const cloned = vnode
+          if (vnode !== lastVnode.value || backParams !== lastBackParams.value) {
+            lastCloned.value = vnode
               ? cloneVNode(vnode, {
                   tId: tabInfo.id,
                   pId: cacheName,
                   ...(backParams ? { _back: backParams } : {})
                 })
               : null
-            lastCloned.value = cloned
             lastVnode.value = vnode
             lastBackParams.value = backParams
-            lastRefreshVersion.value = refreshVersion
           }
+
           return (
             <div
               ref={pageRoot}
               class="stack-tab__cache-page-wrapper"
               id={`W-${cacheName}`}
               style={[
-                runtimeContext.useGlobalScroll.value && !isTransitioning.value
-                  ? 'overflow:auto'
-                  : 'overflow:hidden',
+                // 动画作用于 wrapper 本身，页面内容不会相对滚动容器位移，
+                // 因此无需临时隐藏 overflow，避免动画期间滚动条消失导致内容宽度跳动。
+                runtimeContext.useGlobalScroll.value ? 'overflow:auto' : 'overflow:hidden',
                 'height: 100%'
               ]}
             >
               {lastCloned.value ? (
-                <Transition
-                  name={props.transitionName}
-                  mode="out-in"
-                  onBeforeEnter={beginTransition}
-                  onAfterEnter={endTransition}
-                  onEnterCancelled={endTransition}
-                  onBeforeLeave={beginTransition}
-                  onAfterLeave={endTransition}
-                  onLeaveCancelled={endTransition}
-                >
-                  <PageShell key={`${cacheName}-${refreshVersion}`} vnode={lastCloned.value} />
-                </Transition>
+                <PageShell
+                  key={`${cacheName}-${renderedRefreshVersion.value}`}
+                  vnode={lastCloned.value}
+                />
               ) : null}
               <PageLoading tabId={tabInfo.id!} />
             </div>

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

@@ -12,8 +12,6 @@ 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 =>
@@ -124,9 +122,9 @@ export const createTabPanelScroll = (context: StackTabsRuntimeContext): TabPanel
     })
 
     for (const selector of positions.keys()) {
-      const element = selector.startsWith(AUTO_SCROLLER_PREFIX)
-        ? resolveAutoScrollElement(pageCacheId, selector)
-        : resolveScrollElement(selector)
+      // auto key 已在上一步按 DOM 顺序写入，无需再次解析。
+      if (selector.startsWith(AUTO_SCROLLER_PREFIX)) continue
+      const element = resolveScrollElement(selector)
       positions.set(selector, {
         top: element?.scrollTop ?? 0,
         left: element?.scrollLeft ?? 0
@@ -158,19 +156,10 @@ 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,
-    invalidateAutoScrollCache
+    addPageScroller
   }
 }

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

@@ -32,19 +32,23 @@ export const createTabPanelSession = (context: StackTabsRuntimeContext): TabPane
   let pendingWrite: { tab: ITabItem; version: number } | null = null
   let writeVersion = 0
   let writeScheduled = false
+  /** 最近一次成功写入的内容；与待写入内容相同时跳过 setItem。 */
+  let lastPersistedJson: string | null = null
 
   /**
    * 写入 sessionStorage，捕获隐私模式（QuotaExceededError）等异常，
    * 避免在受限浏览器环境下抛出未处理错误。SSR 环境无 window 时直接跳过。
    */
-  const safeSetItem = (key: string, value: string): void => {
-    if (typeof window === 'undefined') return
+  const safeSetItem = (key: string, value: string): boolean => {
+    if (typeof window === 'undefined') return false
     try {
       window.sessionStorage.setItem(key, value)
+      return true
     } catch (error) {
       if (!import.meta.env.PROD) {
         console.warn('[vue-stack-tabs] Failed to write sessionStorage:', error)
       }
+      return false
     }
   }
 
@@ -64,7 +68,9 @@ export const createTabPanelSession = (context: StackTabsRuntimeContext): TabPane
     const write = pendingWrite
     pendingWrite = null
     if (!write || write.version !== writeVersion) return
-    safeSetItem(getSessionKey(), JSON.stringify(write.tab))
+    const serialized = JSON.stringify(write.tab)
+    if (serialized === lastPersistedJson) return
+    if (safeSetItem(getSessionKey(), serialized)) lastPersistedJson = serialized
   }
 
   const invalidatePendingWrite = () => {
@@ -83,6 +89,7 @@ export const createTabPanelSession = (context: StackTabsRuntimeContext): TabPane
   const clearSession = (): void => {
     invalidatePendingWrite()
     safeRemoveItem(getSessionKey())
+    lastPersistedJson = null
   }
 
   const restoreActiveTabSession = (storedJson: string | null): void => {
@@ -91,7 +98,7 @@ export const createTabPanelSession = (context: StackTabsRuntimeContext): TabPane
       return
     }
     invalidatePendingWrite()
-    safeSetItem(getSessionKey(), storedJson)
+    if (safeSetItem(getSessionKey(), storedJson)) lastPersistedJson = storedJson
   }
 
   const restoreTabFromSession = (storedJson: string | null): ITabItem | null => {

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

@@ -15,7 +15,6 @@ export interface ScrollPosition {
 
 export interface TabPanelRuntimeState {
   tabs: Ref<ITabItem[]>
-  defaultTabs: Ref<ITabItem[]>
   caches: ShallowRef<string[]>
   components: Map<string, DefineComponent>
   cacheIdsToEvict: Set<string>
@@ -34,7 +33,6 @@ export const SESSION_TAB_NAME = 'stacktab-active-tab'
 
 export const createTabPanelRuntimeState = (): TabPanelRuntimeState => ({
   tabs: ref<ITabItem[]>([]) as Ref<ITabItem[]>,
-  defaultTabs: ref<ITabItem[]>([]) as Ref<ITabItem[]>,
   caches: shallowRef<string[]>([]),
   components: new Map<string, DefineComponent>(),
   cacheIdsToEvict: new Set<string>(),

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

@@ -121,6 +121,9 @@ interface TabRecord {
 
 interface PageStackAccess {
   getPages: (tabId: string) => readonly ITabPage[]
+  getPageIds: (tabId: string) => readonly string[]
+  getPageAt: (tabId: string, index: number) => ITabPage | undefined
+  getPageCount: (tabId: string) => number
   getTopPage: (tabId: string) => ITabPage | null
   /** 读取任意页面的刷新版本；渲染层据此只重建对应页面 */
   getPageRefreshVersion: (pageId: string) => number
@@ -156,15 +159,16 @@ class PageStackView extends Stack<ITabPage> {
   }
 
   override at(index: number): ITabPage | undefined {
-    return this.access.getPages(this.tabId)[index]
+    // 只取单个元素时不必构造整条页面数组。
+    return this.access.getPageAt(this.tabId, index)
   }
 
   override isEmpty(): boolean {
-    return this.access.getPages(this.tabId).length === 0
+    return this.access.getPageCount(this.tabId) === 0
   }
 
   override size(): number {
-    return this.access.getPages(this.tabId).length
+    return this.access.getPageCount(this.tabId)
   }
 
   override clear(): void {
@@ -251,6 +255,15 @@ const createTabStore = (context: StackTabsRuntimeContext): TabStoreApi => {
     return pagesById.get(ids[ids.length - 1] as string) ?? null
   }
 
+  const getPageCount = (tabId: string): number => pageIdsByTabId.get(tabId)?.length ?? 0
+
+  /** 按下标读取页面；越界（含负数）返回 undefined，与数组下标语义一致 */
+  const getPageAt = (tabId: string, index: number): ITabPage | undefined => {
+    const ids = pageIdsByTabId.get(tabId)
+    if (!ids || index < 0 || index >= ids.length) return undefined
+    return pagesById.get(ids[index] as string)
+  }
+
   const getPageRefreshVersion = (pageId: string): number =>
     pagesById.get(pageId)?.refreshVersion ?? 0
 
@@ -310,8 +323,12 @@ const createTabStore = (context: StackTabsRuntimeContext): TabStoreApi => {
   }
 
   const activateTab = (id: string): ITabItem | null => {
-    activeTabId.value = tabsById.has(id) ? id : ''
-    syncTabsView()
+    const nextId = tabsById.has(id) ? id : ''
+    // 重复激活同一标签（页面内导航经常走到这里）无需重建 tabs 数组。
+    if (nextId !== activeTabId.value) {
+      activeTabId.value = nextId
+      syncTabsView()
+    }
     return getTab(id)
   }
 
@@ -416,12 +433,13 @@ const createTabStore = (context: StackTabsRuntimeContext): TabStoreApi => {
   }
 
   // ---- 页面栈写入 ----
+  // 页面栈只修改 pageIdsByTabId / pagesById（两者都是响应式 Map），
+  // 不重建 tabs 数组：标签栏、iframe 与刷新版本计算都无需因入栈/出栈重新求值。
   const appendPage = (tabId: string, page: ITabPage): void => {
     if (!tabsById.has(tabId)) return
     const ids = pageIdsByTabId.get(tabId) ?? []
     pageIdsByTabId.set(tabId, [...ids, page.id])
     pagesById.set(page.id, page)
-    syncTabsView()
   }
 
   const popPages = (tabId: string, steps: number): ITabPage[] => {
@@ -437,7 +455,6 @@ const createTabStore = (context: StackTabsRuntimeContext): TabStoreApi => {
       pagesById.delete(pageId)
     }
     pageIdsByTabId.set(tabId, ids)
-    syncTabsView()
     return popped
   }
 
@@ -452,14 +469,12 @@ const createTabStore = (context: StackTabsRuntimeContext): TabStoreApi => {
       nextPageIds.push(cloned.id)
     }
     pageIdsByTabId.set(tabId, nextPageIds)
-    syncTabsView()
   }
 
   const clearPages = (tabId: string): void => {
     if (!tabsById.has(tabId)) return
     for (const pageId of getPageIds(tabId)) pagesById.delete(pageId)
     pageIdsByTabId.set(tabId, [])
-    syncTabsView()
   }
 
   const applyPagePatch = (
@@ -512,8 +527,8 @@ const createTabStore = (context: StackTabsRuntimeContext): TabStoreApi => {
     const top = getTopPage(tabId)
     if (!top || top.id !== pageId || !top._backParams) return null
     const backParams = { ...top._backParams }
+    // _backParams 是页面对象上的响应式字段，删除后读取方会自行更新。
     delete top._backParams
-    syncTabsView()
     return backParams
   }
 
@@ -548,6 +563,9 @@ const createTabStore = (context: StackTabsRuntimeContext): TabStoreApi => {
   // ---- 兼容视图 ----
   const pageAccess: PageStackAccess = {
     getPages,
+    getPageIds,
+    getPageAt,
+    getPageCount,
     getTopPage,
     getPageRefreshVersion,
     appendPage,

package/src/lib/hooks/useIframeManager.ts

@@ -19,7 +19,7 @@ interface IframeLoadState {
 export interface UseIframeManagerOptions {
   tabs: Ref<ITabItem[]>
   iframeRefreshKeys: Ref<Record<string, number>>
-  iframeLoadTimeout: number
+  iframeLoadTimeout: Ref<number>
   t: (key: string) => string
 }
 
@@ -106,7 +106,7 @@ export function useIframeManager(options: UseIframeManagerOptions) {
             message: t('VueStackTab.iframeLoadTimeout')
           }
         }
-      }, iframeLoadTimeout)
+      }, iframeLoadTimeout.value)
     )
   }
 
@@ -176,20 +176,16 @@ export function useIframeManager(options: UseIframeManagerOptions) {
   )
 
   // refreshKey 变化时重新触发对应 iframe 的加载状态
-  watch(
-    iframeRefreshKeys,
-    (keys, previousKeys = {}) => {
-      for (const frame of iframeTabs.value) {
-        if (!frame.active) continue
-        const nextKey = keys[frame.id] ?? 0
-        const previousKey = previousKeys[frame.id] ?? 0
-        if (nextKey !== previousKey) {
-          setIframeLoading(frame.id, { force: true })
-        }
+  watch(iframeRefreshKeys, (keys, previousKeys = {}) => {
+    for (const frame of iframeTabs.value) {
+      if (!frame.active) continue
+      const nextKey = keys[frame.id] ?? 0
+      const previousKey = previousKeys[frame.id] ?? 0
+      if (nextKey !== previousKey) {
+        setIframeLoading(frame.id, { force: true })
       }
-    },
-    { deep: true }
-  )
+    }
+  })
 
   const handleIframeLoad = (frame: { id: string; url?: string }, event: Event) => {
     const iframe = event.currentTarget as HTMLIFrameElement | null