vue-stack-tabs 1.4.1 → 2.2.0

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

@@ -7,58 +7,58 @@
 <template>
   <div
     ref="menuElementRef"
-    class="stack-tab__contextmenu"
+    class="stack-tab__context-menu"
     role="menu"
     tabindex="-1"
     :style="{
       left: `${menuPosition.left}px`,
       top: `${menuPosition.top}px`,
-      'z-index': menuZIndex()
+      'z-index': menuZIndexValue
     }"
     @keydown="handleMenuKeydown"
   >
     <context-menu-item
-      icon="stack-tab__icon-reload svg-mask"
+      icon="stack-tab__icon stack-tab__icon--reload stack-tab__icon--mask"
       :title="t('VueStackTab.reload')"
       :disabled="!tabItem.refreshable"
       @click="handleMenuItemClick(() => refreshTab(tabItem.id))"
     />
     <context-menu-item
-      icon="stack-tab__icon-reload-all svg-mask"
+      icon="stack-tab__icon stack-tab__icon--reload-all stack-tab__icon--mask"
       :title="t('VueStackTab.reloadAll')"
       @click="handleMenuItemClick(refreshAllTabs)"
     />
     <context-menu-item
-      icon="stack-tab__icon-close svg-mask"
+      icon="stack-tab__icon stack-tab__icon--close stack-tab__icon--mask"
       :title="t('VueStackTab.close')"
       :disabled="!tabItem.closable"
       @click="handleMenuItemClick(() => closeTab(tabItem.id))"
     />
     <context-menu-item
-      icon="stack-tab__icon-close-lefts svg-mask"
+      icon="stack-tab__icon stack-tab__icon--close-lefts stack-tab__icon--mask"
       :title="t('VueStackTab.closeLeft')"
       :disabled="index <= 0"
       @click="handleMenuItemClick(() => removeLeftTabs(tabItem.id))"
     />
     <context-menu-item
-      icon="stack-tab__icon-close-rights svg-mask"
+      icon="stack-tab__icon stack-tab__icon--close-rights stack-tab__icon--mask"
       :title="t('VueStackTab.closeRight')"
       :disabled="index >= max - 1"
       @click="handleMenuItemClick(() => removeRightTabs(tabItem.id))"
     />
     <context-menu-item
-      icon="stack-tab__icon-close-others svg-mask"
+      icon="stack-tab__icon stack-tab__icon--close-others stack-tab__icon--mask"
       :title="t('VueStackTab.closeOthers')"
       @click="handleMenuItemClick(() => removeOtherTabs(tabItem.id))"
     />
     <context-menu-item
-      icon="stack-tab__icon-close-all svg-mask"
+      icon="stack-tab__icon stack-tab__icon--close-all stack-tab__icon--mask"
       :title="t('VueStackTab.closeAll')"
       @click="handleMenuItemClick(closeAllTabs)"
     />
     <context-menu-item
       v-if="tabItem.iframe && tabItem.url"
-      icon="stack-tab__icon-open svg-mask"
+      icon="stack-tab__icon stack-tab__icon--open stack-tab__icon--mask"
       :title="t('VueStackTab.openInNewWindow')"
       @click="handleMenuItemClick(() => openInNewWindow(tabItem.id))"
     />
@@ -115,13 +115,8 @@ const menuPosition = reactive({ left: props.left, top: props.top })
 const { closeTab, closeAllTabs, refreshTab, refreshAllTabs, openInNewWindow } = useTabActions()
 const { removeLeftTabs, removeRightTabs, removeOtherTabs } = useTabPanel()
 
