vue-stack-tabs 1.0.1 → 1.3.0

package/src/lib/hooks/useTabPanel.tsx

@@ -12,51 +12,42 @@
  * 使用范围：内部 hook，由 StackTabs、useTabActions、useTabRouter、ContextMenu 调用
  */
 import type { ITabBase, ITabData, ITabItem, ITabPage } from '../model/TabModel'
-import { defineComponent, onActivated, onDeactivated, onMounted, onUnmounted } from 'vue'
+import {
+  defineComponent,
+  onActivated,
+  onDeactivated,
+  onMounted,
+  onUnmounted,
+  computed,
+  ref,
+  shallowRef,
+  cloneVNode
+} from 'vue'
 import type { DefineComponent, VNode } from 'vue'
-import { useRouter } from 'vue-router'
+import { isNavigationFailure, useRouter } from 'vue-router'
 import type { RouteLocationNormalizedLoaded } from 'vue-router'
-import { ulid } from 'ulid'
 import { encodeTabInfo, createPageId, decodeTabInfo } from '../utils/tabInfoEncoder'
 import { defu } from 'defu'
 import { Stack } from '../model/TabModel'
-import { parseUrl, isCrossOriginUrl } from '../utils/urlParser'
+import {
+  parseUrl,
+  isCrossOriginUrl,
+  omitStackTabsReservedQuery,
+  toSafeTabUrl,
+  decodeSafeTabUrl,
+  cloneLocationQuery,
+  clonePage
+} from '../utils/urlParser'
 import PageLoading from '../components/PageLoading.vue'
 import { TabEventType, useTabEmitter } from './useTabEventBus'
+import { runNavigationTransaction } from './tabPanel/navigationTransaction'
 import { useI18n } from 'vue-i18n-lite'
 
-import {
-  tabs,
-  defaultTabs,
-  caches,
-  components,
-  tabIdsToEvict,
-  refreshKey,
-  excludedCacheIdsForRefresh,
-  iframeRefreshKeys,
-  isInitialized,
-  maxTabCount,
-  useGlobalScroll,
-  cacheIdsToEvict,
-  setMaxTabCount,
-  setUseGlobalScroll,
-  setSessionPrefix
-} from './tabPanel/state'
-import {
-  markCacheForEviction,
-  markTabPagesForEviction,
-  markTabPagesForEvictionOnly,
-  addCache,
-  removeCache,
-  evictMarkedCaches
-} from './tabPanel/evict'
-import { restoreScroller, saveScroller, removeScroller, addPageScroller } from './tabPanel/scroll'
-import {
-  saveActiveTabToSession,
-  clearSession,
-  restoreTabFromSession,
-  getSessionKey
-} from './tabPanel/session'
+import { resolveStackTabsRuntimeContext } from './stackTabsContext'
+import { createTabPanelEviction } from './tabPanel/evict'
+import { createTabPanelScroll } from './tabPanel/scroll'
+import { createTabPanelSession } from './tabPanel/session'
+import { createTabPanelRefresh } from './tabPanel/refresh'
 
 /* eslint-disable vue/one-component-per-file */
 /** 占位组件：当路由组件为空或标签已被标记删除时返回 */
@@ -67,6 +58,11 @@ const EmptyPlaceholderComponent = defineComponent({
   }
 })
 
