vue-stack-tabs 1.4.2 → 2.3.0

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

@@ -23,13 +23,10 @@
           <tab-header-item
             v-for="(item, index) in tabs"
             :key="item.id"
-            :item="item as ITabItem"
+            :item="item"
             :drop-position="dropIndicator?.tabId === item.id ? dropIndicator.position : undefined"
-            @contextmenu="
-              (e: MouseEvent) =>
-                handleTabContextMenu(e, item as unknown as ITabItem, index, tabs.length)
-            "
-            @click.middle.prevent="handleCloseTab(item as ITabItem)"
+            @contextmenu="(e: MouseEvent) => handleTabContextMenu(e, item, index, tabs.length)"
+            @click.middle.prevent="handleCloseTab(item)"
             @close="handleCloseTab"
             @active="handleActivateTab"
             @dragstart="handleTabDragStart"
@@ -42,7 +39,11 @@
     </tab-header-scroll>
     <slot name="rightButton" />
     <tab-header-button
-      :icon-class="maximum ? 'stack-tab__icon-restore' : 'stack-tab__icon-fullscreen'"
+      :icon-class="
+        maximum
+          ? 'stack-tab__icon stack-tab__icon--restore'
+          : 'stack-tab__icon stack-tab__icon--fullscreen'
+      "
       :title="maximum ? t('VueStackTab.restore') : t('VueStackTab.maximum')"
       :aria-label="maximum ? t('VueStackTab.restore') : t('VueStackTab.maximum')"
       @click="maximum = !maximum"
@@ -71,7 +72,7 @@
   依赖：useTabActions(tabs/closeTab/activeTab)、useContextMenu
 -->
 <script lang="ts" setup>
-import { inject, computed, ref, nextTick } from 'vue'
+import { inject, computed, ref, nextTick, watch, onUnmounted } from 'vue'
 import type { TransitionProps } from 'vue'
 import { TabScrollMode } from '../../model/TabModel'
 import type { IContextMenu, ITabItem } from '../../model/TabModel'
@@ -83,6 +84,7 @@ import TabHeaderScroll from './TabHeaderScroll.vue'
 import TabHeaderButton from './TabHeaderButton.vue'
 import { useI18n } from 'vue-i18n-lite'
 import { maximumKey } from '../../hooks/stackTabsContext'
+import { TabEventType, useTabEmitter } from '../../hooks/useTabEventBus'
 const { t } = useI18n()
 /** 是否最大化，由上层 provide */
 const maximum = inject(maximumKey, ref(false))
@@ -117,6 +119,47 @@ const props = withDefaults(
   }
 )
 const { closeTab, activeTab, moveTab, tabs } = useTabActions()
+
+/** 当前激活标签 id */
+const activeTabId = computed<string>(() => tabs.value.find((tab) => tab.active)?.id ?? '')
+
+/**
+ * 将指定标签滚动到可视区域；未指定 id 时使用当前激活标签。
+ * 仅在标签确实不可见时才滚动，避免干扰用户的手动滚动。
+ */
+const ensureTabInView = (tabId?: string) => {
+  const scrollContainer = scrollContainerRef.value
+  if (!scrollContainer) return
+
+  const target = headerRef.value?.querySelector<HTMLElement>(
+    tabId
+      ? `.stack-tab__nav [role="tab"][data-tab-id="${CSS.escape(tabId)}"]`
+      : '.stack-tab__nav .stack-tab__item--active'
+  )
+  const tabElement = target?.closest<HTMLElement>('.stack-tab__item')
+  if (tabElement && !scrollContainer.isInView(tabElement)) {
+    scrollContainer.scrollIntoView(tabElement)
+  }
+}
+
+/**
+ * 激活标签变化后确保其位于可视区域：
+ * 覆盖新开标签、通过 openTab 唤醒已有标签、关闭标签后顺延激活等场景。
+ * 仅响应用户主动滚动时不会触发（滚动不改变 active），因此不会把视图强行拉回。
+ */
+watch(activeTabId, () => {
+  nextTick(() => ensureTabInView())
+})
+
+/** 标签已是 active 但被滚开时，显式打开/激活请求仍需把标签栏滚动到它。 */
+const emitter = useTabEmitter()
+const handleTabScrollTo = ({ id }: { id: string }) => {
+  nextTick(() => ensureTabInView(id))
+}
+emitter.on(TabEventType.TAB_SCROLL_TO, handleTabScrollTo)
+onUnmounted(() => {
+  emitter.off(TabEventType.TAB_SCROLL_TO, handleTabScrollTo)
+})
 const draggingTabId = ref<string | null>(null)
 type DropPosition = 'before' | 'after'
 const dropIndicator = ref<{ tabId: string; position: DropPosition } | null>(null)
