vue-stack-tabs 1.1.0 → 1.3.1

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,104 +1,139 @@
 /**
  * tabPanel/evict - 缓存驱逐逻辑
  *
- * 职责：标记待驱逐缓存、执行驱逐、维护 caches / components
- *
- * 驱逐机制分两种：
- *
- * 1. 「标记 + 延迟驱逐」—— 用于关闭标签、刷新标签等场景
- *    调用 markCacheForEviction 将 cacheName 放入 cacheIdsToEvict 集合，
- *    等到目标页面的 cacheComponent 触发 onActivated 时，
- *    再批量调用 evictMarkedCaches 真正执行驱逐。
- *    该策略确保只有切换到新的活动页后才清理旧缓存，避免渲染空白。
- *
- * 2. 「立即驱逐」—— 用于 backward 内部退栈场景
- *    调用 evictPageCache 直接同步清除单个缓存，
- *    但必须在 router.push().then() 回调内调用（即导航完成后），
- *    否则会触发以旧路由为基础的响应式重渲染，导致刚驱逐的组件被重建。
- *    详见 useTabRouter.ts backward 函数的时序说明。
+ * 职责：基于当前 StackTabsRuntimeContext 标记待驱逐缓存、执行驱逐、维护 caches / components。
  */
 import type { ITabPage } from '../../model/TabModel'
-import { caches, components, cacheIdsToEvict, tabIdsToEvict } from './state'
+import { triggerRef } from 'vue'
+import type { StackTabsRuntimeContext } from '../stackTabsContext'
 
-/**
- * 将指定 cacheName 放入待驱逐集合。
- * 不立即清除，等叫到 evictMarkedCaches 时统一处理。
- */
-export const markCacheForEviction = (cacheName: string) => {
-  cacheIdsToEvict.add(cacheName)
+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
 }
 
