vue-stack-tabs 1.0.1 → 1.3.0

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

@@ -8,6 +8,8 @@
     v-if="isScrollButtonVisible"
     icon-class="stack-tab__icon-left-arrow"
     :disabled="isDisabledLeftButton"
+    :title="t('VueStackTab.scrollLeft')"
+    :aria-label="t('VueStackTab.scrollLeft')"
     @click="!isDisabledLeftButton && handleScrollButtonClick(-1 * space)"
   />
   <div ref="headerScroll" class="stack-tab__scroll" @wheel.passive="handleWheelScroll">
@@ -45,19 +47,23 @@
     v-if="isScrollButtonVisible"
     icon-class="stack-tab__icon-right-arrow"
     :disabled="isDisabledRightButton"
+    :title="t('VueStackTab.scrollRight')"
+    :aria-label="t('VueStackTab.scrollRight')"
     @click="!isDisabledRightButton && handleScrollButtonClick(space!)"
   />
 </template>
 
 <script lang="ts" setup>
+import { useI18n } from 'vue-i18n-lite'
 import { computed, ref, reactive, onMounted, watch, onUnmounted } from 'vue'
-import { ResizeObserver } from '@juggle/resize-observer'
-import type { ScrollData, DragData } from '@/lib/model/TabModel'
+import type { ScrollData, DragData } from '../../model/TabModel'
 import {
   scrollTo as scrollToUtil,
   scrollIntoView as scrollIntoViewUtil
-} from '@/lib/utils/scrollUtils'
-import TabHeaderButton from '@/lib/components/TabHeader/TabHeaderButton.vue'
+} from '../../utils/scrollUtils'
+import TabHeaderButton from './TabHeaderButton.vue'
+
+const { t } = useI18n()
 
 /** 标签列表滚动容器 */
 const container = ref<HTMLElement | null>(null)
@@ -71,8 +77,8 @@ const scrollDragging = ref<boolean>(false)
 const isDisabledLeftButton = ref<boolean>(false)
 /** 右箭头是否禁用（已到最右） */
 const isDisabledRightButton = ref<boolean>(false)