+const cloneRouteQuery = (route: RouteLocationNormalizedLoaded, tabInfo: ITabBase) => ({
+  ...cloneLocationQuery(route.query),
+  __tab: route.query.__tab ?? encodeTabInfo(tabInfo)
+})
+
 /** 规范化路径（nginx 等可能加尾部斜杠） */
 export const normalizePathForCache = (route: RouteLocationNormalizedLoaded): string => {
   const lastMatch = route.matched[route.matched.length - 1]
@@ -79,6 +75,37 @@ export default () => {
   const router = useRouter()
   const emitter = useTabEmitter()
   const { t } = useI18n()
+  const runtimeContext = resolveStackTabsRuntimeContext()
+  const {
+    tabs,
+    defaultTabs,
+    caches,
+    components,
+    tabIdsToEvict,
+    refreshKey,
+    iframeRefreshKeys,
+    isInitialized,
+    cacheIdsToEvict
+  } = runtimeContext
+  const {
+    markCacheForEviction,
+    markTabPagesForEviction,
+    markTabPagesForEvictionOnly,
+    addCache,
+    removeCache,
+    evictMarkedCaches,
+    evictPageCache,
+    replacePageCaches
+  } = createTabPanelEviction(runtimeContext)
+  const { restoreScroller, saveScroller, removeScroller, addPageScroller } =
+    createTabPanelScroll(runtimeContext)
+  const {
+    saveActiveTabToSession,
+    clearSession,
+    restoreTabFromSession,
+    restoreActiveTabSession,
+    getSessionKey
+  } = createTabPanelSession(runtimeContext)
 
   const size = (): number => tabs.value.length
 
@@ -87,80 +114,114 @@ export default () => {
    * @param staticTabs - 初始标签配置
    */
   const initialize = (staticTabs: ITabData[]) => {
+    const newDefaults: ITabItem[] = []
+    const newTabs: ITabItem[] = []
+
     for (const item of staticTabs) {
-      const fullItem = defu(item, { id: ulid(), refreshable: true, closable: true, iframe: false })
-      const tabId = fullItem.id ?? ulid()
-      fullItem.id = tabId
-      const uri = parseUrl(fullItem.path)
-      const config = defu(fullItem, {
-        closable: true,
+      const fullItem = defu(item, {
+        id: crypto.randomUUID(),
         refreshable: true,
+        closable: true,
         iframe: false
       })
-      const cacheName = createPageId(tabId, uri.path, uri.query)
+      const tabId = fullItem.id ?? crypto.randomUUID()
+      fullItem.id = tabId
+      const uri = parseUrl(fullItem.path)
+      const cacheName = createPageId()
       const page: ITabPage = {
         id: cacheName,
         tabId,
         path: uri.path,
-        query: defu(uri.query, { __tab: encodeTabInfo(fullItem) })
+        query: defu(omitStackTabsReservedQuery(uri.query), { __tab: encodeTabInfo(fullItem) })
       }
       const pages = new Stack<ITabPage>()
       pages.push(page)
       const tab: ITabItem = {
         id: tabId,
-        title: config.title ?? '',
-        closable: config.closable,
-        refreshable: config.refreshable,
-        iframe: config.iframe,
-        iframeRefreshMode: (config as { iframeRefreshMode?: string }).iframeRefreshMode === 'reload' ? 'reload' : 'postMessage',
+        title: fullItem.title ?? '',
+        closable: fullItem.closable!,
+        refreshable: fullItem.refreshable!,
+        iframe: fullItem.iframe!,
+        iframeRefreshMode:
+          (fullItem as { iframeRefreshMode?: string }).iframeRefreshMode === 'reload'
+            ? 'reload'
+            : 'postMessage',
         active: false,
         pages
       }
 
       addCache(cacheName)
-      defaultTabs.push(tab)
-      tabs.value.push({ ...tab })
+      newDefaults.push(tab)
+      newTabs.push({ ...tab })
     }
 
+    defaultTabs.value = [...defaultTabs.value, ...newDefaults]
+    tabs.value = [...tabs.value, ...newTabs]
+
     const storedTabJson = sessionStorage.getItem(getSessionKey())
     const restoredTab = restoreTabFromSession(storedTabJson)
-    if (restoredTab && !tabs.value.some((t) => t.id === restoredTab!.id)) {
+    if (restoredTab && !tabs.value.some((t) => t.id === restoredTab.id)) {
+      if (restoredTab.url) restoredTab.url = toSafeTabUrl(restoredTab.url)
       if (restoredTab.iframe && restoredTab.url && restoredTab.iframeRefreshMode === undefined) {
-        restoredTab.iframeRefreshMode = isCrossOriginUrl(restoredTab.url)
-          ? 'reload'
-          : 'postMessage'
+        restoredTab.iframeRefreshMode = isCrossOriginUrl(restoredTab.url) ? 'reload' : 'postMessage'
       }
-      tabs.value.push(restoredTab)
+
+      if (restoredTab.pages && typeof restoredTab.pages.list === 'function') {
+        const pages = restoredTab.pages.list()
+        pages.forEach((page) => {
+          if (page && page.id) addCache(page.id)
+        })
+      }
+
+      tabs.value = [...tabs.value, restoredTab]
     }
     isInitialized.value = true
   }
 
   const hasTab = (id: string) => tabs.value.some((t) => t.id === id)
   const canAddTab = () =>
-    maxTabCount <= 0 || (maxTabCount > 0 && maxTabCount > tabs.value.length)
+    runtimeContext.maxTabCount.value <= 0 ||
+    (runtimeContext.maxTabCount.value > 0 && runtimeContext.maxTabCount.value > tabs.value.length)
 
-  const addTab = (tab: ITabItem) => {
-    tabs.value.push(tab)
-    return Promise.resolve(true)
+  const addTab = (tab: ITabItem): void => {
+    tabs.value = [...tabs.value, tab]
   }
 
   const getTab = (id: string) => tabs.value.find((t) => t.id === id) ?? null
 
-  /** 从路由解析 tabInfo，若无则创建默认并写入 query */
+  /** 从路由解析 tabInfo，若无则创建默认信息，调用方负责把编码信息写入内部 page.query */
   const parseTabInfoFromRoute = (route: RouteLocationNormalizedLoaded): ITabBase => {
-    if (route.query.__tab) return decodeTabInfo(route.query.__tab as string)
-    const tabInfo: ITabBase = {
-      id: ulid(),
+    if (typeof route.query.__tab === 'string') {
+      const tabInfo = decodeTabInfo(route.query.__tab)
+      if (tabInfo.id) return tabInfo
+    }
+
+    const path = normalizePathForCache(route)
+    const activeTab = tabs.value.find((tab) => tab.active)
+    const activePage = activeTab?.pages.peek()
+    if (activeTab && activePage?.path === path) {
+      return {
+        id: activeTab.id,
+        title: activeTab.title,
+        closable: activeTab.closable,
+        refreshable: activeTab.refreshable,
+        iframe: activeTab.iframe,
+        iframeRefreshMode: activeTab.iframeRefreshMode
+      }
+    }
+
+    return {
+      id: crypto.randomUUID(),
       title: t('VueStackTab.undefined'),
       closable: true,
       refreshable: true,
       iframe: false
     }
-    route.query.__tab = encodeTabInfo(tabInfo)
-    return tabInfo
   }
 
-  /** 查找或创建目标 tab，同步 active 并添加 page */
+  /**
+   * 查找或创建目标标签，并同步更新 active 状态与 pages 栈。
+   */
   const findOrCreateTargetTab = (
     tabInfo: ITabBase,
     route: RouteLocationNormalizedLoaded,
@@ -184,13 +245,12 @@ export default () => {
         refreshable: tabInfo.refreshable!,
         iframe: tabInfo.iframe!,
         iframeRefreshMode: tabInfo.iframeRefreshMode ?? 'postMessage',
-        url: decodeURIComponent(src as string),
+        url: decodeSafeTabUrl(src),
         active: true,
         pages
-      }
-      addTab(targetTab).then(() => {
-        emitter.emit(TabEventType.TAB_ACTIVE, { id: tabInfo.id!, isRoute: false })
-      })
+      } as unknown as ITabItem
+      addTab(targetTab)
+      emitter.emit(TabEventType.TAB_ACTIVE, { id: tabInfo.id!, isRoute: false })
     } else {
       targetTab.active = true
       if (targetTab.pages.isEmpty() || targetTab.pages.peek()!.id !== page.id) {
@@ -200,9 +260,12 @@ export default () => {
     return targetTab
   }
 
+  const createCacheName = () => {
+    return createPageId()
+  }
+
   /**
-   * 根据当前路由更新/创建标签与页面状态
-   * @returns 缓存名、标签信息、目标标签，或 empty/recovered
+   * 根据当前路由更新/创建标签与页面状态（核心路由适配器）。
    */
   const updatePageState = (
     route: RouteLocationNormalizedLoaded
@@ -214,62 +277,179 @@ export default () => {
     if (tabIdsToEvict.has(tabInfo.id!)) return { empty: true }
 
     const path = normalizePathForCache(route)
-    const cacheName = createPageId(tabInfo.id!, path, route.query.valueOf())
+
+    let targetTab: ITabItem | null = tabInfo.id ? (getTab(tabInfo.id) as ITabItem | null) : null
+    let cacheName: string
+    let page: ITabPage | null = null
+
+    if (targetTab && !targetTab.pages.isEmpty()) {
+      const top = targetTab.pages.peek()
+      if (!top) throw new Error('[vue-stack-tabs] Stack is not empty but peek() returned undefined')
+
+      if (top.path === path) {
+        cacheName = top.id
+      } else {
+        const pagesList = targetTab.pages.readonlyList()
+        let foundIndex = -1
+        for (let i = pagesList.length - 2; i >= 0; i--) {
+          const pastPage = pagesList[i]
+          if (pastPage && pastPage.path === path) {
+            foundIndex = i
+            break
+          }
+        }
+
+        if (foundIndex !== -1) {
+          if (!import.meta.env.PROD) {
+            console.warn(
+              '[vue-stack-tabs] Detected native browser back navigation, repairing page stack...'
+            )
+          }
+          const stepsToPop = pagesList.length - 1 - foundIndex
+          for (let i = 0; i < stepsToPop; i++) {
+            const popped = targetTab.pages.pop()
+            if (popped) evictPageCache(popped.id)
+          }
+          const newTop = targetTab.pages.peek()
+          cacheName = newTop ? newTop.id : createPageId()
+
+          if (!newTop) {
+            page = {
+              id: cacheName,
+              tabId: tabInfo.id!,
+              path: route.path,
+              query: cloneRouteQuery(route, tabInfo)
+            }
+          }
+        } else {
+          cacheName = createPageId()
+          page = {
+            id: cacheName,
+            tabId: tabInfo.id!,
+            path: route.path,
+            query: cloneRouteQuery(route, tabInfo)
+          }
+        }
+      }
+    } else {
+      cacheName = createPageId()
+      page = {
+        id: cacheName,
+        tabId: tabInfo.id!,
+        path: route.path,
+        query: cloneRouteQuery(route, tabInfo)
+      }
+    }
+
     if (cacheIdsToEvict.has(cacheName)) {
       cacheIdsToEvict.delete(cacheName)
       const cached = components.get(cacheName)
       if (cached) return { recovered: cached, cacheName }
     }
 
-    const page: ITabPage = {
-      id: cacheName,
-      tabId: tabInfo.id!,
-      path: route.path,
-      query: route.query as Record<string, string>
+    if (page) {
+      targetTab = findOrCreateTargetTab(tabInfo, route, cacheName, page)
+    } else {
+      for (const t of tabs.value) t.active = false
+      targetTab!.active = true
     }
-    const targetTab = findOrCreateTargetTab(tabInfo, route, cacheName, page)
-    saveActiveTabToSession(targetTab)
-    return { cacheName, tabInfo, targetTab }
+
+    saveActiveTabToSession(targetTab!)
+    return { cacheName, tabInfo, targetTab: targetTab! }
   }
 
-  const resolvePageComponent = (
-    ctx: { cacheName: string; tabInfo: ITabBase; targetTab: ITabItem },
-    component: VNode
-  ): DefineComponent => {
+  /**
+   * 获取或创建与 cacheName 对应的 cacheComponent（keep-alive 包装组件）。
+   */
+  const resolvePageComponent = (ctx: {
+    cacheName: string
+    tabInfo: ITabBase
+    targetTab: ITabItem
+  }): DefineComponent => {
     const { cacheName, tabInfo } = ctx
+
     if (components.has(cacheName)) {
       addCache(cacheName)
       return components.get(cacheName)!
     }
+
     const cacheComponent = defineComponent({
       name: cacheName,
-      components: { DynamicComponent: component },
+      props: {
+        vnode: {
+          type: Object as () => VNode,
+          required: false,
+          default: undefined
+        }
+      },
       emits: ['onLoaded'],
-      setup(_props, context) {
+      setup(props, context) {
+        const localBackParams = ref<Record<string, unknown> | null>(null)
+        const lastVnode = shallowRef<VNode | null>(null)
+        const lastCloned = shallowRef<VNode | null>(null)
+        const lastBackParams = shallowRef<Record<string, unknown> | null>(null)
+
+        const checkAndConsumeBackParams = () => {
+          try {
+            const tab = getTab(tabInfo.id!)
+            const top = tab?.pages.peek()
+            if (top && top.id === cacheName && top._backParams) {
+              localBackParams.value = { ...top._backParams }
+              delete top._backParams
+            } else {
+              localBackParams.value = null
+            }
+          } catch {
+            localBackParams.value = null
+          }
+        }
+
         onMounted(() => {
           context.emit('onLoaded')
-          addPageScroller(cacheName, '.cache-page-wrapper')
+          addPageScroller(cacheName, `#W-${cacheName}`)
+          checkAndConsumeBackParams()
         })
+
         onDeactivated(() => saveScroller(cacheName))
+
         onActivated(() => {
           context.emit('onLoaded')
           restoreScroller(cacheName)
           evictMarkedCaches()
           tabIdsToEvict.clear()
-          clearExcludedCacheIdForRefresh(cacheName)
-          component.props = null
+          checkAndConsumeBackParams()
         })
+
         onUnmounted(() => removeScroller(cacheName))
-        return () => (
-          <div
-            class="cache-page-wrapper"
-            id={'W-' + tabInfo.id}
-            style={[useGlobalScroll ? 'overflow:auto' : 'overflow:hidden']}
-          >
-            <dynamic-component tId={tabInfo.id} pId={cacheName} />
-            <PageLoading tabId={tabInfo.id!} />
-          </div>
-        )
+
+        return () => {
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          const Node = (props as any).vnode as VNode
+          const backParams = localBackParams.value
+
+          if (Node !== lastVnode.value || backParams !== lastBackParams.value) {
+            const dynamicBackProps = backParams ? { _back: backParams } : {}
+            lastCloned.value = Node
+              ? cloneVNode(Node, { tId: tabInfo.id, pId: cacheName, ...dynamicBackProps })
+              : null
+            lastVnode.value = Node
+            lastBackParams.value = backParams
+          }
+
+          return (
+            <div
+              class="cache-page-wrapper"
+              id={`W-${cacheName}`}
+              style={[
+                runtimeContext.useGlobalScroll.value ? 'overflow:auto' : 'overflow:hidden',
+                'height: 100%'
+              ]}
+            >
+              {lastCloned.value}
+              <PageLoading tabId={tabInfo.id!} />
+            </div>
+          )
+        }
       }
     }) as DefineComponent
     components.set(cacheName, cacheComponent)
@@ -277,32 +457,63 @@ export default () => {
     return cacheComponent
   }
 
-  const clearExcludedCacheIdForRefresh = (cacheId: string) => {
-    excludedCacheIdsForRefresh.value = excludedCacheIdsForRefresh.value.filter((c) => c !== cacheId)
-  }
+  /** 当前正在渲染的页面的缓存 Key（ULID），供 StackTabs.vue 的 :key 绑定使用 */
+  const activeCacheKey = ref<string>('')
+  /** 只随当前活动页面刷新变化，避免一个 Tab 刷新导致其他 Tab 的缓存 key 失效。 */
+  const activePageRefreshVersion = computed(() => {
+    const activeTab = tabs.value.find((tab) => tab.active)
+    return activeTab?.pages.peek()?.refreshVersion ?? 0
+  })
 
-  /**
-   * 将路由对应的组件注册为缓存页面，由 tabWrapper 调用
-   * @returns 包装后的缓存组件
-   */
-  const addPage = (route: RouteLocationNormalizedLoaded, component: VNode): DefineComponent => {
+  let lastRouteKey = ''
+  let lastAddPageResult: DefineComponent | null = null
+
+  const addPage = (
+    route: RouteLocationNormalizedLoaded,
+    component?: VNode | null
+  ): DefineComponent => {
     if (!component) return EmptyPlaceholderComponent as DefineComponent
 
+    const routeKey = route.fullPath + (route.query.__tab || '')
+    if (routeKey === lastRouteKey && lastAddPageResult) {
+      return lastAddPageResult
+    }
+
     const state = updatePageState(route)
     if ('empty' in state) return EmptyPlaceholderComponent as DefineComponent
     if ('recovered' in state) {
       addCache(state.cacheName)
+      activeCacheKey.value = state.cacheName
+      lastRouteKey = routeKey
+      lastAddPageResult = state.recovered
       return state.recovered
     }
-    return resolvePageComponent(state, component)
+    activeCacheKey.value = state.cacheName
+    const result = resolvePageComponent(state)
+    lastRouteKey = routeKey
+    lastAddPageResult = result
+    return result
   }
 
   const renewTab = (tab: ITabData) => {
     const currentTab = getTab(tab.id!)
-    if (!currentTab) return
+    if (!currentTab) return undefined
+
+    const pageSnapshot = currentTab.pages.list().map((p) => clonePage(p))
+    const cacheSnapshot = [...caches.value]
+    const componentSnapshot = new Map(components)
+
     markTabPagesForEvictionOnly(currentTab)
     evictMarkedCaches()
     currentTab.pages.clear()
+
+    return () => {
+      currentTab.pages.clear()
+      for (const page of pageSnapshot) currentTab.pages.push(clonePage(page))
+      caches.value = [...cacheSnapshot]
+      components.clear()
+      for (const [id, component] of componentSnapshot) components.set(id, component)
+    }
   }
 
   const removeTab = (id: string): string => {
@@ -333,16 +544,21 @@ export default () => {
     return activeTabId
   }
 
-  const removeAllTabs = () => {
+  /** 批量关闭满足条件的可关闭标签，并统一标记其页面缓存待驱逐。 */
+  const removeTabs = (shouldRemove: (tab: ITabItem, index: number) => boolean) => {
     const tabList = tabs.value
-    for (let i = tabList.length - 1; i >= 0; i--) {
-      const tab = tabList[i]
-      if (tab?.closable) {
-        markTabPagesForEviction(tab)
-        tab.pages.clear()
-        tabList.splice(i, 1)
-      }
+    for (let index = tabList.length - 1; index >= 0; index--) {
+      const tab = tabList[index]
+      if (!tab || !tab.closable || !shouldRemove(tab, index)) continue
+      markTabPagesForEviction(tab)
+      tab.pages.clear()
+      tabList.splice(index, 1)
     }
+  }
+
+  const removeAllTabs = () => {
+    const tabList = tabs.value
+    removeTabs(() => true)
     const hasActive = tabList.some((t) => t.active)
     if (hasActive) {
       evictMarkedCaches()
@@ -355,18 +571,8 @@ export default () => {
 
   const removeOtherTabs = (id: string) => {
     const tabList = tabs.value
-    let activeTab: ITabItem | undefined
-    for (let i = tabList.length - 1; i >= 0; i--) {
-      const tab = tabList[i]
-      if (!tab) continue
-      if (tab.id === id) {
-        activeTab = tab as ITabItem
-      } else if (tab.closable) {
-        markTabPagesForEviction(tab)
-        tab.pages.clear()
-        tabList.splice(i, 1)
-      }
-    }
+    const activeTab = tabList.find((tab) => tab.id === id)
+    removeTabs((tab) => tab.id !== id)
     if (activeTab && !activeTab.active) {
       emitter.emit(TabEventType.TAB_ACTIVE, { id })
     } else {
@@ -380,14 +586,7 @@ export default () => {
     const pivot = tabList.findIndex((t) => t?.id === id)
     if (pivot <= 0) return
 
-    for (let i = pivot - 1; i >= 0; i--) {
-      const tab = tabList[i]
-      if (tab?.closable) {
-        markTabPagesForEviction(tab)
-        tab.pages.clear()
-        tabList.splice(i, 1)
-      }
-    }
+    removeTabs((_, index) => index < pivot)
     if (tabList.some((t) => t.active)) {
       evictMarkedCaches()
       tabIdsToEvict.clear()
@@ -402,14 +601,7 @@ export default () => {
     const pivot = tabList.findIndex((t) => t?.id === id)
     if (pivot < 0 || pivot >= tabList.length - 1) return
 
-    for (let i = tabList.length - 1; i > pivot; i--) {
-      const tab = tabList[i]
-      if (tab?.closable) {
-        markTabPagesForEviction(tab)
-        tab.pages.clear()
-        tabList.splice(i, 1)
-      }
-    }
+    removeTabs((_, index) => index > pivot)
     if (tabList.some((t) => t.active)) {
       evictMarkedCaches()
       tabIdsToEvict.clear()
@@ -419,54 +611,16 @@ export default () => {
     if (last) emitter.emit(TabEventType.TAB_ACTIVE, { id: last.id })
   }
 
-  const refreshTab = (id: string) => {
-    const tab = getTab(id)
-    if (!tab?.refreshable) return
-
-    if (tab.iframe) {
-      if (tab.iframeRefreshMode === 'reload') {
-        iframeRefreshKeys.value = {
-          ...iframeRefreshKeys.value,
-          [id]: (iframeRefreshKeys.value[id] ?? 0) + 1
-        }
-      } else {
-        ;(emitter as { emit: (t: string, p: string) => void }).emit('REFRESH_IFRAME_POSTMESSAGE', id)
-      }
-      return
-    }
-
-    const currentPageId = tab.pages.peek()?.id
-    if (!currentPageId) return
-
-    excludedCacheIdsForRefresh.value = [...excludedCacheIdsForRefresh.value, currentPageId]
-    if (tab.active) {
-      refreshKey.value++
-    }
-  }
-
-  const refreshAllTabs = () => {
-    const toRefresh: string[] = []
-    for (const tab of tabs.value) {
-      if (!tab?.refreshable) continue
-      if (tab.iframe) {
-        if (tab.iframeRefreshMode === 'reload') {
-          iframeRefreshKeys.value = {
-            ...iframeRefreshKeys.value,
-            [tab.id]: (iframeRefreshKeys.value[tab.id] ?? 0) + 1
-          }
-        } else {
-          ;(emitter as { emit: (t: string, p: string) => void }).emit('REFRESH_IFRAME_POSTMESSAGE', tab.id)
-        }
-      } else {
-        const pageId = tab.pages.peek()?.id
-        if (pageId) toRefresh.push(pageId)
-      }
-    }
-    if (toRefresh.length > 0) {
-      excludedCacheIdsForRefresh.value = [...excludedCacheIdsForRefresh.value, ...toRefresh]
-      refreshKey.value++
-    }
-  }
+  const { refreshTab, refreshAllTabs } = createTabPanelRefresh({
+    tabs,
+    iframeRefreshKeys,
+    getTab,
+    createPageId,
+    addCache,
+    evictPageCache,
+    replacePageCaches,
+    refreshIframeByPostMessage: (id) => emitter.emit(TabEventType.REFRESH_IFRAME_POSTMESSAGE, id)
+  })
 
   const getComponent = (id: string) => components.get(id)
 
@@ -476,32 +630,71 @@ export default () => {
    * @param route - 是否执行 router.push
    */
   const active = (id: string, route = true) => {
-    emitter.emit('FORWARD')
+    emitter.emit(TabEventType.FORWARD)
     const target = getTab(id)
-    if (!target) return
-    if (target.active) return
+    if (!target) return Promise.resolve()
+    if (target.active) return Promise.resolve()
 
-    for (const tab of tabs.value) {
-      tab.active = tab.id === id
+    const top = target.pages.peek()
+    const activateTarget = () => {
+      for (const tab of tabs.value) {
+        tab.active = tab.id === id
+      }
+      saveActiveTabToSession(target as ITabItem)
+      tabs.value = tabs.value.slice()
+    }
+
+    if (!route) {
+      activateTarget()
+      return Promise.resolve()
     }
-    saveActiveTabToSession(target as ITabItem)
-    // 强制触发 tabs 响应式更新，确保 TabHeader 高亮与 iframe 进入动画 timing 正确
-    tabs.value = tabs.value.slice()
-    if (route) {
-      const top = target.pages.peek()
-      if (top) router.push({ path: top.path, query: top.query })
+    if (!top) {
+      activateTarget()
+      return Promise.resolve()
     }
+
+    const __tab = encodeTabInfo({
+      id: target.id,
+      title: target.title,
+      closable: target.closable,
+      refreshable: target.refreshable,
+      iframe: target.iframe
+    })
+    const query = defu({ __tab }, top.query || {})
+
+    return runNavigationTransaction({
+      apply: () => {
+        const prevActiveId = tabs.value.find((tab) => tab.active)?.id
+        const sessionSnapshot = window.sessionStorage.getItem(getSessionKey())
+        activateTarget()
+        return { prevActiveId, sessionSnapshot }
+      },
+      navigate: () => router.push({ path: top.path, query }),
+      rollback: (snapshot) => {
+        for (const tab of tabs.value) {
+          tab.active = tab.id === snapshot.prevActiveId
+        }
+        tabs.value = tabs.value.slice()
+        restoreActiveTabSession(snapshot.sessionSnapshot)
+      },
+      isFailureResult: isNavigationFailure,
+      rejectFailureResult: true
+    })
   }
 
   const reset = () => removeAllTabs()
 
   const destroy = () => {
-    tabs.value.length = 0
+    tabs.value = []
+    defaultTabs.value = []
     cacheIdsToEvict.clear()
     tabIdsToEvict.clear()
     iframeRefreshKeys.value = {}
-    caches.value.length = 0
+    caches.value = []
     components.clear()
+    runtimeContext.scrollPositionsByPageId.clear()
+    runtimeContext.isInitialized.value = false
+    runtimeContext.refreshKey.value = 0
     clearSession()
   }
 
@@ -509,13 +702,17 @@ export default () => {
     tabs,
     caches,
     refreshKey,
-    excludedCacheIdsForRefresh,
+    activeCacheKey,
+    activePageRefreshVersion,
     isInitialized,
-    setMaxSize: setMaxTabCount,
+    setMaxSize: (value: number) => {
+      runtimeContext.maxTabCount.value = value
+    },
     canAddTab,
     initialize,
     size,
     active,
+    getCacheName: createCacheName,
     destroy,
     reset,
     addCache,
@@ -535,12 +732,17 @@ export default () => {
     removeComponent: (id: string) => components.delete(id),
     markCacheForEviction,
     evictMarkedCaches,
+    evictPageCache,
     refreshTab,
     refreshAllTabs,
     iframeRefreshKeys,
     addPageScroller,
-    setGlobalScroll: setUseGlobalScroll,
+    setGlobalScroll: (value: boolean) => {
+      runtimeContext.useGlobalScroll.value = value
+    },
     clearSession,
-    setSessionPrefix
+    setSessionPrefix: (value: string) => {
+      runtimeContext.sessionPrefix.value = value
+    }
   }
 }