vue-stack-tabs 2.5.0 → 2.6.0

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

@@ -7,6 +7,7 @@
 import {
   cloneVNode,
   defineComponent,
+  h,
   nextTick,
   onActivated,
   onBeforeUnmount,
@@ -20,6 +21,11 @@ import {
 } from 'vue'
 import type { DefineComponent, PropType, VNode } from 'vue'
 import type { ITabBase } from '../../model/TabModel'
+import {
+  readAdapterScrollMetrics,
+  resolveScrollAdapter,
+  type StackTabsScrollAdapter
+} from '../../model/ScrollAdapter'
 import PageLoading from '../../components/PageLoading.vue'
 import type { StackTabsRuntimeContext } from '../stackTabsContext'
 import { tabPageContextKey } from '../tabPageContext'
@@ -34,6 +40,10 @@ interface PageComponentFactoryOptions {
   evictMarkedCaches: () => void
   clearTabEvictionMarks: () => void
   addPageScroller: (pageId: string, ...selectors: string[]) => void
+  setPageScrollAdapter: (
+    pageId: string,
+    getter: (() => StackTabsScrollAdapter | null) | null
+  ) => void
   saveScroller: (pageId: string) => void
   restoreScroller: (pageId: string) => void
   removeScroller: (pageId: string) => void
@@ -79,6 +89,7 @@ export const createPageComponentFactory = (options: PageComponentFactoryOptions)
     evictMarkedCaches,
     clearTabEvictionMarks,
     addPageScroller,
+    setPageScrollAdapter,
     saveScroller,
     restoreScroller,
     removeScroller
@@ -154,6 +165,9 @@ export const createPageComponentFactory = (options: PageComponentFactoryOptions)
         const lastCloned = shallowRef<VNode | null>(null)
         const lastBackParams = shallowRef<Record<string, unknown> | null>(null)
         const pageRoot = ref<HTMLElement | null>(null)
+        /** 自定义滚动组件的实例（expose proxy），用于解析滚动适配器。 */
+        const scrollContainerRef = ref<unknown>(null)
+        const customScrollAdapter = shallowRef<StackTabsScrollAdapter | null>(null)
         /**
          * 实际渲染的刷新版本。
          *
@@ -163,6 +177,62 @@ export const createPageComponentFactory = (options: PageComponentFactoryOptions)
          */
         const renderedRefreshVersion = ref(props.refreshVersion ?? 0)
 
+        const hasCustomScrollContainer = (): boolean =>
+          Boolean(runtimeContext.scrollContainer.value)
+
+        /**
+         * 当前页面的主滚动适配器。
+         *
+         * 未传 `scrollContainer` 时把 wrapper 本身当作适配器，默认路径行为保持不变；
+         * 传入时读取自定义组件 expose 的能力，解析不到则按「无滚动容器」处理。
+         */
+        const getScrollAdapter = (): StackTabsScrollAdapter | null => {
+          if (!hasCustomScrollContainer()) {
+            return pageRoot.value ? { scrollElement: pageRoot.value } : null
+          }
+          return customScrollAdapter.value
+        }
+
+        /** 重新解析自定义滚动组件的适配器（运行时切换容器后也会调用）。 */
+        const syncScrollAdapter = (): void => {
+          customScrollAdapter.value = hasCustomScrollContainer()
+            ? resolveScrollAdapter(scrollContainerRef.value)
+            : null
+        }
+
+        /** 阴影订阅：优先用适配器的 onScroll，缺失时监听原生滚动元素。 */
+        const subscribeAdapterScroll = (listener: () => void): (() => void) => {
+          const adapter = getScrollAdapter()
+          if (adapter?.onScroll) return adapter.onScroll(listener)
+          const element = adapter?.scrollElement
+          if (!element) return () => undefined
+          element.addEventListener('scroll', listener, { passive: true })
+          return () => element.removeEventListener('scroll', listener)
+        }
+
+        // 阴影类挂到不被刷新动画 transform 的 panel 上；滚动监听绑定真实滚动元素。
+        // 否则 ::after 的绝对定位包含块会随 transform 变化，顶部阴影会错位/消失。
+        const scrollShadow = useScrollShadow({
+          target: () => getScrollAdapter()?.scrollElement ?? null,
+          classTarget: () => pageRoot.value?.parentElement ?? null,
+          getMetrics: () => readAdapterScrollMetrics(getScrollAdapter()),
+          onScroll: subscribeAdapterScroll
+        })
+
+        /**
+         * 同步主滚动容器的注册方式：
+         * - 默认路径：保持 `#W-<cacheName>` 选择器，行为与旧版本一致；
+         * - 自定义路径：改用适配器读写位置，跳过 wrapper 的注册。
+         */
+        const syncScrollRegistration = (): void => {
+          if (hasCustomScrollContainer()) {
+            setPageScrollAdapter(cacheName, () => customScrollAdapter.value)
+            return
+          }
+          addPageScroller(cacheName, `#W-${cacheName}`)
+          setPageScrollAdapter(cacheName, null)
+        }
+
         let refreshDisposed = false
         let isFlushingRefresh = false
         let queuedRefreshVersion: number | null = null
@@ -309,11 +379,22 @@ export const createPageComponentFactory = (options: PageComponentFactoryOptions)
 
         onMounted(() => {
           context.emit('onLoaded')
-          addPageScroller(cacheName, `#W-${cacheName}`)
+          syncScrollRegistration()
+          syncScrollAdapter()
           // 新页面经 Transition(out-in) 挂载时，setup 后的 microtask 可能早于 ref 赋值；
           // 挂载后重新 sync，确保 scroll shadow 监听与阴影类目标正确绑定。
-          scrollShadow.sync()
+          scrollShadow.sync(true)
           checkAndConsumeBackParams()
+
+          // 自定义滚动组件可能异步加载（异步组件 / Suspense），首帧尚未 expose。
+          // 下一 tick 再解析一次；首次解析成功时补一次位置恢复。
+          void nextTick(() => {
+            if (refreshDisposed) return
+            const wasResolved = Boolean(customScrollAdapter.value)
+            syncScrollAdapter()
+            if (!wasResolved && customScrollAdapter.value) restoreScroller(cacheName)
+            scrollShadow.sync(true)
+          })
         })
         onDeactivated(() => {
           scrollShadow.clear()
@@ -321,8 +402,9 @@ export const createPageComponentFactory = (options: PageComponentFactoryOptions)
         })
         onActivated(() => {
           context.emit('onLoaded')
+          syncScrollAdapter()
           restoreScroller(cacheName)
-          scrollShadow.sync()
+          scrollShadow.sync(true)
           evictMarkedCaches()
           clearTabEvictionMarks()
           checkAndConsumeBackParams()
@@ -336,12 +418,21 @@ export const createPageComponentFactory = (options: PageComponentFactoryOptions)
         })
         onUnmounted(() => removeScroller(cacheName))
 
-        // 阴影类挂到不被刷新动画 transform 的 panel 上；滚动监听仍绑定 wrapper。
-        // 否则 ::after 的绝对定位包含块会随 transform 变化，顶部阴影会错位/消失。
-        const scrollShadow = useScrollShadow({
-          target: pageRoot,
-          classTarget: () => pageRoot.value?.parentElement ?? null
-        })
+        // 运行时切换滚动组件：只重新解析适配器并重新同步阴影，不重建缓存页。
+        watch(
+          () => runtimeContext.scrollContainer.value,
+          () => {
+            // 切换前保存旧容器的主滚动位置，切换后由新容器 / 默认 wrapper 恢复。
+            saveScroller(cacheName)
+            void nextTick(() => {
+              if (refreshDisposed) return
+              syncScrollRegistration()
+              syncScrollAdapter()
+              restoreScroller(cacheName)
+              scrollShadow.sync(true)
+            })
+          }
+        )
 
         return () => {
           const vnode = props.vnode
@@ -356,24 +447,33 @@ export const createPageComponentFactory = (options: PageComponentFactoryOptions)
             lastBackParams.value = backParams
           }
 
+          const scrollContainer = runtimeContext.scrollContainer.value
+          const pageContent = lastCloned.value ? (
+            <PageShell
+              key={`${cacheName}-${renderedRefreshVersion.value}`}
+              vnode={lastCloned.value}
+            />
+          ) : null
+
           return (
             <div
               ref={pageRoot}
               class="stack-tab__cache-page-wrapper"
               id={`W-${cacheName}`}
               style={[
+                // 自定义滚动容器优先：wrapper 不再承担滚动，避免出现两层滚动条。
                 // 动画作用于 wrapper 本身，页面内容不会相对滚动容器位移，
                 // 因此无需临时隐藏 overflow，避免动画期间滚动条消失导致内容宽度跳动。
-                runtimeContext.useGlobalScroll.value ? 'overflow:auto' : 'overflow:hidden',
+                !scrollContainer && runtimeContext.useGlobalScroll.value
+                  ? 'overflow:auto'
+                  : 'overflow:hidden',
                 'height: 100%'
               ]}
             >
-              {lastCloned.value ? (
-                <PageShell
-                  key={`${cacheName}-${renderedRefreshVersion.value}`}
-                  vnode={lastCloned.value}
-                />
-              ) : null}
+              {scrollContainer
+                ? h(scrollContainer, { ref: scrollContainerRef }, { default: () => pageContent })
+                : pageContent}
+              {/* PageLoading 必须在滚动容器外层：它是覆盖整个内容区的遮罩。 */}
               <PageLoading tabId={tabInfo.id!} />
             </div>
           )

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

@@ -6,14 +6,33 @@
  *       避免每次 deactivate 都全量 querySelectorAll。
  */
 import type { StackTabsRuntimeContext } from '../stackTabsContext'
+import {
+  readAdapterScrollPosition,
+  writeAdapterScrollPosition,
+  type StackTabsScrollAdapter
+} from '../../model/ScrollAdapter'
 
 export interface TabPanelScrollApi {
   restoreScroller: (pageCacheId: string) => void
   saveScroller: (pageCacheId: string) => void
   removeScroller: (pageCacheId: string) => void
   addPageScroller: (pageCacheId: string, ...selectorIds: string[]) => void
+  /**
+   * 注册页面的自定义滚动适配器。
+   *
+   * 传 null 表示该页面回退到默认 wrapper（`#W-<cacheName>`）路径。
+   * getter 而不是适配器实例：运行时切换 `scrollContainer` 时，
+   * 位置保存/恢复总是读取最新的适配器。
+   */
+  setPageScrollAdapter: (
+    pageCacheId: string,
+    getter: (() => StackTabsScrollAdapter | null) | null
+  ) => void
 }
 
+/** 自定义滚动容器对应的主滚动位置 key；无自定义容器时仍使用 `#W-<cacheName>`。 */
+const MAIN_SCROLLER_KEY = '__stack-tab-main-scroller__'
+
 const resolveScrollElement = (selector: string): HTMLElement | null =>
   selector.startsWith('#')
     ? document.getElementById(selector.slice(1))
@@ -88,12 +107,20 @@ const resolveAutoScrollElement = (pageCacheId: string, key: string): HTMLElement
 
 export const createTabPanelScroll = (context: StackTabsRuntimeContext): TabPanelScrollApi => {
   const { scrollPositionsByPageId } = context
+  /** 已注册自定义滚动容器的页面；值为读取最新适配器的 getter。 */
+  const adapterGetters = new Map<string, () => StackTabsScrollAdapter | null>()
+
+  const getPageAdapter = (pageCacheId: string): StackTabsScrollAdapter | null =>
+    adapterGetters.get(pageCacheId)?.() ?? null
 
   const restoreScroller = (pageCacheId: string): void => {
     const positions = scrollPositionsByPageId.get(pageCacheId)
     if (!positions) return
 
+    // 先恢复页面内其它滚动元素，最后恢复主滚动容器：
+    // 运行时切换滚动组件时，普通 key 可能仍指向旧 wrapper，最后写入主位置可避免被覆盖。
     for (const [selector, position] of positions) {
+      if (selector === MAIN_SCROLLER_KEY) continue
       const element = selector.startsWith(AUTO_SCROLLER_PREFIX)
         ? resolveAutoScrollElement(pageCacheId, selector)
         : resolveScrollElement(selector)
@@ -102,12 +129,31 @@ export const createTabPanelScroll = (context: StackTabsRuntimeContext): TabPanel
         element.scrollLeft = position.left
       }
     }
+
+    const mainPosition = positions.get(MAIN_SCROLLER_KEY)
+    if (!mainPosition) return
+    const adapter = getPageAdapter(pageCacheId)
+    if (adapter && writeAdapterScrollPosition(adapter, mainPosition)) return
+    // 自定义组件被移除（切换回默认路径）或适配器暂时不可用时回退 wrapper。
+    const wrapper = document.getElementById(`W-${pageCacheId}`)
+    if (wrapper) {
+      wrapper.scrollTop = mainPosition.top
+      wrapper.scrollLeft = mainPosition.left
+    }
   }
 
   const saveScroller = (pageCacheId: string): void => {
     const positions = scrollPositionsByPageId.get(pageCacheId)
     if (!positions) return
 
+    // 自定义滚动容器存在时，主滚动位置由适配器读写；wrapper 不再承载滚动，
+    // 必须跳过 `#W-...` 的 DOM 读取，否则会把 0 写入位置缓存。
+    if (adapterGetters.has(pageCacheId)) {
+      positions.delete(`#W-${pageCacheId}`)
+      const position = readAdapterScrollPosition(getPageAdapter(pageCacheId))
+      if (position) positions.set(MAIN_SCROLLER_KEY, position)
+    }
+
     // 与当前页面 DOM 同步自动标记的容器；移除的元素不保留过期位置。
     for (const key of positions.keys()) {
       if (key.startsWith(AUTO_SCROLLER_PREFIX)) positions.delete(key)
@@ -122,8 +168,8 @@ export const createTabPanelScroll = (context: StackTabsRuntimeContext): TabPanel
     })
 
     for (const selector of positions.keys()) {
-      // auto key 已在上一步按 DOM 顺序写入，无需再次解析。
-      if (selector.startsWith(AUTO_SCROLLER_PREFIX)) continue
+      // auto key 已在上一步按 DOM 顺序写入，主滚动位置由适配器维护，均无需再次解析。
+      if (selector.startsWith(AUTO_SCROLLER_PREFIX) || selector === MAIN_SCROLLER_KEY) continue
       const element = resolveScrollElement(selector)
       positions.set(selector, {
         top: element?.scrollTop ?? 0,
@@ -138,6 +184,7 @@ export const createTabPanelScroll = (context: StackTabsRuntimeContext): TabPanel
       positions.clear()
       scrollPositionsByPageId.delete(pageCacheId)
     }
+    adapterGetters.delete(pageCacheId)
     // 同步卸载 MutationObserver，避免页面被驱逐后 observer 仍持有 DOM 引用。
     const cache = autoScrollCaches.get(pageCacheId)
     if (cache) {
@@ -156,10 +203,29 @@ export const createTabPanelScroll = (context: StackTabsRuntimeContext): TabPanel
     }
   }
 
+  const setPageScrollAdapter = (
+    pageCacheId: string,
+    getter: (() => StackTabsScrollAdapter | null) | null
+  ): void => {
+    if (!getter) {
+      adapterGetters.delete(pageCacheId)
+      return
+    }
+    adapterGetters.set(pageCacheId, getter)
+    if (!scrollPositionsByPageId.has(pageCacheId)) {
+      scrollPositionsByPageId.set(pageCacheId, new Map())
+    }
+    const positions = scrollPositionsByPageId.get(pageCacheId)!
+    if (!positions.has(MAIN_SCROLLER_KEY)) {
+      positions.set(MAIN_SCROLLER_KEY, { top: 0, left: 0 })
+    }
+  }
+
   return {
     restoreScroller,
     saveScroller,
     removeScroller,
-    addPageScroller
+    addPageScroller,
+    setPageScrollAdapter
   }
 }

package/src/lib/hooks/useScrollShadow.ts

@@ -43,11 +43,25 @@ export interface UseScrollShadowOptions {
    * 距离边界 ≤ 阈值视为已贴边（不显示阴影）；距离边界 > 阈值视为可继续滚动（显示阴影）。
    */
   edgeThreshold?: number
+  /**
+   * 自定义尺寸读取（可选）。提供时优先于 `target` 的原生
+   * `scrollTop / scrollHeight / clientHeight`，用于命令式滚动组件。
+   */
+  getMetrics?: () => { scrollTop: number; scrollHeight: number; clientHeight: number } | null
+  /**
+   * 自定义滚动订阅（可选）。提供时优先于在 `target` 上监听 scroll 事件，
+   * 返回取消订阅函数。`target` 可以为 null（例如纯 transform 驱动的滚动组件）。
+   */
+  onScroll?: (listener: () => void) => () => void
 }
 
 export interface UseScrollShadowReturn {
-  /** 重新解析滚动/阴影目标并同步一次（用于 keep-alive 激活、DOM 重新挂载后） */
-  sync: () => void
+  /**
+   * 重新解析滚动/阴影目标并同步一次（用于 keep-alive 激活、DOM 重新挂载后）。
+   * `force` 为 true 时即使 target 未变化也重建订阅，用于适配器内部状态
+   * （自定义滚动元素的 expose）在两次 sync 之间发生变化的场景。
+   */
+  sync: (force?: boolean) => void
   /** 移除阴影类并取消待执行的 rAF（用于 keep-alive 失活） */
   clear: () => void
 }
@@ -65,6 +79,8 @@ export const useScrollShadow = (options: UseScrollShadowOptions): UseScrollShado
   const edgeThreshold = Math.max(0, options.edgeThreshold ?? DEFAULT_EDGE_THRESHOLD)
   let rafId: number | null = null
   let attached: HTMLElement | null = null
+  let attachedOnScroll: ((listener: () => void) => () => void) | null = null
+  let scrollCleanup: (() => void) | null = null
   let classElement: HTMLElement | null = null
   let resizeObserver: ResizeObserver | null = null
 
@@ -78,8 +94,8 @@ export const useScrollShadow = (options: UseScrollShadowOptions): UseScrollShado
     options.classTarget ? resolveTarget(options.classTarget) : attached
 
   const recompute = (): void => {
-    if (!attached) return
-    const target = attached
+    // 命令式滚动组件可能没有原生滚动元素，但通过 getMetrics 提供尺寸。
+    if (!attached && !options.getMetrics) return
     const nextClassTarget = resolveClassTarget()
     if (classElement && classElement !== nextClassTarget) {
       clearClasses(classElement)
@@ -88,7 +104,19 @@ export const useScrollShadow = (options: UseScrollShadowOptions): UseScrollShado
     classElement = nextClassTarget
     if (!classElement) return
 
-    const { scrollTop, scrollHeight, clientHeight } = target
+    // 自定义尺寸优先；返回 null 时回退到原生滚动元素。
+    const metrics =
+      options.getMetrics?.() ??
+      (attached
+        ? {
+            scrollTop: attached.scrollTop,
+            scrollHeight: attached.scrollHeight,
+            clientHeight: attached.clientHeight
+          }
+        : null)
+    if (!metrics) return
+
+    const { scrollTop, scrollHeight, clientHeight } = metrics
     const distanceToTop = scrollTop
     const distanceToBottom = scrollHeight - clientHeight - scrollTop
     // 顶部阴影：表示上方还有内容，离开顶部（距离顶部 > 阈值）时显示。
@@ -111,23 +139,40 @@ export const useScrollShadow = (options: UseScrollShadowOptions): UseScrollShado
     })
   }
 
-  const attach = (): void => {
+  /** 释放滚动事件订阅 / ResizeObserver，不清理阴影类。 */
+  const releaseScrollSource = (): void => {
+    if (attached) attached.removeEventListener('scroll', schedule)
+    if (scrollCleanup) {
+      scrollCleanup()
+      scrollCleanup = null
+    }
+    attachedOnScroll = null
+    resizeObserver?.disconnect()
+    resizeObserver = null
+  }
+
+  const attach = (force = false): void => {
     const el = resolveTarget(options.target)
-    if (!el) return
-    if (el === attached) {
+    const onScroll = options.onScroll ?? null
+    if (!el && !onScroll && !options.getMetrics) return
+    if (!force && el === attached && onScroll === attachedOnScroll) {
       schedule()
       return
     }
-    if (attached) {
-      attached.removeEventListener('scroll', schedule)
-      resizeObserver?.disconnect()
-      resizeObserver = null
-      clearClasses(classElement)
-      classElement = null
-    }
+    releaseScrollSource()
+    clearClasses(classElement)
+    classElement = null
+
     attached = el
-    el.addEventListener('scroll', schedule, { passive: true })
-    if (watchResize && typeof ResizeObserver !== 'undefined') {
+    if (onScroll) {
+      // 自定义滚动订阅优先于原生 scroll 事件；没有原生滚动元素时也能工作。
+      attachedOnScroll = onScroll
+      const cleanup = onScroll(schedule)
+      scrollCleanup = typeof cleanup === 'function' ? cleanup : null
+    } else if (el) {
+      el.addEventListener('scroll', schedule, { passive: true })
+    }
+    if (watchResize && el && typeof ResizeObserver !== 'undefined') {
       resizeObserver = new ResizeObserver(() => schedule())
       resizeObserver.observe(el)
     }
@@ -147,24 +192,23 @@ export const useScrollShadow = (options: UseScrollShadowOptions): UseScrollShado
   }
 
   /** 重新解析目标：keep-alive 激活或 DOM 重新挂载后由调用方触发 */
-  const sync = (): void => {
+  const sync = (force = false): void => {
     const el = resolveTarget(options.target)
-    if (!el) {
-      clear()
+    const onScroll = options.onScroll ?? null
+    if (!el && !onScroll && !options.getMetrics) {
+      detach()
       return
     }
-    if (el !== attached) {
-      attach()
+    if (force || el !== attached || onScroll !== attachedOnScroll) {
+      attach(force)
       return
     }
     schedule()
   }
 
   const detach = (): void => {
-    if (attached) attached.removeEventListener('scroll', schedule)
+    releaseScrollSource()
     attached = null
-    resizeObserver?.disconnect()
-    resizeObserver = null
     clearClasses(classElement)
     classElement = null
     cancelScheduled()

package/src/lib/hooks/useTabPanel.tsx

@@ -13,7 +13,7 @@
  */
 import type { ITabBase, ITabData, ITabItem, ITabPage } from '../model/TabModel'
 import { computed, ref } from 'vue'
-import type { DefineComponent, VNode } from 'vue'
+import type { Component, DefineComponent, VNode } from 'vue'
 import { isNavigationFailure, useRouter } from 'vue-router'
 import type { RouteLocationNormalizedLoaded } from 'vue-router'
 import { encodeTabInfo, createId, createPageId, decodeTabInfo } from '../utils/tabInfoEncoder'
@@ -108,7 +108,7 @@ const createTabPanelApi = (runtimeContext: StackTabsRuntimeContext) => {
     restoreCaches,
     reset: resetStore
   } = store
-  const { restoreScroller, saveScroller, removeScroller, addPageScroller } =
+  const { restoreScroller, saveScroller, removeScroller, addPageScroller, setPageScrollAdapter } =
     createTabPanelScroll(runtimeContext)
   const {
     saveActiveTabToSession,
@@ -246,6 +246,7 @@ const createTabPanelApi = (runtimeContext: StackTabsRuntimeContext) => {
     evictMarkedCaches,
     clearTabEvictionMarks,
     addPageScroller,
+    setPageScrollAdapter,
     saveScroller,
     restoreScroller,
     removeScroller
@@ -813,6 +814,9 @@ const createTabPanelApi = (runtimeContext: StackTabsRuntimeContext) => {
     setGlobalScroll: (value: boolean) => {
       runtimeContext.useGlobalScroll.value = value
     },
+    setScrollContainer: (value: Component | null | undefined) => {
+      runtimeContext.scrollContainer.value = value ?? null
+    },
     clearSession,
     setSessionPrefix: (value: string) => {
       runtimeContext.sessionPrefix.value = value

package/src/lib/index.ts

@@ -37,6 +37,12 @@ export {
 }
 export { postOpenTab, onRefreshRequest, MSG_REFRESH, MSG_OPEN_TAB } from './utils/iframeBridge'
 export type { IframeOpenTabPayload } from './utils/iframeBridge'
+export type {
+  StackTabsScrollAdapter,
+  StackTabsScrollElementInstance,
+  StackTabsScrollMetrics,
+  StackTabsScrollPosition
+} from './model/ScrollAdapter'
 export default {
   install(Vue: App, options?: VueStackTabsPluginOptions): void {
     logVersion(import.meta.env.PACKAGE_VERSION)