-/**
- * 菜单挂载时 z-index 必须重新计算（DOM 层叠已变化），先用 invalidateZIndexCache 失效再读取。
- */
-const menuZIndex = () => {
-  invalidateZIndexCache('.stack-tab,.stack-tab *')
-  return getMaxZIndex('.stack-tab,.stack-tab *')
-}
+/** 菜单挂载时计算一次 z-index；菜单打开期间层叠关系不会变化。 */
+const menuZIndexValue = ref(0)
 
 const focusActiveTabFallback = () => {
   const activeTab = document.querySelector<HTMLElement>('[role="tab"][aria-selected="true"]')
@@ -204,12 +199,20 @@ const handleMenuKeydown = (event: KeyboardEvent) => {
 const getCustomMenuKey = (item: IContextMenu): string =>
   item.key ?? `${item.title}-${item.icon ?? ''}`
 
-/** 挂载后修正菜单位置，避免超出右边界 */
+/** 挂载后计算 z-index 并修正右/下边界，避免菜单溢出视口 */
 onMounted(() => {
-  const menuWidth = menuElementRef.value?.clientWidth ?? 0
+  invalidateZIndexCache('.stack-tab,.stack-tab *')
+  menuZIndexValue.value = getMaxZIndex('.stack-tab,.stack-tab *')
+
+  const menuElement = menuElementRef.value
+  const menuWidth = menuElement?.clientWidth ?? 0
+  const menuHeight = menuElement?.clientHeight ?? 0
   if (menuPosition.left + menuWidth > window.innerWidth) {
     menuPosition.left = window.innerWidth - menuWidth - 5
   }
+  if (menuPosition.top + menuHeight > window.innerHeight) {
+    menuPosition.top = Math.max(0, window.innerHeight - menuHeight - 5)
+  }
   focusMenuItem(0)
 })
 </script>

package/src/lib/components/PageLoading.vue

@@ -7,13 +7,13 @@
 <template>
   <div
     v-if="isLoading"
-    class="stack-tab-loading-mask"
+    class="stack-tab-loading__mask"
     role="status"
     aria-live="polite"
     :aria-label="t('VueStackTab.loading')"
     :style="{ zIndex: loadingZIndex() }"
   >
-    <div class="stack-tab-loading--spin turn" aria-hidden="true" />
+    <div class="stack-tab-loading__spin" aria-hidden="true" />
   </div>
 </template>
 <script setup lang="ts">
@@ -23,11 +23,11 @@ import { TabEventType, useTabEmitter } from '../hooks/useTabEventBus'
 import { getMaxZIndex, invalidateZIndexCache } from '../utils/scrollUtils'
 
 /**
- * loading 遮罩每次显隐都会改变 .cache-page-wrapper 子树层叠，先失效缓存再读取避免旧值。
+ * loading 遮罩每次显隐都会改变 .stack-tab__cache-page-wrapper 子树层叠，先失效缓存再读取避免旧值。
  */
 const loadingZIndex = () => {
-  invalidateZIndexCache('.cache-page-wrapper *')
-  return getMaxZIndex('.cache-page-wrapper *')
+  invalidateZIndexCache('.stack-tab__cache-page-wrapper *')
+  return getMaxZIndex('.stack-tab__cache-page-wrapper *')
 }
 const props = defineProps<{
   /** 当前标签 id，用于过滤 PAGE_LOADING 事件 */

package/src/lib/components/StackKeepAlive/StackKeepAlive.vue

@@ -27,7 +27,7 @@ const emit = defineEmits<{
   loaded: []
 }>()
 
-const { caches } = useTabPanel()
+const { caches, getPageRefreshVersion } = useTabPanel()
 
 /** 页面组件加载完成时向父组件转发 */
 const emitLoaded = () => {
@@ -38,7 +38,7 @@ const emitLoaded = () => {
 <template>
   <router-view v-slot="{ Component, route }">
     <StackCacheRenderer
-      v-slot="{ wrappedComponent, activeCacheKey, activePageRefreshVersion, component }"
+      v-slot="{ wrappedComponent, activeCacheKey, component }"
       :route="route"
       :component="Component"
     >
@@ -46,8 +46,10 @@ const emitLoaded = () => {
         <keep-alive :include="caches">
           <component
             :is="wrappedComponent"
-            :key="`${activeCacheKey}-${activePageRefreshVersion}`"
+            :key="activeCacheKey"
             :vnode="component"
+            :refresh-version="getPageRefreshVersion(activeCacheKey)"
+            :transition-name="transitionName"
             @on-loaded="emitLoaded"
           />
         </keep-alive>

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

@@ -4,13 +4,14 @@
     role="presentation"
     class="stack-tab__item"
     :class="{
-      'is-active': item.active,
-      'is-icon': item.closable,
-      'is-dragging': dragging,
-      'is-drop-before': dropPosition === 'before',
-      'is-drop-after': dropPosition === 'after'
+      'stack-tab__item--active': item.active,
+      'stack-tab__item--closable': item.closable,
+      'stack-tab__item--pinned': item.pinned,
+      'stack-tab__item--dragging': dragging,
+      'stack-tab__item--drop-before': dropPosition === 'before',
+      'stack-tab__item--drop-after': dropPosition === 'after'
     }"
-    :draggable="true"
+    :draggable="!item.pinned"
     @click.self="handleActivate(true)"
     @contextmenu="$emit('contextmenu', $event)"
     @dragstart="handleDragStart"
@@ -40,7 +41,7 @@
     <button
       v-if="item.closable"
       type="button"
-      class="stack-tab__icon-close-fill stack-tab__item-button"
+      class="stack-tab__icon stack-tab__icon--close-fill stack-tab__item-button"
       :title="t('VueStackTab.close')"
       :aria-label="`${t('VueStackTab.close')} ${title}`"
       :tabindex="item.active ? 0 : -1"
@@ -99,6 +100,11 @@ const handleClose = () => {
   emit('close', props.item)
 }
 const handleDragStart = (event: DragEvent) => {
+  // pinned 标签（home）固定在左侧，不参与拖拽。
+  if (props.item.pinned) {
+    event.preventDefault()
+    return
+  }
   dragging.value = true
   event.dataTransfer?.setData('text/plain', props.item.id)
   if (event.dataTransfer) event.dataTransfer.effectAllowed = 'move'

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

@@ -6,7 +6,7 @@
 <template>
   <tab-header-button
     v-if="isScrollButtonVisible"
-    icon-class="stack-tab__icon-left-arrow"
+    icon-class="stack-tab__icon stack-tab__icon--left-arrow"
     :disabled="isDisabledLeftButton"
     :title="t('VueStackTab.scrollLeft')"
     :aria-label="t('VueStackTab.scrollLeft')"
@@ -29,12 +29,12 @@
       v-show="hasScroller"
       ref="bar"
       class="stack-tab__scrollbar"
-      :class="{ 'is-dragging': scrollDragging }"
+      :class="{ 'stack-tab__scrollbar--dragging': scrollDragging }"
     >
       <div
         ref="thumb"
         class="stack-tab__scrollbar-thumb"
-        :class="{ 'is-dragging': scrollDragging }"
+        :class="{ 'stack-tab__scrollbar-thumb--dragging': scrollDragging }"
         :style="{
           width: `${thumbWidth}px`,
           transform: `translateX(${thumbLeft}px)`
@@ -45,7 +45,7 @@
   </div>
   <tab-header-button
     v-if="isScrollButtonVisible"
-    icon-class="stack-tab__icon-right-arrow"
+    icon-class="stack-tab__icon stack-tab__icon--right-arrow"
     :disabled="isDisabledRightButton"
     :title="t('VueStackTab.scrollRight')"
     :aria-label="t('VueStackTab.scrollRight')"
@@ -161,7 +161,7 @@ const updateScrollState = () => {
 /** 确保激活的标签在可视区域内 */
 const ensureActiveTabInView = () => {
   const activeTabEl = container.value?.querySelector(
-    '.stack-tab__item.is-active'
+    '.stack-tab__item--active'
   ) as HTMLElement | null
   if (activeTabEl && !isInView(activeTabEl)) {
     scrollIntoView(activeTabEl)
@@ -229,7 +229,8 @@ onMounted(() => {
     ensureActiveTabInView()
   })
   tabListResizeObserver = new ResizeObserver(() => {
-    if (!hasScroller.value) ensureActiveTabInView()
+    // 内容溢出（存在滚动条）时才需要在标签增删后纠正滚动位置。
+    if (hasScroller.value) ensureActiveTabInView()
     updateScrollState()
   })
 
@@ -238,6 +239,7 @@ onMounted(() => {
   if (tabNav) tabListResizeObserver.observe(tabNav)
 })
 onUnmounted(() => {
+  handleScrollbarDragEnd()
   scrollContainerResizeObserver?.disconnect()
   tabListResizeObserver?.disconnect()
   scrollContainerResizeObserver = null

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

@@ -42,7 +42,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"
@@ -149,6 +153,7 @@ const handleTabContextMenu = (e: MouseEvent, item: ITabItem, index: number, max:
 
 /** 原生拖放只在释放鼠标时更新顺序，避免拖动经过标签时反复变更响应式列表。 */
 const handleTabDragStart = (item: ITabItem) => {
+  if (item.pinned) return
   draggingTabId.value = item.id
 }
 
@@ -161,9 +166,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 +188,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)
 }
 

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

@@ -5,6 +5,7 @@
  * 使 useTabPanel 只负责领域状态与路由协调。
  */
 import {
+  Transition,
   cloneVNode,
   defineComponent,
   onActivated,
@@ -15,16 +16,19 @@ import {
   shallowRef
 } from 'vue'
 import type { DefineComponent, PropType, VNode } from 'vue'
-import type { ITabBase, ITabItem } from '../../model/TabModel'
+import type { ITabBase } 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
+  consumeBackParams: (tabId: string, pageId: string) => Record<string, unknown> | null
+  getComponent: (id: string) => DefineComponent | undefined
+  setComponent: (id: string, component: DefineComponent) => void
   addCache: (cacheName: string) => void
   evictMarkedCaches: () => void
+  clearTabEvictionMarks: () => void
   addPageScroller: (pageId: string, ...selectors: string[]) => void
   saveScroller: (pageId: string) => void
   restoreScroller: (pageId: string) => void
@@ -34,31 +38,70 @@ interface PageComponentFactoryOptions {
 export const createPageComponentFactory = (options: PageComponentFactoryOptions) => {
   const {
     runtimeContext,
-    getTab,
+    consumeBackParams,
+    getComponent,
+    setComponent,
     addCache,
     evictMarkedCaches,
+    clearTabEvictionMarks,
     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)
+    const existing = getComponent(cacheName)
     if (existing) {
       addCache(cacheName)
       return existing
     }
 
-    const cacheComponent = defineComponent<{ vnode?: VNode }>({
+    /**
+     * 页面壳组件：作为 Transition 的直接子节点，承接刷新时的 key 变化，
+     * 避免直接修改 router-view 页面 vnode 的 key 破坏 keep-alive 的实例复用。
+     */
+    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'],
@@ -67,21 +110,26 @@ 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，
+         * 位移会让内容短暂溢出并闪出滚动条。
+         */
+        const isTransitioning = ref(false)
+        let transitionCount = 0
+        const beginTransition = () => {
+          transitionCount++
+          isTransitioning.value = true
+        }
+        const endTransition = () => {
+          transitionCount = Math.max(0, transitionCount - 1)
+          if (transitionCount === 0) isTransitioning.value = false
+        }
 
         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
-          }
+          localBackParams.value = consumeBackParams(tabInfo.id!, cacheName)
         }
 
         onMounted(() => {
@@ -94,46 +142,68 @@ export const createPageComponentFactory = (options: PageComponentFactoryOptions)
           context.emit('onLoaded')
           restoreScroller(cacheName)
           evictMarkedCaches()
-          tabIdsToEvict.clear()
+          clearTabEvictionMarks()
           checkAndConsumeBackParams()
         })
         onUnmounted(() => removeScroller(cacheName))
 
-        // 给 .cache-page-wrapper 挂滚动阴影，确保 keep-alive 的 suspended/deactivated 生命周期下表现一致
+        // 给 .stack-tab__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
+          const refreshVersion = props.refreshVersion ?? 0
+          if (
+            vnode !== lastVnode.value ||
+            backParams !== lastBackParams.value ||
+            refreshVersion !== lastRefreshVersion.value
+          ) {
+            const cloned = 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="cache-page-wrapper"
+              class="stack-tab__cache-page-wrapper"
               id={`W-${cacheName}`}
               style={[
-                runtimeContext.useGlobalScroll.value ? 'overflow:auto' : 'overflow:hidden',
+                runtimeContext.useGlobalScroll.value && !isTransitioning.value
+                  ? 'overflow:auto'
+                  : 'overflow:hidden',
                 'height: 100%'
               ]}
             >
-              {lastCloned.value}
+              {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>
+              ) : null}
               <PageLoading tabId={tabInfo.id!} />
             </div>
           )
         }
       }
     }) as DefineComponent
-    components.set(cacheName, cacheComponent)
+    setComponent(cacheName, cacheComponent)
     addCache(cacheName)
     return cacheComponent
   }

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

@@ -4,8 +4,8 @@
  * 活动普通页面保持 cache id 稳定，只递增页面级刷新版本；非活动页面可直接替换缓存。
  */
 import type { Ref } from 'vue'
-import { triggerRef } from 'vue'
-import type { ITabItem } from '../../model/TabModel'
+import type { ITabItem, ITabPage } from '../../model/TabModel'
+import type { PagePatch, PageUpdate } from './tabStore'
 
 export interface TabPanelRefreshApi {
   refreshTab: (id: string) => void
@@ -13,9 +13,13 @@ export interface TabPanelRefreshApi {
 }
 
 export interface CreateTabPanelRefreshOptions {
-  tabs: Ref<ITabItem[]>
+  getTabs: () => readonly ITabItem[]
+  getTopPage: (tabId: string) => ITabPage | null
+  /** 修改页面字段（刷新版本 / 页面 id） */
+  updatePage: (tabId: string, pageId: string, patch: PagePatch) => boolean
+  /** 批量修改页面字段，refreshAllTabs 最后统一触发一次 tabs 更新 */
+  updatePages: (updates: readonly PageUpdate[]) => void
   iframeRefreshKeys: Ref<Record<string, number>>
-  getTab: (id: string) => ITabItem | null
   createPageId: () => string
   addCache: (cacheName: string) => void
   evictPageCache: (cacheName: string) => void
@@ -30,9 +34,11 @@ export const createTabPanelRefresh = (
   options: CreateTabPanelRefreshOptions
 ): TabPanelRefreshApi => {
   const {
-    tabs,
+    getTabs,
+    getTopPage,
+    updatePage,
+    updatePages,
     iframeRefreshKeys,
-    getTab,
     createPageId,
     addCache,
     evictPageCache,
@@ -51,31 +57,45 @@ export const createTabPanelRefresh = (
     refreshIframeByPostMessage(tab.id)
   }
 
-  const refreshPage = (tab: ITabItem, cacheNamesToEvict?: string[], cacheNamesToAdd?: string[]) => {
-    const currentPage = tab.pages.peek()
+  const refreshPage = (
+    tab: ITabItem,
+    cacheNamesToEvict?: string[],
+    cacheNamesToAdd?: string[],
+    pageUpdates?: PageUpdate[]
+  ) => {
+    const currentPage = getTopPage(tab.id)
     if (!currentPage) return
 
     if (tab.active) {
-      currentPage.refreshVersion = (currentPage.refreshVersion ?? 0) + 1
-      // 通知 activePageRefreshVersion 这类依赖 tabs.value 的计算属性重新计算
-      triggerRef(tabs)
+      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
-    currentPage.id = createPageId()
-    currentPage.refreshVersion = 0
+    const nextPageId = createPageId()
+    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(currentPage.id)
+      cacheNamesToAdd.push(nextPageId)
       return
     }
     evictPageCache(oldCacheName)
-    addCache(currentPage.id)
+    addCache(nextPageId)
   }
 
   const refreshTab = (id: string) => {
-    const tab = getTab(id)
+    const tab = getTabs().find((item) => item.id === id)
     if (!tab?.refreshable) return
     if (tab.iframe) {
       refreshIframe(tab)
@@ -87,10 +107,11 @@ export const createTabPanelRefresh = (
   const refreshAllTabs = () => {
     const cacheNamesToEvict: string[] = []
     const cacheNamesToAdd: string[] = []
+    const pageUpdates: PageUpdate[] = []
     const iframeKeysUpdate = { ...iframeRefreshKeys.value }
     let iframeKeysChanged = false
 
-    for (const tab of tabs.value) {
+    for (const tab of getTabs()) {
       if (!tab.refreshable) continue
       if (tab.iframe) {
         if (tab.iframeRefreshMode === 'reload') {
@@ -101,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)
   }