-/** 是否有横向滚动条（内容超出时显示左右箭头） */
-const isScrollButtonVisible = ref<boolean>(true)
+/** 是否显示左右滚动按钮：必须启用按钮模式且内容横向溢出 */
+const isScrollButtonVisible = ref<boolean>(false)
 /** 外层滚动区域，用于 ResizeObserver */
 const headerScroll = ref<HTMLElement>()
 const props = withDefaults(
@@ -109,12 +115,18 @@ watch(scrollData, (data) => {
   updateScrollButtonState(data)
 })
 
-/** 根据滚动位置更新左右箭头禁用状态及滚动条可见性 */
+watch(
+  () => props.isScrollButton,
+  () => updateScrollButtonState(scrollData)
+)
+
+/** 根据滚动位置更新左右箭头禁用状态及滚动按钮可见性 */
 const updateScrollButtonState = (data: ScrollData) => {
+  const hasHorizontalOverflow = data.scrollWidth > data.clientWidth
+
   isDisabledLeftButton.value = data.scrollLeft <= 10
-  isDisabledRightButton.value =
-    data.clientWidth + data.scrollLeft - data.scrollWidth >= -10
-  isScrollButtonVisible.value = data.scrollWidth !== data.clientWidth
+  isDisabledRightButton.value = data.clientWidth + data.scrollLeft - data.scrollWidth >= -10
+  isScrollButtonVisible.value = props.isScrollButton && hasHorizontalOverflow
 }
 
 /** 内容是否超出容器宽度，需要显示滚动条 */
@@ -148,21 +160,16 @@ const updateScrollState = () => {
 
 /** 确保激活的标签在可视区域内 */
 const ensureActiveTabInView = () => {
-  const activeTabEl = container.value?.querySelector('.stack-tab__item.is-active') as HTMLElement | null
+  const activeTabEl = container.value?.querySelector(
+    '.stack-tab__item.is-active'
+  ) as HTMLElement | null
   if (activeTabEl && !isInView(activeTabEl)) {
     scrollIntoView(activeTabEl)
   }
 }
 
-const scrollContainerResizeObserver = new ResizeObserver(() => {
-  updateScrollState()
-  ensureActiveTabInView()
-})
-
-const tabListResizeObserver = new ResizeObserver(() => {
-  if (!hasScroller.value) ensureActiveTabInView()
-  updateScrollState()
-})
+let scrollContainerResizeObserver: ResizeObserver | null = null
+let tabListResizeObserver: ResizeObserver | null = null
 /** 滚动到指定 left 位置 */
 const scrollTo = (left: number, smooth = true) => {
   scrollToUtil({ wrap: container.value, left, top: 0, smooth })
@@ -173,8 +180,10 @@ const handleScrollButtonClick = (delta: number) => {
 }
 
 const handleWheelScroll = (e: WheelEvent) => {
+  if (!props.isScrollWheel || !container.value) return
+
   const isScrollUp = e.deltaY < 0
-  scrollTo(container.value!.scrollLeft + (isScrollUp ? -props.space : props.space))
+  scrollTo(container.value.scrollLeft + (isScrollUp ? -props.space : props.space))
 }
 
 const handleScrollbarDragStart = (e: MouseEvent) => {
@@ -213,13 +222,26 @@ const handleScrollbarDragEnd = () => {
 }
 
 onMounted(() => {
-  scrollContainerResizeObserver.observe(headerScroll.value as Element)
+  if (typeof ResizeObserver === 'undefined') return
+
+  scrollContainerResizeObserver = new ResizeObserver(() => {
+    updateScrollState()
+    ensureActiveTabInView()
+  })
+  tabListResizeObserver = new ResizeObserver(() => {
+    if (!hasScroller.value) ensureActiveTabInView()
+    updateScrollState()
+  })
+
+  if (headerScroll.value) scrollContainerResizeObserver.observe(headerScroll.value)
   const tabNav = container.value?.querySelector('.stack-tab__nav')
-  tabListResizeObserver.observe(tabNav!)
+  if (tabNav) tabListResizeObserver.observe(tabNav)
 })
 onUnmounted(() => {
-  scrollContainerResizeObserver.disconnect()
-  tabListResizeObserver.disconnect()
+  scrollContainerResizeObserver?.disconnect()
+  tabListResizeObserver?.disconnect()
+  scrollContainerResizeObserver = null
+  tabListResizeObserver = null
 })
 
 const scrollIntoView = (el: HTMLElement) => {

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

@@ -1,5 +1,5 @@
 <template>
-  <div class="stack-tab__header">
+  <div ref="headerRef" class="stack-tab__header">
     <slot name="leftButton" />
     <tab-header-scroll
       ref="scrollContainerRef"
@@ -12,16 +12,19 @@
           key="tab-list-transition"
           tag="ul"
           class="stack-tab__nav"
+          role="tablist"
+          aria-orientation="horizontal"
           v-bind="tabTransitionProps"
           appear
+          @keydown="handleTabListKeydown"
         >
           <tab-header-item
             v-for="(item, index) in tabs"
             :key="item.id"
-            :contextmenu="contextmenu"
             :item="item as ITabItem"
-            @contextmenu.prevent="
-              (e: MouseEvent) => showContextMenu(e, item as unknown as ITabItem, index, tabs.length)
+            @contextmenu="
+              (e: MouseEvent) =>
+                handleTabContextMenu(e, item as unknown as ITabItem, index, tabs.length)
             "
             @click.middle.prevent="handleCloseTab(item as ITabItem)"
             @close="handleCloseTab"
@@ -33,7 +36,8 @@
     <slot name="rightButton" />
     <tab-header-button
       :icon-class="maximum ? 'stack-tab__icon-restore' : 'stack-tab__icon-fullscreen'"
-      :title="t('VueStackTab.maximum')"
+      :title="maximum ? t('VueStackTab.restore') : t('VueStackTab.maximum')"
+      :aria-label="maximum ? t('VueStackTab.restore') : t('VueStackTab.maximum')"
       @click="maximum = !maximum"
     />
     <transition name="stack-tab-zoom" appear>
@@ -45,6 +49,8 @@
         :tab-item="contextMenuData.item as ITabItem"
         :max="contextMenuData.max"
         :index="contextMenuData.index"
+        :context-menu="normalizedContextMenu"
+        :restore-focus-element="contextMenuTriggerElement"
         @close="handleCloseContextMenu"
       />
     </transition>
@@ -61,7 +67,7 @@
 import { inject, computed, ref, nextTick } from 'vue'
 import type { TransitionProps } from 'vue'
 import { TabScrollMode } from '../../model/TabModel'
-import type { ITabItem } from '../../model/TabModel'
+import type { IContextMenu, ITabItem } from '../../model/TabModel'
 import ContextMenu from '../ContextMenu/index.vue'
 import useContextMenu from '../../hooks/useContextMenu'
 import useTabActions from '../../hooks/useTabActions'
@@ -69,13 +75,16 @@ import TabHeaderItem from './TabHeaderItem.vue'
 import TabHeaderScroll from './TabHeaderScroll.vue'
 import TabHeaderButton from './TabHeaderButton.vue'
 import { useI18n } from 'vue-i18n-lite'
+import { maximumKey } from '../../hooks/stackTabsContext'
 const { t } = useI18n()
 /** 是否最大化，由上层 provide */
-const maximum = inject<boolean>('maximum')
+const maximum = inject(maximumKey, ref(false))
 const emit = defineEmits(['active'])
 /** 滚动容器 ref，用于调用 scrollIntoView / isInView */
 const scrollContainerRef = ref<InstanceType<typeof TabHeaderScroll>>()
+const headerRef = ref<HTMLElement>()
 const { shown: contextMenuShown, contextMenuData, showContextMenu } = useContextMenu()
+const contextMenuTriggerElement = ref<HTMLElement | null>(null)
 /** 关闭右键菜单 */
 const handleCloseContextMenu = () => {
   contextMenuShown.value = false
@@ -102,6 +111,32 @@ const props = withDefaults(
 )
 const { closeTab, activeTab, tabs } = useTabActions()
 
+/** 右键菜单是否启用；仅 false 明确禁用，其余旧对象值保持启用以兼容历史写法 */
+const isContextMenuEnabled = computed<boolean>(() => props.contextmenu !== false)
+
+/** 自定义菜单数组；非数组对象按历史宽类型兼容为默认菜单，不抛错 */
+const normalizedContextMenu = computed<IContextMenu[]>(() => {
+  return Array.isArray(props.contextmenu) ? props.contextmenu : []
+})
+
+/** 右键标签：禁用时不阻止浏览器默认菜单，启用时打开组件菜单 */
+const getContextMenuFocusElement = (event: MouseEvent): HTMLElement | null => {
+  const eventTarget = event.target instanceof Element ? event.target : null
+  const targetTab = eventTarget?.closest<HTMLElement>('[role="tab"]')
+  if (targetTab) return targetTab
+
+  const currentTarget = event.currentTarget instanceof HTMLElement ? event.currentTarget : null
+  return currentTarget?.querySelector<HTMLElement>('[role="tab"]') ?? null
+}
+
+const handleTabContextMenu = (e: MouseEvent, item: ITabItem, index: number, max: number) => {
+  if (!isContextMenuEnabled.value) return
+
+  e.preventDefault()
+  contextMenuTriggerElement.value = getContextMenuFocusElement(e)
+  showContextMenu(e, item, index, max)
+}
+
 /** 标签列表 transition 的 props，支持 string 或对象 */
 const tabTransitionProps = computed<TransitionProps>(() =>
   typeof props.tabTransition === 'string'
@@ -109,13 +144,68 @@ const tabTransitionProps = computed<TransitionProps>(() =>
     : (props.tabTransition as TransitionProps)
 )
 
+const getActiveTabIndex = (): number => tabs.value.findIndex((tab) => tab.active)
+
+const focusTabById = (tabId: string) => {
+  nextTick(() => {
+    const activeTabElement = headerRef.value?.querySelector<HTMLElement>(
+      `.stack-tab__nav [role="tab"][data-tab-id="${CSS.escape(tabId)}"]`
+    )
+    if (!activeTabElement) return
+
+    activeTabElement.focus()
+    if (scrollContainerRef.value && !scrollContainerRef.value.isInView(activeTabElement)) {
+      scrollContainerRef.value.scrollIntoView(activeTabElement)
+    }
+  })
+}
+
+const activateTabByIndex = (index: number) => {
+  const item = tabs.value[index]
+  if (!item) return
+  handleActivateTab(item as ITabItem, undefined, true)
+  focusTabById(String(item.id))
+}
+
+const handleTabListKeydown = (event: KeyboardEvent) => {
+  const count = tabs.value.length
+  if (count <= 0) return
+
+  const currentIndex = getActiveTabIndex()
+  const safeIndex = currentIndex >= 0 ? currentIndex : 0
+
+  if (event.key === 'ArrowRight') {
+    event.preventDefault()
+    activateTabByIndex((safeIndex + 1) % count)
+    return
+  }
+
+  if (event.key === 'ArrowLeft') {
+    event.preventDefault()
+    activateTabByIndex((safeIndex - 1 + count) % count)
+    return
+  }
+
+  if (event.key === 'Home') {
+    event.preventDefault()
+    activateTabByIndex(0)
+    return
+  }
+
+  if (event.key === 'End') {
+    event.preventDefault()
+    activateTabByIndex(count - 1)
+  }
+}
+
 /** 是否显示左右滚动按钮 */
 const isScrollButton = computed<boolean>(() => {
   return props.tabScrollMode === TabScrollMode.BOTH || props.tabScrollMode === TabScrollMode.BUTTON
 })
 /** 是否支持滚轮滚动 */
-const isScrollWheel =
-  props.tabScrollMode === TabScrollMode.BOTH || props.tabScrollMode === TabScrollMode.WHEEL
+const isScrollWheel = computed<boolean>(() => {
+  return props.tabScrollMode === TabScrollMode.BOTH || props.tabScrollMode === TabScrollMode.WHEEL
+})
 
 /** 关闭指定标签，并关闭右键菜单 */
 const handleCloseTab = (item: ITabItem) => {
@@ -126,7 +216,11 @@ const handleCloseTab = (item: ITabItem) => {
 }
 
 /** 激活指定标签，滚动到可视区域，并触发路由跳转 */
-const handleActivateTab = (item: ITabItem, clickedTabElement: HTMLElement | undefined, isRoute: boolean) => {
+const handleActivateTab = (
+  item: ITabItem,
+  clickedTabElement: HTMLElement | undefined,
+  isRoute: boolean
+) => {
   if (scrollContainerRef.value && clickedTabElement) {
     nextTick(() => {
       if (!scrollContainerRef.value!.isInView(clickedTabElement)) {
@@ -134,8 +228,11 @@ const handleActivateTab = (item: ITabItem, clickedTabElement: HTMLElement | unde
       }
     })
   }
-  activeTab(item.id, isRoute)
-  emit('active', item.id)
+  Promise.resolve(activeTab(item.id, isRoute))
+    .then(() => emit('active', item.id))
+    .catch((error: unknown) => {
+      console.warn('[vue-stack-tabs] Failed to activate tab:', error)
+    })
 }
 </script>
 

package/src/lib/hooks/stackTabsContext.ts

@@ -0,0 +1,135 @@
+/**
+ * VueStackTabs 全局运行时上下文管理。
+ *
+ * 负责创建、注册、解析全局唯一的 StackTabsRuntimeContext，
+ * 支持通过 Vue provide/inject 或模块级单例两种方式访问。
+ * 每个 Vue app 只允许注册一个 <VueStackTabs> 实例。
+ */
+import type { App, DefineComponent, InjectionKey, Ref, ShallowRef } from 'vue'
+import { hasInjectionContext, inject, ref } from 'vue'
+import type { Emitter } from 'mitt'
+import mitt from 'mitt'
+import type { ITabItem } from '../model/TabModel'
+import type { TabEventPayloadMap } from './useTabEventBus'
+import { createTabPanelRuntimeState } from './tabPanel/state'
+import type { ScrollPosition } from './tabPanel/state'
+
+export const STACK_TABS_CONTEXT_UNAVAILABLE_MESSAGE =
+  'VueStackTabs runtime context is not available. Render <VueStackTabs> before using vue-stack-tabs composables.'
+
+export const STACK_TABS_DUPLICATE_INSTANCE_MESSAGE =
+  'VueStackTabs only supports one <VueStackTabs> instance per Vue app.'
+
+export interface StackTabsRuntimeContext {
+  tabs: Ref<ITabItem[]>
+  defaultTabs: Ref<ITabItem[]>
+  caches: ShallowRef<string[]>
+  components: Map<string, DefineComponent>
+  cacheIdsToEvict: Set<string>
+  tabIdsToEvict: Set<string>
+  refreshKey: Ref<number>
+  scrollPositionsByPageId: Map<string, Map<string, ScrollPosition>>
+  isInitialized: Ref<boolean>
+  iframeRefreshKeys: Ref<Record<string, number>>
+  maxTabCount: Ref<number>
+  useGlobalScroll: Ref<boolean>
+  sessionPrefix: Ref<string>
+  iframePath: Ref<string>
+  eventBus: Emitter<TabEventPayloadMap>
+}
+
+export interface CreateStackTabsRuntimeContextOptions {
+  iframePath?: string
+  maxTabCount?: number
+  useGlobalScroll?: boolean
+  sessionPrefix?: string
+}
+
+export interface RegisterStackTabsRuntimeContextOptions {
+  app?: App
+  isProduction?: boolean
+}
+
+export interface UnregisterStackTabsRuntimeContextOptions {
+  app?: App
+}
+
+export const stackTabsContextKey: InjectionKey<StackTabsRuntimeContext> = Symbol('stackTabsContext')
+export const maximumKey: InjectionKey<Ref<boolean>> = Symbol('stackTabsMaximum')
+
+let activeRuntimeContext: StackTabsRuntimeContext | null = null
+let isFallbackRuntimeContextOwnerRegistered = false
+const runtimeContextOwnersByApp = new WeakSet<App>()
+
+/** 创建一个新的运行时上下文实例 */
+export const createStackTabsRuntimeContext = (
+  options: CreateStackTabsRuntimeContextOptions = {}
+): StackTabsRuntimeContext => {
+  const state = createTabPanelRuntimeState()
+
+  return {
+    ...state,
+    maxTabCount: ref(options.maxTabCount ?? state.maxTabCount.value),
+    useGlobalScroll: ref(options.useGlobalScroll ?? state.useGlobalScroll.value),
+    sessionPrefix: ref(options.sessionPrefix ?? state.sessionPrefix.value),
+    iframePath: ref(options.iframePath ?? ''),
+    eventBus: mitt<TabEventPayloadMap>()
+  }
+}
+
+/** 获取当前活跃的运行时上下文（模块级单例） */
+export const getActiveStackTabsRuntimeContext = (): StackTabsRuntimeContext | null =>
+  activeRuntimeContext
+
+/** 注册运行时上下文，重复注册会在开发环境抛出错误 */
+export const registerStackTabsRuntimeContext = (
+  context: StackTabsRuntimeContext,
+  options: RegisterStackTabsRuntimeContextOptions = {}
+): boolean => {
+  if (!activeRuntimeContext) {
+    activeRuntimeContext = context
+  }
+
+  if (options.app && !runtimeContextOwnersByApp.has(options.app)) {
+    runtimeContextOwnersByApp.add(options.app)
+    return true
+  }
+
+  if (
+    !options.app &&
+    activeRuntimeContext === context &&
+    !isFallbackRuntimeContextOwnerRegistered
+  ) {
+    isFallbackRuntimeContextOwnerRegistered = true
+    return true
+  }
+
+  const isProduction = options.isProduction ?? import.meta.env.PROD
+  if (isProduction) {
+    console.warn(STACK_TABS_DUPLICATE_INSTANCE_MESSAGE)
+    return false
+  }
+
+  throw new Error(STACK_TABS_DUPLICATE_INSTANCE_MESSAGE)
+}
+
+/** 注销运行时上下文，组件卸载时调用 */
+export const unregisterStackTabsRuntimeContext = (
+  context: StackTabsRuntimeContext,
+  options: UnregisterStackTabsRuntimeContextOptions = {}
+): void => {
+  if (options.app) runtimeContextOwnersByApp.delete(options.app)
+  if (!options.app && activeRuntimeContext === context)
+    isFallbackRuntimeContextOwnerRegistered = false
+  if (activeRuntimeContext === context) activeRuntimeContext = null
+}
+
+/** 解析当前可用的运行时上下文，优先使用 inject，回退到模块单例 */
+export const resolveStackTabsRuntimeContext = (): StackTabsRuntimeContext => {
+  const injected = hasInjectionContext() ? inject(stackTabsContextKey, null) : null
+  const context = injected ?? activeRuntimeContext
+
+  if (!context) throw new Error(STACK_TABS_CONTEXT_UNAVAILABLE_MESSAGE)
+
+  return context
+}

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

@@ -1,57 +1,139 @@
 /**
  * tabPanel/evict - 缓存驱逐逻辑
  *
- * 职责：标记待驱逐缓存、执行驱逐、维护 caches/components
+ * 职责：基于当前 StackTabsRuntimeContext 标记待驱逐缓存、执行驱逐、维护 caches / components。
  */
 import type { ITabPage } from '../../model/TabModel'
-import {
-  caches,
-  components,
-  cacheIdsToEvict,
-  tabIdsToEvict
-} from './state'
-
-/** 标记缓存为待驱逐 */
-export const markCacheForEviction = (cacheName: string) => {
-  cacheIdsToEvict.add(cacheName)
-}
+import { triggerRef } from 'vue'
+import type { StackTabsRuntimeContext } from '../stackTabsContext'
 
-/** 标记标签下所有页面为可驱逐，并标记该标签（关闭场景） */
-export const markTabPagesForEviction = (tab: { id: string; pages: { list(): ITabPage[] } }) => {
-  for (const page of tab.pages.list()) markCacheForEviction(page.id)
-  tabIdsToEvict.add(tab.id)
+export interface TabPanelEvictionApi {
+  markCacheForEviction: (cacheName: string) => void
+  markTabPagesForEviction: (tab: { id: string; pages: { list(): ITabPage[] } }) => void
+  markTabPagesForEvictionOnly: (tab: { pages: { list(): ITabPage[] } }) => void
+  addCache: (cacheName: string) => void
+  removeCache: (cacheName: string) => void
+  evictPageCache: (cacheName: string) => void
+  replacePageCaches: (
+    cacheNamesToEvict: Iterable<string>,
+    cacheNamesToAdd: Iterable<string>
+  ) => void
+  evictMarkedCaches: () => void
 }
 
-/** 仅标记标签下所有页面为可驱逐（续签场景） */
-export const markTabPagesForEvictionOnly = (tab: { pages: { list(): ITabPage[] } }) => {
-  for (const page of tab.pages.list()) markCacheForEviction(page.id)
-}
+export const createTabPanelEviction = (context: StackTabsRuntimeContext): TabPanelEvictionApi => {
+  const { caches, components, cacheIdsToEvict, tabIdsToEvict } = context
 
-/** 将缓存 id 加入 caches */
-export const addCache = (cacheName: string) => {
-  if (!caches.value.includes(cacheName)) caches.value.push(cacheName)
-}
+  const cacheSet = new Set<string>(caches.value)
+  let cacheList = caches.value
 
-/** 从 caches 中移除指定 id */
-export const removeCache = (cacheName: string) => {
-  const i = caches.value.indexOf(cacheName)
-  if (i >= 0) caches.value.splice(i, 1)
-}
+  /** 外部重置 caches（例如 destroy）后，同步内部 Set，避免后续 addCache 被错误跳过。 */
+  const syncCacheSet = () => {
+    if (cacheList === caches.value) return
+    cacheList = caches.value
+    cacheSet.clear()
+    for (const cacheName of cacheList) cacheSet.add(cacheName)
+  }
 
-/** 立即驱逐单个页面缓存 */
-export const evictPageCache = (cacheName: string) => {
-  if (!cacheName) return
-  cacheIdsToEvict.delete(cacheName)
-  removeCache(cacheName)
-  components.delete(cacheName)
-}
+  const markCacheForEviction = (cacheName: string): void => {
+    cacheIdsToEvict.add(cacheName)
+  }
+
+  const markTabPagesForEviction = (tab: { id: string; pages: { list(): ITabPage[] } }): void => {
+    for (const page of tab.pages.list()) 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 addCache = (cacheName: string): void => {
+    syncCacheSet()
+    if (!cacheSet.has(cacheName)) {
+      cacheSet.add(cacheName)
+      cacheList.push(cacheName)
+      triggerRef(caches)
+    }
+  }
+
+  const removeCache = (cacheName: string): void => {
+    syncCacheSet()
+    if (cacheSet.has(cacheName)) {
+      cacheSet.delete(cacheName)
+      const index = cacheList.indexOf(cacheName)
+      if (index >= 0) cacheList.splice(index, 1)
+      triggerRef(caches)
+    }
+  }
+
+  const evictPageCache = (cacheName: string): void => {
+    if (!cacheName) return
+    cacheIdsToEvict.delete(cacheName)
+    removeCache(cacheName)
+    components.delete(cacheName)
+  }
 
-/** 执行所有待驱逐缓存的驱逐 */
-export const evictMarkedCaches = () => {
-  if (cacheIdsToEvict.size > 0) {
-    for (const cacheName of [...cacheIdsToEvict]) {
-      evictPageCache(cacheName)
+  /** 批量替换缓存 id，仅在所有变更完成后通知一次，供刷新全部等操作使用。 */
+  const replacePageCaches = (
+    cacheNamesToEvict: Iterable<string>,
+    cacheNamesToAdd: Iterable<string>
+  ): void => {
+    syncCacheSet()
+    const toEvict = new Set(cacheNamesToEvict)
+    let changed = false
+
+    if (toEvict.size > 0) {
+      for (let index = cacheList.length - 1; index >= 0; index--) {
+        const cacheName = cacheList[index]
+        if (cacheName && toEvict.has(cacheName)) {
+          cacheList.splice(index, 1)
+          changed = true
+        }
+      }
+      for (const cacheName of toEvict) {
+        cacheSet.delete(cacheName)
+        cacheIdsToEvict.delete(cacheName)
+        components.delete(cacheName)
+      }
+    }
+
+    for (const cacheName of cacheNamesToAdd) {
+      if (!cacheSet.has(cacheName)) {
+        cacheSet.add(cacheName)
+        cacheList.push(cacheName)
+        changed = true
+      }
     }
+
+    if (changed) triggerRef(caches)
+  }
+
+  const evictMarkedCaches = (): void => {
+    if (cacheIdsToEvict.size <= 0) return
+
+    syncCacheSet()
+    const toEvict = new Set(cacheIdsToEvict)
+    for (let index = cacheList.length - 1; index >= 0; index--) {
+      const cacheName = cacheList[index]
+      if (cacheName && toEvict.has(cacheName)) cacheList.splice(index, 1)
+    }
+    for (const cacheName of toEvict) {
+      cacheSet.delete(cacheName)
+      components.delete(cacheName)
+    }
+    triggerRef(caches)
     cacheIdsToEvict.clear()
   }
+
+  return {
+    markCacheForEviction,
+    markTabPagesForEviction,
+    markTabPagesForEvictionOnly,
+    addCache,
+    removeCache,
+    evictPageCache,
+    replacePageCaches,
+    evictMarkedCaches
+  }
 }