@@ -149,6 +192,7 @@ const handleTabContextMenu = (e: MouseEvent, item: ITabItem, index: number, max:
 
 /** 原生拖放只在释放鼠标时更新顺序，避免拖动经过标签时反复变更响应式列表。 */
 const handleTabDragStart = (item: ITabItem) => {
+  if (item.pinned) return
   draggingTabId.value = item.id
 }
 
@@ -161,9 +205,11 @@ const handleTabDragOver = (item: ITabItem, event: DragEvent) => {
   if (!tabElement) return
 
   const { left, width } = tabElement.getBoundingClientRect()
+  const position = event.clientX < left + width / 2 ? 'before' : 'after'
   dropIndicator.value = {
     tabId: item.id,
-    position: event.clientX < left + width / 2 ? 'before' : 'after'
+    // pinned 标签固定在左侧，拖到它前半区时改为插到它后面。
+    position: item.pinned && position === 'before' ? 'after' : position
   }
   if (event.dataTransfer) event.dataTransfer.dropEffect = 'move'
 }
@@ -181,6 +227,13 @@ const handleTabDrop = (target: ITabItem) => {
   let destinationIndex = targetIndex
   if (indicator.position === 'before' && sourceIndex < targetIndex) destinationIndex--
   if (indicator.position === 'after' && sourceIndex > targetIndex) destinationIndex++
+
+  // home 等 pinned 标签固定在左侧，任何标签都不能插到它前面（store 层还会再兜底）。
+  let firstUnpinnedIndex = 0
+  tabs.value.forEach((tab, index) => {
+    if (tab.pinned) firstUnpinnedIndex = index + 1
+  })
+  destinationIndex = Math.max(destinationIndex, firstUnpinnedIndex)
   moveTab(sourceId, destinationIndex)
 }
 
@@ -205,7 +258,7 @@ const handleTabListDragOver = (event: DragEvent) => {
 const handleTabListDrop = (event: DragEvent) => {
   if (isTabItemDragEvent(event)) return
   const lastTab = tabs.value[tabs.value.length - 1]
-  if (lastTab) handleTabDrop(lastTab as ITabItem)
+  if (lastTab) handleTabDrop(lastTab)
 }
 
 /** 标签列表 transition 的 props，支持 string 或对象 */
@@ -234,7 +287,7 @@ const focusTabById = (tabId: string) => {
 const activateTabByIndex = (index: number) => {
   const item = tabs.value[index]
   if (!item) return
-  handleActivateTab(item as ITabItem, undefined, true)
+  handleActivateTab(item, undefined, true)
   focusTabById(String(item.id))
 }
 
@@ -303,7 +356,9 @@ const handleActivateTab = (
   Promise.resolve(activeTab(item.id, isRoute))
     .then(() => emit('active', item.id))
     .catch((error: unknown) => {
-      console.warn('[vue-stack-tabs] Failed to activate tab:', error)
+      if (!import.meta.env.PROD) {
+        console.warn('[vue-stack-tabs] Failed to activate tab:', error)
+      }
     })
 }
 </script>

package/src/lib/hooks/stackTabsContext.ts

@@ -23,7 +23,6 @@ export const STACK_TABS_DUPLICATE_INSTANCE_MESSAGE =
 
 export interface StackTabsRuntimeContext {
   tabs: Ref<ITabItem[]>
-  defaultTabs: Ref<ITabItem[]>
   caches: ShallowRef<string[]>
   components: Map<string, DefineComponent>
   cacheIdsToEvict: Set<string>

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

@@ -9,8 +9,11 @@ import type { StackTabsRuntimeContext } from '../stackTabsContext'
 
 export interface TabPanelEvictionApi {
   markCacheForEviction: (cacheName: string) => void
-  markTabPagesForEviction: (tab: { id: string; pages: { list(): ITabPage[] } }) => void
-  markTabPagesForEvictionOnly: (tab: { pages: { list(): ITabPage[] } }) => void
+  markTabPagesForEviction: (tab: {
+    id: string
+    pages: { readonlyList(): readonly ITabPage[] }
+  }) => void
+  markTabPagesForEvictionOnly: (tab: { pages: { readonlyList(): readonly ITabPage[] } }) => void
   addCache: (cacheName: string) => void
   removeCache: (cacheName: string) => void
   evictPageCache: (cacheName: string) => void
@@ -39,13 +42,18 @@ export const createTabPanelEviction = (context: StackTabsRuntimeContext): TabPan
     cacheIdsToEvict.add(cacheName)
   }
 
-  const markTabPagesForEviction = (tab: { id: string; pages: { list(): ITabPage[] } }): void => {
-    for (const page of tab.pages.list()) markCacheForEviction(page.id)
+  const markTabPagesForEviction = (tab: {
+    id: string
+    pages: { readonlyList(): readonly ITabPage[] }
+  }): void => {
+    for (const page of tab.pages.readonlyList()) markCacheForEviction(page.id)
     tabIdsToEvict.add(tab.id)
   }
 
-  const markTabPagesForEvictionOnly = (tab: { pages: { list(): ITabPage[] } }): void => {
-    for (const page of tab.pages.list()) markCacheForEviction(page.id)
+  const markTabPagesForEvictionOnly = (tab: {
+    pages: { readonlyList(): readonly ITabPage[] }
+  }): void => {
+    for (const page of tab.pages.readonlyList()) markCacheForEviction(page.id)
   }
 
   const addCache = (cacheName: string): void => {

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

@@ -7,12 +7,15 @@
 import {
   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'
@@ -34,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,
@@ -57,13 +90,51 @@ export const createPageComponentFactory = (options: PageComponentFactoryOptions)
       return existing
     }
 
-    const cacheComponent = defineComponent<{ vnode?: VNode }>({
+    /**
+     * 页面壳组件：承接刷新时的 key 变化，让页面重建发生在缓存 wrapper 内部，
+     * 避免直接修改 router-view 页面 vnode 的 key 破坏 keep-alive 的实例复用。
+     * 不额外渲染元素，页面可以是单根，也可以是多根节点（Fragment）。
+     */
+    const PageShell = defineComponent({
+      name: `${cacheName}-shell`,
+      props: {
+        vnode: {
+          type: Object as PropType<VNode | null>,
+          required: false,
+          default: null
+        }
+      },
+      setup(props) {
+        return () => props.vnode
+      }
+    })
+
+    const cacheComponent = defineComponent<{
+      vnode?: VNode
+      refreshVersion?: number
+      transitionName?: string
+    }>({
       name: cacheName,
       props: {
         vnode: {
           type: Object as PropType<VNode>,
           required: false,
           default: undefined
+        },
+        /**
+         * 页面级刷新版本。外层 keep-alive 的 key 保持稳定（避免旧实例滞留缓存），
+         * 刷新时只让内部页面 vnode 的 key 变化，从而重建页面组件而保留包装层与滚动位置。
+         */
+        refreshVersion: {
+          type: Number,
+          required: false,
+          default: 0
+        },
+        /** 页面转场名，与 StackKeepAlive 外层 Transition 保持一致 */
+        transitionName: {
+          type: String,
+          required: false,
+          default: ''
         }
       },
       emits: ['onLoaded'],
@@ -73,6 +144,154 @@ export const createPageComponentFactory = (options: PageComponentFactoryOptions)
         const lastCloned = shallowRef<VNode | null>(null)
         const lastBackParams = shallowRef<Record<string, unknown> | null>(null)
         const pageRoot = ref<HTMLElement | null>(null)
+        /**
+         * 实际渲染的刷新版本。
+         *
+         * 刷新时先把 wrapper（真实元素，兼容多根节点页面）作为动画主体执行离场，
+         * 离场结束再提升该值重建页面，最后执行入场；因此它会短暂落后于
+         * props.refreshVersion。外层 keep-alive key 保持不变，避免实例累积。
+         */
+        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 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)
@@ -81,20 +300,38 @@ 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))
 
-        // 给 .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
@@ -110,17 +347,25 @@ export const createPageComponentFactory = (options: PageComponentFactoryOptions)
             lastVnode.value = vnode
             lastBackParams.value = backParams
           }
+
           return (
             <div
               ref={pageRoot}
-              class="cache-page-wrapper"
+              class="stack-tab__cache-page-wrapper"
               id={`W-${cacheName}`}
               style={[
+                // 动画作用于 wrapper 本身，页面内容不会相对滚动容器位移，
+                // 因此无需临时隐藏 overflow，避免动画期间滚动条消失导致内容宽度跳动。
                 runtimeContext.useGlobalScroll.value ? 'overflow:auto' : 'overflow:hidden',
                 'height: 100%'
               ]}
             >
-              {lastCloned.value}
+              {lastCloned.value ? (
+                <PageShell
+                  key={`${cacheName}-${renderedRefreshVersion.value}`}
+                  vnode={lastCloned.value}
+                />
+              ) : null}
               <PageLoading tabId={tabInfo.id!} />
             </div>
           )

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

@@ -5,7 +5,7 @@
  */
 import type { Ref } from 'vue'
 import type { ITabItem, ITabPage } from '../../model/TabModel'
-import type { PagePatch } from './tabStore'
+import type { PagePatch, PageUpdate } from './tabStore'
 
 export interface TabPanelRefreshApi {
   refreshTab: (id: string) => void
@@ -15,8 +15,10 @@ export interface TabPanelRefreshApi {
 export interface CreateTabPanelRefreshOptions {
   getTabs: () => readonly ITabItem[]
   getTopPage: (tabId: string) => ITabPage | null
-  /** 修改页面字段（刷新版本 / 页面 id）并触发 tabs 更新 */
+  /** 修改页面字段（刷新版本 / 页面 id） */
   updatePage: (tabId: string, pageId: string, patch: PagePatch) => boolean
+  /** 批量修改页面字段，refreshAllTabs 最后统一触发一次 tabs 更新 */
+  updatePages: (updates: readonly PageUpdate[]) => void
   iframeRefreshKeys: Ref<Record<string, number>>
   createPageId: () => string
   addCache: (cacheName: string) => void
@@ -35,6 +37,7 @@ export const createTabPanelRefresh = (
     getTabs,
     getTopPage,
     updatePage,
+    updatePages,
     iframeRefreshKeys,
     createPageId,
     addCache,
@@ -54,21 +57,34 @@ export const createTabPanelRefresh = (
     refreshIframeByPostMessage(tab.id)
   }
 
-  const refreshPage = (tab: ITabItem, cacheNamesToEvict?: string[], cacheNamesToAdd?: string[]) => {
+  const refreshPage = (
+    tab: ITabItem,
+    cacheNamesToEvict?: string[],
+    cacheNamesToAdd?: string[],
+    pageUpdates?: PageUpdate[]
+  ) => {
     const currentPage = getTopPage(tab.id)
     if (!currentPage) return
 
     if (tab.active) {
-      // updatePage 内部会触发 tabs 更新，activePageRefreshVersion 随之重新求值。
-      updatePage(tab.id, currentPage.id, {
-        refreshVersion: (currentPage.refreshVersion ?? 0) + 1
-      })
+      const patch = { refreshVersion: (currentPage.refreshVersion ?? 0) + 1 }
+      if (pageUpdates) {
+        pageUpdates.push({ tabId: tab.id, pageId: currentPage.id, patch })
+      } else {
+        // 只有 refreshVersion 变化：页面对象是响应式的，不需要重建 tabs 数组。
+        updatePage(tab.id, currentPage.id, patch)
+      }
       return
     }
 
     const oldCacheName = currentPage.id
     const nextPageId = createPageId()
-    updatePage(tab.id, oldCacheName, { id: nextPageId, refreshVersion: 0 })
+    const patch = { id: nextPageId, refreshVersion: 0 }
+    if (pageUpdates) {
+      pageUpdates.push({ tabId: tab.id, pageId: oldCacheName, patch })
+    } else {
+      updatePage(tab.id, oldCacheName, patch)
+    }
     if (cacheNamesToEvict && cacheNamesToAdd) {
       cacheNamesToEvict.push(oldCacheName)
       cacheNamesToAdd.push(nextPageId)
@@ -91,6 +107,7 @@ export const createTabPanelRefresh = (
   const refreshAllTabs = () => {
     const cacheNamesToEvict: string[] = []
     const cacheNamesToAdd: string[] = []
+    const pageUpdates: PageUpdate[] = []
     const iframeKeysUpdate = { ...iframeRefreshKeys.value }
     let iframeKeysChanged = false
 
@@ -105,10 +122,11 @@ export const createTabPanelRefresh = (
         }
         continue
       }
-      refreshPage(tab, cacheNamesToEvict, cacheNamesToAdd)
+      refreshPage(tab, cacheNamesToEvict, cacheNamesToAdd, pageUpdates)
     }
 
     if (iframeKeysChanged) iframeRefreshKeys.value = iframeKeysUpdate
+    updatePages(pageUpdates)
     replacePageCaches(cacheNamesToEvict, cacheNamesToAdd)
   }
 

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