-/**
- * 标记某个标签下所有页面为待驱逐，并标记该标签本身（用于「关闭标签」场景）。
- * tabIdsToEvict 中的标签 ID 会在 updatePageState 中被检测到，
- * 阻止被关闭的标签重新路由时意外复活。
- */
-export const markTabPagesForEviction = (tab: { id: string; pages: { list(): ITabPage[] } }) => {
-  for (const page of tab.pages.list()) markCacheForEviction(page.id)
-  tabIdsToEvict.add(tab.id)
-}
+export const createTabPanelEviction = (context: StackTabsRuntimeContext): TabPanelEvictionApi => {
+  const { caches, components, cacheIdsToEvict, tabIdsToEvict } = context
 
-/**
- * 仅标记标签下所有页面为待驱逐，不标记标签本身（用于「续签/换页」场景）。
- * 适用于刷新标签：旧页面缓存清零，标签本身仍然存活，
- * 导航后由 updatePageState 重新创建页面。
- */
-export const markTabPagesForEvictionOnly = (tab: { pages: { list(): ITabPage[] } }) => {
-  for (const page of tab.pages.list()) markCacheForEviction(page.id)
-}
+  const cacheSet = new Set<string>(caches.value)
+  let cacheList = caches.value
 
-/**
- * 将 cacheName 加入 <keep-alive> 的 include 列表（caches）。
- * 幂等：已存在时不重复添加，避免 include 数组中出现重复项
- * 影响 <keep-alive> 缓存范围，决定哪些 cacheComponent 实例会被保留。
- */
-export const addCache = (cacheName: string) => {
-  if (!caches.value.includes(cacheName)) caches.value.push(cacheName)
-}
+  /** 外部重置 caches（例如 destroy）后，同步内部 Set，避免后续 addCache 被错误跳过。 */
+  const syncCacheSet = () => {
+    if (cacheList === caches.value) return
+    cacheList = caches.value
+    cacheSet.clear()
+    for (const cacheName of cacheList) cacheSet.add(cacheName)
+  }
 
-/**
- * 将 cacheName 从 include 列表（caches）中移除。
- * Vue 的 <keep-alive> 会以 flush:'post' 的 watcher 检测 include 变更，
- * 在下次渲染后自动销毁不再被 include 的缓存实例。
- */
-export const removeCache = (cacheName: string) => {
-  const i = caches.value.indexOf(cacheName)
-  if (i >= 0) caches.value.splice(i, 1)
-}
+  const markCacheForEviction = (cacheName: string): void => {
+    cacheIdsToEvict.add(cacheName)
+  }
 
-/**
- * 立即、同步、彻底驱逐单个页面的缓存。
- *
- * 操作步骤：
- * 1. 从 cacheIdsToEvict 移除（若存在，防止后续 evictMarkedCaches 二次处理）
- * 2. removeCache(cacheName)   → 从 <keep-alive> include 列表删除，触发 Vue 销毁缓存组件实例
- * 3. components.delete(...)   → 从 components Map 删除组件定义，
- *    使 resolvePageComponent 下次进入时必须重新创建全新的 cacheComponent 实例
- *
- * ⚠️ 调用时机要求：
- * 必须在 router.push() 完成（.then()）之后调用，
- * 不能在导航前调用，否则驱逐触发的响应式更新会导致 StackTabs 以旧路由重渲染，
- * 进而重建刚被删除的组件（竞态）。详见 useTabRouter.ts backward 的注释。
- */
-export const evictPageCache = (cacheName: string) => {
-  if (!cacheName) return
-  cacheIdsToEvict.delete(cacheName)
-  removeCache(cacheName)
-  components.delete(cacheName)
-}
+  const markTabPagesForEviction = (tab: { id: string; pages: { list(): ITabPage[] } }): void => {
+    for (const page of tab.pages.list()) markCacheForEviction(page.id)
+    tabIdsToEvict.add(tab.id)
+  }
 
-/**
- * 执行所有已标记缓存的批量驱逐（由 cacheComponent 的 onActivated 调用）。
- *
- * 调用时机：
- * 当 cacheComponent 切换到激活（activated）状态时，说明用户切换到了一个新页面，
- * 相关的旧页面已经稳定进入「不活跃/待驱逐」状态，此时批量清理是安全的。
- */
-export const evictMarkedCaches = () => {
-  if (cacheIdsToEvict.size > 0) {
-    for (const cacheName of [...cacheIdsToEvict]) {
-      evictPageCache(cacheName)
+  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)
+  }
+
+  /** 批量替换缓存 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
+  }
 }

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

@@ -0,0 +1,61 @@
+/**
+ * 导航事务管理器。
+ *
+ * 将「乐观 UI 更新 → 路由导航 → 确认/回滚」包装为原子事务：
+ * 1. apply()  — 先对 UI 状态做乐观修改，返回快照
+ * 2. navigate() — 执行 router.push 等异步导航
+ * 3. 成功 → commit()；失败/异常 → rollback(snapshot) 恢复快照
+ *
+ * 当连续快速操作导致事务过期时（isCurrent 返回 false），
+ * 不回滚而是调用 cleanupStale() 清理残留状态，避免覆盖新事务的结果。
+ */
+interface NavigationTransactionOptions<TSnapshot, TResult> {
+  /** 乐观应用 UI 变更，返回可用于 rollback 的快照 */
+  apply: () => TSnapshot
+  /** 执行异步路由导航 */
+  navigate: () => Promise<TResult>
+  /** 导航失败时回滚到快照状态 */
+  rollback: (snapshot: TSnapshot) => void
+  /** 导航成功后的确认回调（如驱逐旧缓存） */
+  commit?: () => void
+  /** 判断导航结果是否为失败（如 vue-router 返回的 NavigationFailure） */
+  isFailureResult?: (result: TResult) => boolean
+  /** 若为失败结果，是否将其作为异常抛出 */
+  rejectFailureResult?: boolean
+  /** 检查当前事务是否仍然有效（防止过期事务覆盖新状态） */
+  isCurrent?: () => boolean
+  /** 事务已过期时的清理回调（替代 rollback） */
+  cleanupStale?: () => void
+}
+
+/**
+ * 执行一次导航事务：apply → navigate → commit/rollback。
+ * 保证乐观更新在导航失败时能安全回滚。
+ */
+export const runNavigationTransaction = async <TSnapshot, TResult>(
+  options: NavigationTransactionOptions<TSnapshot, TResult>
+): Promise<TResult> => {
+  const snapshot = options.apply()
+
+  try {
+    const result = await options.navigate()
+    if (options.isFailureResult?.(result)) {
+      if (options.isCurrent?.() ?? true) {
+        options.rollback(snapshot)
+      } else {
+        options.cleanupStale?.()
+      }
+      if (options.rejectFailureResult) throw result
+      return result
+    }
+    if (options.isCurrent?.() ?? true) options.commit?.()
+    return result
+  } catch (error) {
+    if (options.isCurrent?.() ?? true) {
+      options.rollback(snapshot)
+    } else {
+      options.cleanupStale?.()
+    }
+    throw error
+  }
+}

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

@@ -0,0 +1,109 @@
+/**
+ * tabPanel/refresh - 普通页面与 iframe 标签的刷新逻辑。
+ *
+ * 活动普通页面保持 cache id 稳定，只递增页面级刷新版本；非活动页面可直接替换缓存。
+ */
+import type { Ref } from 'vue'
+import type { ITabItem } from '../../model/TabModel'
+
+export interface TabPanelRefreshApi {
+  refreshTab: (id: string) => void
+  refreshAllTabs: () => void
+}
+
+export interface CreateTabPanelRefreshOptions {
+  tabs: Ref<ITabItem[]>
+  iframeRefreshKeys: Ref<Record<string, number>>
+  getTab: (id: string) => ITabItem | null
+  createPageId: () => string
+  addCache: (cacheName: string) => void
+  evictPageCache: (cacheName: string) => void
+  replacePageCaches: (
+    cacheNamesToEvict: Iterable<string>,
+    cacheNamesToAdd: Iterable<string>
+  ) => void
+  refreshIframeByPostMessage: (tabId: string) => void
+}
+
+export const createTabPanelRefresh = (
+  options: CreateTabPanelRefreshOptions
+): TabPanelRefreshApi => {
+  const {
+    tabs,
+    iframeRefreshKeys,
+    getTab,
+    createPageId,
+    addCache,
+    evictPageCache,
+    replacePageCaches,
+    refreshIframeByPostMessage
+  } = options
+
+  const refreshIframe = (tab: ITabItem) => {
+    if (tab.iframeRefreshMode === 'reload') {
+      iframeRefreshKeys.value = {
+        ...iframeRefreshKeys.value,
+        [tab.id]: (iframeRefreshKeys.value[tab.id] ?? 0) + 1
+      }
+      return
+    }
+    refreshIframeByPostMessage(tab.id)
+  }
+
+  const refreshPage = (tab: ITabItem, cacheNamesToEvict?: string[], cacheNamesToAdd?: string[]) => {
+    const currentPage = tab.pages.peek()
+    if (!currentPage) return
+
+    if (tab.active) {
+      currentPage.refreshVersion = (currentPage.refreshVersion ?? 0) + 1
+      return
+    }
+
+    const oldCacheName = currentPage.id
+    currentPage.id = createPageId()
+    currentPage.refreshVersion = 0
+    if (cacheNamesToEvict && cacheNamesToAdd) {
+      cacheNamesToEvict.push(oldCacheName)
+      cacheNamesToAdd.push(currentPage.id)
+      return
+    }
+    evictPageCache(oldCacheName)
+    addCache(currentPage.id)
+  }
+
+  const refreshTab = (id: string) => {
+    const tab = getTab(id)
+    if (!tab?.refreshable) return
+    if (tab.iframe) {
+      refreshIframe(tab)
+      return
+    }
+    refreshPage(tab)
+  }
+
+  const refreshAllTabs = () => {
+    const cacheNamesToEvict: string[] = []
+    const cacheNamesToAdd: string[] = []
+    const iframeKeysUpdate = { ...iframeRefreshKeys.value }
+    let iframeKeysChanged = false
+
+    for (const tab of tabs.value) {
+      if (!tab.refreshable) continue
+      if (tab.iframe) {
+        if (tab.iframeRefreshMode === 'reload') {
+          iframeKeysUpdate[tab.id] = (iframeKeysUpdate[tab.id] ?? 0) + 1
+          iframeKeysChanged = true
+        } else {
+          refreshIframeByPostMessage(tab.id)
+        }
+        continue
+      }
+      refreshPage(tab, cacheNamesToEvict, cacheNamesToAdd)
+    }
+
+    if (iframeKeysChanged) iframeRefreshKeys.value = iframeKeysUpdate
+    replacePageCaches(cacheNamesToEvict, cacheNamesToAdd)
+  }
+
+  return { refreshTab, refreshAllTabs }
+}

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

@@ -1,56 +1,73 @@
 /**
  * tabPanel/scroll - 滚动位置保存与恢复
  *
- * 职责：在切出/切入页面时保存和恢复滚动位置
+ * 职责：基于当前 StackTabsRuntimeContext 在切出/切入页面时保存和恢复滚动位置。
  */
-import { scrollPositionsByPageId } from './state'
-
-/** 恢复指定页面的滚动位置 */
-export const restoreScroller = (pageCacheId: string) => {
-  const positions = scrollPositionsByPageId.get(pageCacheId)
-  if (!positions) return
-  for (const [sel, pos] of positions) {
-    const el = sel.startsWith('#')
-      ? document.getElementById(sel.slice(1))
-      : (document.querySelector(sel) as HTMLElement | null)
-    if (el) {
-      el.scrollTop = pos.top
-      el.scrollLeft = pos.left
+import type { StackTabsRuntimeContext } from '../stackTabsContext'
+
+export interface TabPanelScrollApi {
+  restoreScroller: (pageCacheId: string) => void
+  saveScroller: (pageCacheId: string) => void
+  removeScroller: (pageCacheId: string) => void
+  addPageScroller: (pageCacheId: string, ...selectorIds: string[]) => void
+}
+
+const resolveScrollElement = (selector: string): HTMLElement | null =>
+  selector.startsWith('#')
+    ? document.getElementById(selector.slice(1))
+    : (document.querySelector(selector) as HTMLElement | null)
+
+export const createTabPanelScroll = (context: StackTabsRuntimeContext): TabPanelScrollApi => {
+  const { scrollPositionsByPageId } = context
+
+  const restoreScroller = (pageCacheId: string): void => {
+    const positions = scrollPositionsByPageId.get(pageCacheId)
+    if (!positions) return
+
+    for (const [selector, position] of positions) {
+      const element = resolveScrollElement(selector)
+      if (element) {
+        element.scrollTop = position.top
+        element.scrollLeft = position.left
+      }
     }
   }
-}
 
-/** 保存指定页面的滚动位置 */
-export const saveScroller = (pageCacheId: string) => {
-  const positions = scrollPositionsByPageId.get(pageCacheId)
-  if (!positions) return
-  for (const sel of positions.keys()) {
-    const el = sel.startsWith('#')
-      ? document.getElementById(sel.slice(1))
-      : (document.querySelector(sel) as HTMLElement | null)
-    positions.set(sel, {
-      top: el?.scrollTop ?? 0,
-      left: el?.scrollLeft ?? 0
-    })
+  const saveScroller = (pageCacheId: string): void => {
+    const positions = scrollPositionsByPageId.get(pageCacheId)
+    if (!positions) return
+
+    for (const selector of positions.keys()) {
+      const element = resolveScrollElement(selector)
+      positions.set(selector, {
+        top: element?.scrollTop ?? 0,
+        left: element?.scrollLeft ?? 0
+      })
+    }
   }
-}
 
-/** 移除指定页面的滚动记录 */
-export const removeScroller = (pageCacheId: string) => {
-  const positions = scrollPositionsByPageId.get(pageCacheId)
-  if (positions) {
+  const removeScroller = (pageCacheId: string): void => {
+    const positions = scrollPositionsByPageId.get(pageCacheId)
+    if (!positions) return
+
     positions.clear()
     scrollPositionsByPageId.delete(pageCacheId)
   }
-}
 
-/** 为页面注册需要记录滚动位置的选择器 */
-export const addPageScroller = (pageCacheId: string, ...selectorIds: string[]) => {
-  if (!scrollPositionsByPageId.has(pageCacheId)) {
-    scrollPositionsByPageId.set(pageCacheId, new Map<string, { top: number; left: number }>())
+  const addPageScroller = (pageCacheId: string, ...selectorIds: string[]): void => {
+    if (!scrollPositionsByPageId.has(pageCacheId)) {
+      scrollPositionsByPageId.set(pageCacheId, new Map())
+    }
+    const positions = scrollPositionsByPageId.get(pageCacheId)!
+    for (const selector of selectorIds) {
+      positions.set(selector, { top: 0, left: 0 })
+    }
   }
-  const positions = scrollPositionsByPageId.get(pageCacheId)!
-  for (const sel of selectorIds) {
-    positions.set(sel, { top: 0, left: 0 })
+
+  return {
+    restoreScroller,
+    saveScroller,
+    removeScroller,
+    addPageScroller
   }
 }