vue-stack-tabs 1.4.2 → 2.3.0

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

@@ -32,19 +32,23 @@ export const createTabPanelSession = (context: StackTabsRuntimeContext): TabPane
   let pendingWrite: { tab: ITabItem; version: number } | null = null
   let writeVersion = 0
   let writeScheduled = false
+  /** 最近一次成功写入的内容；与待写入内容相同时跳过 setItem。 */
+  let lastPersistedJson: string | null = null
 
   /**
    * 写入 sessionStorage，捕获隐私模式（QuotaExceededError）等异常，
    * 避免在受限浏览器环境下抛出未处理错误。SSR 环境无 window 时直接跳过。
    */
-  const safeSetItem = (key: string, value: string): void => {
-    if (typeof window === 'undefined') return
+  const safeSetItem = (key: string, value: string): boolean => {
+    if (typeof window === 'undefined') return false
     try {
       window.sessionStorage.setItem(key, value)
+      return true
     } catch (error) {
       if (!import.meta.env.PROD) {
         console.warn('[vue-stack-tabs] Failed to write sessionStorage:', error)
       }
+      return false
     }
   }
 
@@ -64,7 +68,9 @@ export const createTabPanelSession = (context: StackTabsRuntimeContext): TabPane
     const write = pendingWrite
     pendingWrite = null
     if (!write || write.version !== writeVersion) return
-    safeSetItem(getSessionKey(), JSON.stringify(write.tab))
+    const serialized = JSON.stringify(write.tab)
+    if (serialized === lastPersistedJson) return
+    if (safeSetItem(getSessionKey(), serialized)) lastPersistedJson = serialized
   }
 
   const invalidatePendingWrite = () => {
@@ -83,6 +89,7 @@ export const createTabPanelSession = (context: StackTabsRuntimeContext): TabPane
   const clearSession = (): void => {
     invalidatePendingWrite()
     safeRemoveItem(getSessionKey())
+    lastPersistedJson = null
   }
 
   const restoreActiveTabSession = (storedJson: string | null): void => {
@@ -91,7 +98,7 @@ export const createTabPanelSession = (context: StackTabsRuntimeContext): TabPane
       return
     }
     invalidatePendingWrite()
-    safeSetItem(getSessionKey(), storedJson)
+    if (safeSetItem(getSessionKey(), storedJson)) lastPersistedJson = storedJson
   }
 
   const restoreTabFromSession = (storedJson: string | null): ITabItem | null => {

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

@@ -15,7 +15,6 @@ export interface ScrollPosition {
 
 export interface TabPanelRuntimeState {
   tabs: Ref<ITabItem[]>
-  defaultTabs: Ref<ITabItem[]>
   caches: ShallowRef<string[]>
   components: Map<string, DefineComponent>
   cacheIdsToEvict: Set<string>
@@ -34,7 +33,6 @@ export const SESSION_TAB_NAME = 'stacktab-active-tab'
 
 export const createTabPanelRuntimeState = (): TabPanelRuntimeState => ({
   tabs: ref<ITabItem[]>([]) as Ref<ITabItem[]>,
-  defaultTabs: ref<ITabItem[]>([]) as Ref<ITabItem[]>,
   caches: shallowRef<string[]>([]),
   components: new Map<string, DefineComponent>(),
   cacheIdsToEvict: new Set<string>(),

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

@@ -12,7 +12,7 @@
  * 注意：本模块不依赖 vue-router，也不触发业务事件；路由事务与事件由 useTabPanel /
  * useTabRouter 等上层编排。
  */
-import { reactive, ref } from 'vue'
+import { markRaw, reactive, ref } from 'vue'
 import type { DefineComponent } from 'vue'
 import type { ITabItem, ITabPage } from '../../model/TabModel'
 import { Stack } from '../../model/TabModel'
@@ -27,6 +27,12 @@ export interface RemoveTabResult {
   nextActiveId: string
 }
 
+export interface PageUpdate {
+  tabId: string
+  pageId: string
+  patch: PagePatch
+}
+
 /** updatePage 允许修改的字段；页面身份与刷新版本必须通过 store 写入 */
 export interface PagePatch {
   id?: string
@@ -46,6 +52,8 @@ export interface TabStoreApi extends TabPanelEvictionApi {
   canAddTab: () => boolean
   getPages: (tabId: string) => readonly ITabPage[]
   getTopPage: (tabId: string) => ITabPage | null
+  /** 读取任意页面的刷新版本；渲染层据此只重建对应页面 */
+  getPageRefreshVersion: (pageId: string) => number
   /** 返回深拷贝的页面栈快照，可直接用于 rollback */
   getPageSnapshot: (tabId: string) => ITabPage[]
 
@@ -54,6 +62,8 @@ export interface TabStoreApi extends TabPanelEvictionApi {
   addTabs: (tabs: readonly ITabItem[]) => void
   /** 唯一 active 写入口 */
   activateTab: (id: string) => ITabItem | null
+  /** 动态更新标签标题；返回 false 表示标签不存在 */
+  updateTabTitle: (id: string, title: string) => boolean
   moveTab: (id: string, targetIndex: number) => boolean
   removeTab: (id: string) => RemoveTabResult
   removeTabs: (shouldRemove: (tab: ITabItem, index: number) => boolean) => ITabItem[]
@@ -65,8 +75,10 @@ export interface TabStoreApi extends TabPanelEvictionApi {
   /** 用给定页面替换整个栈（内部深拷贝页面） */
   replacePages: (tabId: string, pages: readonly ITabPage[]) => void
   clearPages: (tabId: string) => void
-  /** 修改页面字段（id / refreshVersion / _backParams），并触发 tabs 更新 */
+  /** 修改页面字段（id / refreshVersion / _backParams）；仅 id 变化时重建 tabs 数组 */
   updatePage: (tabId: string, pageId: string, patch: PagePatch) => boolean
+  /** 批量修改页面字段，最后最多重建一次 tabs 数组（供 refreshAllTabs 使用） */
+  updatePages: (updates: readonly PageUpdate[]) => void
   /** 取出并清除栈顶页面的 _backParams；pageId 不是当前栈顶时返回 null */
   consumeBackParams: (tabId: string, pageId: string) => Record<string, unknown> | null
 
@@ -103,11 +115,18 @@ interface TabRecord {
   iframe: boolean
   iframeRefreshMode?: 'postMessage' | 'reload'
   url?: string
+  /** 固定在标签栏最前方，不可拖动，其他标签也不能排到它前面 */
+  pinned?: boolean
 }
 
 interface PageStackAccess {
   getPages: (tabId: string) => readonly ITabPage[]
+  getPageIds: (tabId: string) => readonly string[]
+  getPageAt: (tabId: string, index: number) => ITabPage | undefined
+  getPageCount: (tabId: string) => number
   getTopPage: (tabId: string) => ITabPage | null
+  /** 读取任意页面的刷新版本；渲染层据此只重建对应页面 */
+  getPageRefreshVersion: (pageId: string) => number
   appendPage: (tabId: string, page: ITabPage) => void
   popPages: (tabId: string, steps: number) => ITabPage[]
   clearPages: (tabId: string) => void
@@ -140,15 +159,16 @@ class PageStackView extends Stack<ITabPage> {
   }
 
   override at(index: number): ITabPage | undefined {
-    return this.access.getPages(this.tabId)[index]
+    // 只取单个元素时不必构造整条页面数组。
+    return this.access.getPageAt(this.tabId, index)
   }
 
   override isEmpty(): boolean {
-    return this.access.getPages(this.tabId).length === 0
+    return this.access.getPageCount(this.tabId) === 0
   }
 
   override size(): number {
-    return this.access.getPages(this.tabId).length
+    return this.access.getPageCount(this.tabId)
   }
 
   override clear(): void {
@@ -211,6 +231,7 @@ const createTabStore = (context: StackTabsRuntimeContext): TabStoreApi => {
   // ---- 查询 ----
   const getTabs = (): readonly ITabItem[] => tabs.value
 
+  // 返回 tabs.value 中的对象（深度代理后的视图），保持调用方的对象身份比较语义。
   const getTab = (id: string): ITabItem | null => tabs.value.find((tab) => tab.id === id) ?? null
 
   const getActiveTab = (): ITabItem | null => tabs.value.find((tab) => tab.active) ?? null
@@ -234,9 +255,22 @@ const createTabStore = (context: StackTabsRuntimeContext): TabStoreApi => {
     return pagesById.get(ids[ids.length - 1] as string) ?? null
   }
 
+  const getPageCount = (tabId: string): number => pageIdsByTabId.get(tabId)?.length ?? 0
+
+  /** 按下标读取页面；越界（含负数）返回 undefined，与数组下标语义一致 */
+  const getPageAt = (tabId: string, index: number): ITabPage | undefined => {
+    const ids = pageIdsByTabId.get(tabId)
+    if (!ids || index < 0 || index >= ids.length) return undefined
+    return pagesById.get(ids[index] as string)
+  }
+
+  const getPageRefreshVersion = (pageId: string): number =>
+    pagesById.get(pageId)?.refreshVersion ?? 0
+
   const findTabByTopPagePath = (path: string): ITabItem | null => {
+    // 直接遍历 tabViews，避免原先「getTopPage + getTab(find)」的 O(n²) 组合。
     for (const id of tabOrder.value) {
-      if (getTopPage(id)?.path === path) return getTab(id)
+      if (getTopPage(id)?.path === path) return tabViews.get(id) ?? null
     }
     return null
   }
@@ -258,7 +292,8 @@ const createTabStore = (context: StackTabsRuntimeContext): TabStoreApi => {
     refreshable: tab.refreshable,
     iframe: tab.iframe,
     iframeRefreshMode: tab.iframeRefreshMode,
-    url: tab.url
+    url: tab.url,
+    pinned: tab.pinned
   })
 
   const registerTab = (tab: ITabItem): void => {
@@ -288,27 +323,46 @@ const createTabStore = (context: StackTabsRuntimeContext): TabStoreApi => {
   }
 
   const activateTab = (id: string): ITabItem | null => {
-    activeTabId.value = tabsById.has(id) ? id : ''
-    syncTabsView()
+    const nextId = tabsById.has(id) ? id : ''
+    // 重复激活同一标签（页面内导航经常走到这里）无需重建 tabs 数组。
+    if (nextId !== activeTabId.value) {
+      activeTabId.value = nextId
+      syncTabsView()
+    }
     return getTab(id)
   }
 
+  const updateTabTitle = (id: string, title: string): boolean => {
+    const record = tabsById.get(id)
+    if (!record) return false
+    if (record.title === title) return true
+    record.title = title
+    syncTabsView()
+    return true
+  }
+
   const moveTab = (id: string, targetIndex: number): boolean => {
     const order = tabOrder.value
     const sourceIndex = order.indexOf(id)
-    if (
-      sourceIndex < 0 ||
-      targetIndex < 0 ||
-      targetIndex >= order.length ||
-      sourceIndex === targetIndex
-    ) {
+    if (sourceIndex < 0 || targetIndex < 0 || sourceIndex === targetIndex) {
       return false
     }
 
+    // pinned 标签（home）固定在最前方：自身不可移动，其他标签也不得插到它前面。
+    const sourceRecord = tabsById.get(id)
+    if (!sourceRecord || sourceRecord.pinned) return false
+
+    let firstUnpinnedIndex = 0
+    for (let index = 0; index < order.length; index++) {
+      if (tabsById.get(order[index] as string)?.pinned) firstUnpinnedIndex = index + 1
+    }
+    const safeTargetIndex = Math.max(targetIndex, firstUnpinnedIndex)
+    if (safeTargetIndex >= order.length || safeTargetIndex === sourceIndex) return false
+
     const reordered = [...order]
     const [tabId] = reordered.splice(sourceIndex, 1)
     if (!tabId) return false
-    reordered.splice(targetIndex, 0, tabId)
+    reordered.splice(safeTargetIndex, 0, tabId)
     tabOrder.value = reordered
     syncTabsView()
     return true
@@ -379,12 +433,13 @@ const createTabStore = (context: StackTabsRuntimeContext): TabStoreApi => {
   }
 
   // ---- 页面栈写入 ----
+  // 页面栈只修改 pageIdsByTabId / pagesById（两者都是响应式 Map），
+  // 不重建 tabs 数组：标签栏、iframe 与刷新版本计算都无需因入栈/出栈重新求值。
   const appendPage = (tabId: string, page: ITabPage): void => {
     if (!tabsById.has(tabId)) return
     const ids = pageIdsByTabId.get(tabId) ?? []
     pageIdsByTabId.set(tabId, [...ids, page.id])
     pagesById.set(page.id, page)
-    syncTabsView()
   }
 
   const popPages = (tabId: string, steps: number): ITabPage[] => {
@@ -400,7 +455,6 @@ const createTabStore = (context: StackTabsRuntimeContext): TabStoreApi => {
       pagesById.delete(pageId)
     }
     pageIdsByTabId.set(tabId, ids)
-    syncTabsView()
     return popped
   }
 
@@ -415,22 +469,25 @@ const createTabStore = (context: StackTabsRuntimeContext): TabStoreApi => {
       nextPageIds.push(cloned.id)
     }
     pageIdsByTabId.set(tabId, nextPageIds)
-    syncTabsView()
   }
 
   const clearPages = (tabId: string): void => {
     if (!tabsById.has(tabId)) return
     for (const pageId of getPageIds(tabId)) pagesById.delete(pageId)
     pageIdsByTabId.set(tabId, [])
-    syncTabsView()
   }
 
-  const updatePage = (tabId: string, pageId: string, patch: PagePatch): boolean => {
+  const applyPagePatch = (
+    tabId: string,
+    pageId: string,
+    patch: PagePatch
+  ): 'missing' | 'conflict' | 'same-id' | 'new-id' => {
     const ids = pageIdsByTabId.get(tabId)
-    if (!ids || !ids.includes(pageId)) return false
+    if (!ids || !ids.includes(pageId)) return 'missing'
 
     const page = pagesById.get(pageId)
-    if (!page) return false
+    if (!page) return 'missing'
+    if (patch.id && patch.id !== pageId && pagesById.has(patch.id)) return 'conflict'
 
     Object.assign(page, patch)
     if (patch.id && patch.id !== pageId) {
@@ -440,17 +497,38 @@ const createTabStore = (context: StackTabsRuntimeContext): TabStoreApi => {
         tabId,
         ids.map((id) => (id === pageId ? (patch.id as string) : id))
       )
+      return 'new-id'
     }
-    syncTabsView()
+    return 'same-id'
+  }
+
+  /**
+   * 刷新版本、_backParams 都是 page 上的响应式字段，读取方会自行更新；
+   * 只有页面 id 变化才需要重建 tabs 视图，避免刷新一个标签就 diff 整个标签栏。
+   */
+  const updatePage = (tabId: string, pageId: string, patch: PagePatch): boolean => {
+    const result = applyPagePatch(tabId, pageId, patch)
+    if (result === 'missing' || result === 'conflict') return false
+    if (result === 'new-id') syncTabsView()
     return true
   }
 
+  const updatePages = (updates: readonly PageUpdate[]): void => {
+    let needsSync = false
+    for (const update of updates) {
+      if (applyPagePatch(update.tabId, update.pageId, update.patch) === 'new-id') {
+        needsSync = true
+      }
+    }
+    if (needsSync) syncTabsView()
+  }
+
   const consumeBackParams = (tabId: string, pageId: string): Record<string, unknown> | null => {
     const top = getTopPage(tabId)
     if (!top || top.id !== pageId || !top._backParams) return null
     const backParams = { ...top._backParams }
+    // _backParams 是页面对象上的响应式字段，删除后读取方会自行更新。
     delete top._backParams
-    syncTabsView()
     return backParams
   }
 
@@ -485,7 +563,11 @@ const createTabStore = (context: StackTabsRuntimeContext): TabStoreApi => {
   // ---- 兼容视图 ----
   const pageAccess: PageStackAccess = {
     getPages,
+    getPageIds,
+    getPageAt,
+    getPageCount,
     getTopPage,
+    getPageRefreshVersion,
     appendPage,
     popPages,
     clearPages
@@ -506,7 +588,9 @@ const createTabStore = (context: StackTabsRuntimeContext): TabStoreApi => {
         iframeRefreshMode: record.iframeRefreshMode,
         url: record.url,
         active: activeTabId.value === id,
-        pages: new PageStackView(id, pageAccess)
+        // pages 的读写都转发给 store，本身不需要被 ref 深度代理。
+        pages: markRaw(new PageStackView(id, pageAccess)),
+        pinned: record.pinned
       }
       tabViews.set(id, view)
     } else {
@@ -515,6 +599,7 @@ const createTabStore = (context: StackTabsRuntimeContext): TabStoreApi => {
       view.refreshable = record.refreshable
       view.iframe = record.iframe
       view.active = activeTabId.value === id
+      view.pinned = record.pinned
       if (record.iframeRefreshMode === undefined) {
         delete view.iframeRefreshMode
       } else {
@@ -548,10 +633,12 @@ const createTabStore = (context: StackTabsRuntimeContext): TabStoreApi => {
     canAddTab,
     getPages,
     getTopPage,
+    getPageRefreshVersion,
     getPageSnapshot,
     addTab,
     addTabs,
     activateTab,
+    updateTabTitle,
     moveTab,
     removeTab,
     removeTabs,
@@ -560,6 +647,7 @@ const createTabStore = (context: StackTabsRuntimeContext): TabStoreApi => {
     replacePages,
     clearPages,
     updatePage,
+    updatePages,
     consumeBackParams,
     isTabMarkedForEviction: (id) => tabIdsToEvict.has(id),
     isCacheMarkedForEviction: (id) => cacheIdsToEvict.has(id),

package/src/lib/hooks/useContextMenu.ts

@@ -41,7 +41,7 @@ export default () => {
   /** 点击菜单外部时关闭菜单。 */
   const handleClickOutside = (ev: MouseEvent) => {
     const target = ev.target as Element
-    if (target.closest?.('.stack-tab__contextmenu')) return
+    if (target.closest?.('.stack-tab__context-menu')) return
     // 同一手势的 click 仍在守卫窗口内，跳过关闭判断。
     if (Date.now() - lastContextMenuAt < BUBBLE_GUARD_MS) return
     hideContextMenu()

package/src/lib/hooks/useIframeManager.ts

@@ -19,7 +19,7 @@ interface IframeLoadState {
 export interface UseIframeManagerOptions {
   tabs: Ref<ITabItem[]>
   iframeRefreshKeys: Ref<Record<string, number>>
-  iframeLoadTimeout: number
+  iframeLoadTimeout: Ref<number>
   t: (key: string) => string
 }
 
@@ -106,7 +106,7 @@ export function useIframeManager(options: UseIframeManagerOptions) {
             message: t('VueStackTab.iframeLoadTimeout')
           }
         }
-      }, iframeLoadTimeout)
+      }, iframeLoadTimeout.value)
     )
   }
 
@@ -137,10 +137,17 @@ export function useIframeManager(options: UseIframeManagerOptions) {
     }
   }
 
-  /** 同步 iframe 激活和移除状态，避免用多个 watcher 重复遍历 iframe 列表。 */
+  /**
+   * 同步 iframe 激活和移除状态。
+   * 只监听 id:active 签名，普通标签的标题/页面栈变化不会触发遍历。
+   */
+  const iframeActivationSignature = computed(() =>
+    iframeTabs.value.map((frame) => `${frame.id}:${frame.active ? 1 : 0}`).join('|')
+  )
   watch(
-    () => iframeTabs.value.map((frame) => ({ id: frame.id, active: frame.active })),
-    (frames) => {
+    iframeActivationSignature,
+    () => {
+      const frames = iframeTabs.value
       for (const f of frames) {
         if (!f.active) continue
         iframeEverActivated[f.id] = true
@@ -169,20 +176,16 @@ export function useIframeManager(options: UseIframeManagerOptions) {
   )
 
   // refreshKey 变化时重新触发对应 iframe 的加载状态
-  watch(
-    iframeRefreshKeys,
-    (keys, previousKeys = {}) => {
-      for (const frame of iframeTabs.value) {
-        if (!frame.active) continue
-        const nextKey = keys[frame.id] ?? 0
-        const previousKey = previousKeys[frame.id] ?? 0
-        if (nextKey !== previousKey) {
-          setIframeLoading(frame.id, { force: true })
-        }
+  watch(iframeRefreshKeys, (keys, previousKeys = {}) => {
+    for (const frame of iframeTabs.value) {
+      if (!frame.active) continue
+      const nextKey = keys[frame.id] ?? 0
+      const previousKey = previousKeys[frame.id] ?? 0
+      if (nextKey !== previousKey) {
+        setIframeLoading(frame.id, { force: true })
       }
-    },
-    { deep: true }
-  )
+    }
+  })
 
   const handleIframeLoad = (frame: { id: string; url?: string }, event: Event) => {
     const iframe = event.currentTarget as HTMLIFrameElement | null

package/src/lib/hooks/useScrollShadow.ts

@@ -13,6 +13,8 @@
  *  - 阈值（默认 5px）内视为已贴边（≤ 阈值）→ 隐藏阴影；超过阈值视为可继续滚动 → 显示阴影
  *  - SSR 安全：在 document 不存在时直接返回
  *  - 自动清理：onScopeDispose 移除监听并取消 rAF/disconnect observer
+ *  - 阴影类可以挂到另一个不参与 transform 的元素上：滚动容器的 ::after 一旦
+ *    跟随 transform（例如页面刷新动画），绝对定位的包含块就会变化，阴影会错位/消失
  */
 import { onScopeDispose, type Ref } from 'vue'
 
@@ -22,8 +24,15 @@ const SHADOW_VERTICAL_CLASS = 'stack-tab__shadow-inset-vertical'
 const DEFAULT_EDGE_THRESHOLD = 5
 
 export interface UseScrollShadowOptions {
-  /** 容器元素的 ref，可以是 Ref<HTMLElement | null> 或 getter 函数 */
+  /** 滚动容器：用于监听 scroll / resize 并读取滚动尺寸 */
   target: Ref<HTMLElement | null> | (() => HTMLElement | null)
+  /**
+   * 阴影类挂载目标，默认与 target 相同。
+   * 当 target 参与 transform 动画（如刷新转场）时，应传入不参与动画的祖先
+   * （例如 .stack-tab__keep-alive-panel），否则 ::after 的绝对定位包含块会变化，
+   * 阴影会随动画错位或消失。
+   */
+  classTarget?: Ref<HTMLElement | null> | (() => HTMLElement | null)
   /**
    * 是否监听内容缩放/尺寸变化（默认 true）。
    * 启用后会用 ResizeObserver 监视目标尺寸，容器或子树尺寸变化都会重新计算阴影边界。
@@ -37,8 +46,10 @@ export interface UseScrollShadowOptions {
 }
 
 export interface UseScrollShadowReturn {
-  /** 手动同步一次（用于内容变化/resize 后） */
+  /** 重新解析滚动/阴影目标并同步一次（用于 keep-alive 激活、DOM 重新挂载后） */
   sync: () => void
+  /** 移除阴影类并取消待执行的 rAF（用于 keep-alive 失活） */
+  clear: () => void
 }
 
 const resolveTarget = (
@@ -47,18 +58,36 @@ const resolveTarget = (
 
 export const useScrollShadow = (options: UseScrollShadowOptions): UseScrollShadowReturn => {
   if (typeof document === 'undefined') {
-    return { sync: () => undefined }
+    return { sync: () => undefined, clear: () => undefined }
   }
 
   const watchResize = options.watchResize !== false
   const edgeThreshold = Math.max(0, options.edgeThreshold ?? DEFAULT_EDGE_THRESHOLD)
   let rafId: number | null = null
   let attached: HTMLElement | null = null
+  let classElement: HTMLElement | null = null
   let resizeObserver: ResizeObserver | null = null
 
+  const clearClasses = (element: HTMLElement | null): void => {
+    if (!element) return
+    element.classList.remove(SHADOW_TOP_CLASS, SHADOW_BOTTOM_CLASS, SHADOW_VERTICAL_CLASS)
+  }
+
+  /** 阴影类目标：配置了 classTarget 时必须真实解析到，否则宁可不显示（激活后会 sync 重试） */
+  const resolveClassTarget = (): HTMLElement | null =>
+    options.classTarget ? resolveTarget(options.classTarget) : attached
+
   const recompute = (): void => {
     if (!attached) return
     const target = attached
+    const nextClassTarget = resolveClassTarget()
+    if (classElement && classElement !== nextClassTarget) {
+      clearClasses(classElement)
+      classElement = null
+    }
+    classElement = nextClassTarget
+    if (!classElement) return
+
     const { scrollTop, scrollHeight, clientHeight } = target
     const distanceToTop = scrollTop
     const distanceToBottom = scrollHeight - clientHeight - scrollTop
@@ -69,9 +98,9 @@ export const useScrollShadow = (options: UseScrollShadowOptions): UseScrollShado
     // 注意：-top / -bottom 是两个独立 CSS 规则、作用在同一个 ::after 上，
     // 同时加会互相覆盖（后定义的 -bottom 胜出）。因此这里互斥地只加一个类：
     // 两侧都有内容用 -vertical，只有一侧用 -top / -bottom，贴边时都不加。
-    target.classList.toggle(SHADOW_VERTICAL_CLASS, showTopShadow && showBottomShadow)
-    target.classList.toggle(SHADOW_TOP_CLASS, showTopShadow && !showBottomShadow)
-    target.classList.toggle(SHADOW_BOTTOM_CLASS, !showTopShadow && showBottomShadow)
+    classElement.classList.toggle(SHADOW_VERTICAL_CLASS, showTopShadow && showBottomShadow)
+    classElement.classList.toggle(SHADOW_TOP_CLASS, showTopShadow && !showBottomShadow)
+    classElement.classList.toggle(SHADOW_BOTTOM_CLASS, !showTopShadow && showBottomShadow)
   }
 
   const schedule = (): void => {
@@ -84,11 +113,17 @@ export const useScrollShadow = (options: UseScrollShadowOptions): UseScrollShado
 
   const attach = (): void => {
     const el = resolveTarget(options.target)
-    if (!el || el === attached) return
+    if (!el) return
+    if (el === attached) {
+      schedule()
+      return
+    }
     if (attached) {
       attached.removeEventListener('scroll', schedule)
       resizeObserver?.disconnect()
       resizeObserver = null
+      clearClasses(classElement)
+      classElement = null
     }
     attached = el
     el.addEventListener('scroll', schedule, { passive: true })
@@ -99,18 +134,40 @@ export const useScrollShadow = (options: UseScrollShadowOptions): UseScrollShado
     schedule()
   }
 
-  const detach = (): void => {
-    if (attached) {
-      attached.removeEventListener('scroll', schedule)
-      attached.classList.remove(SHADOW_TOP_CLASS, SHADOW_BOTTOM_CLASS, SHADOW_VERTICAL_CLASS)
-      attached = null
+  const cancelScheduled = (): void => {
+    if (rafId === null) return
+    cancelAnimationFrame(rafId)
+    rafId = null
+  }
+
+  const clear = (): void => {
+    clearClasses(classElement)
+    classElement = null
+    cancelScheduled()
+  }
+
+  /** 重新解析目标：keep-alive 激活或 DOM 重新挂载后由调用方触发 */
+  const sync = (): void => {
+    const el = resolveTarget(options.target)
+    if (!el) {
+      clear()
+      return
+    }
+    if (el !== attached) {
+      attach()
+      return
     }
+    schedule()
+  }
+
+  const detach = (): void => {
+    if (attached) attached.removeEventListener('scroll', schedule)
+    attached = null
     resizeObserver?.disconnect()
     resizeObserver = null
-    if (rafId !== null) {
-      cancelAnimationFrame(rafId)
-      rafId = null
-    }
+    clearClasses(classElement)
+    classElement = null
+    cancelScheduled()
   }
 
   // 初始挂载（target 可能是异步插入的 DOM，使用 microtask 等一帧）
@@ -118,7 +175,5 @@ export const useScrollShadow = (options: UseScrollShadowOptions): UseScrollShado
 
   onScopeDispose(detach)
 
-  return {
-    sync: () => schedule()
-  }
+  return { sync, clear }
 }