vue-stack-tabs 2.5.1 → 2.6.1

package/src/lib/StackTabs.vue

@@ -22,7 +22,7 @@ import {
   toRef,
   watch
 } from 'vue'
-import type { TransitionProps } from 'vue'
+import type { Component, TransitionProps } from 'vue'
 import { getMaxZIndex, invalidateZIndexCache } from './utils/scrollUtils'
 import { isAllowedTabUrl } from './utils/urlParser'
 import { applyStackTabsLocale } from './i18n/stackTabsLocale'
@@ -70,6 +70,14 @@ const props = withDefaults(
     i18n?: string
     space?: number
     globalScroll?: boolean
+    /**
+     * 可选的自定义滚动组件，用于承载每个页签内容区的滚动。
+     *
+     * 组件需要渲染默认插槽、根元素填满父容器，并通过 `expose` 暴露
+     * `scrollElement`（或实现 `StackTabsScrollAdapter` 的可选方法）。
+     * 传入后 wrapper 恒为 `overflow: hidden`，`globalScroll` 仅对默认路径生效。
+     */
+    scrollContainer?: Component
     iframePath: string
     sessionPrefix?: string
     iframeAllowedOrigins?: string[]
@@ -118,6 +126,7 @@ const runtimeContext =
     iframePath: props.iframePath,
     maxTabCount: props.max,
     useGlobalScroll: props.globalScroll,
+    scrollContainer: props.scrollContainer,
     sessionPrefix: props.sessionPrefix
   })
 const stackTabsApp = getCurrentInstance()?.appContext.app
@@ -148,6 +157,7 @@ const panelApi = isRuntimeContextOwner
       initialize: () => undefined,
       setMaxSize: () => undefined,
       setGlobalScroll: () => undefined,
+      setScrollContainer: () => undefined,
       setSessionPrefix: () => undefined
     }
 const {
@@ -157,6 +167,7 @@ const {
   initialize,
   setMaxSize,
   setGlobalScroll,
+  setScrollContainer,
   setSessionPrefix
 } = panelApi
 const tabActions = isRuntimeContextOwner
@@ -170,6 +181,7 @@ const { setIFramePath, openTab, openInNewWindow } = tabActions
 if (isRuntimeContextOwner) {
   setIFramePath(props.iframePath)
   setGlobalScroll(props.globalScroll)
+  setScrollContainer(props.scrollContainer)
   setMaxSize(props.max)
   applyStackTabsLocale(changeLocale, props.i18n)
 
@@ -183,6 +195,10 @@ if (isRuntimeContextOwner) {
     () => props.globalScroll,
     (value) => setGlobalScroll(value)
   )
+  watch(
+    () => props.scrollContainer,
+    (value) => setScrollContainer(value)
+  )
   watch(
     () => props.sessionPrefix,
     (value) => setSessionPrefix(value)

package/src/lib/hooks/stackTabsContext.ts

@@ -6,8 +6,8 @@
  * 容器的兼容调用（例如旧的单元测试），绝不能承载某个 Vue App 的状态。
  * 每个 Vue app 只允许注册一个 <VueStackTabs> 实例。
  */
-import type { App, DefineComponent, InjectionKey, Ref, ShallowRef } from 'vue'
-import { hasInjectionContext, inject, ref } from 'vue'
+import type { App, Component, DefineComponent, InjectionKey, Ref, ShallowRef } from 'vue'
+import { hasInjectionContext, inject, ref, shallowRef } from 'vue'
 import type { Emitter } from 'mitt'
 import mitt from 'mitt'
 import type { ITabItem } from '../model/TabModel'
@@ -33,6 +33,12 @@ export interface StackTabsRuntimeContext {
   iframeRefreshKeys: Ref<Record<string, number>>
   maxTabCount: Ref<number>
   useGlobalScroll: Ref<boolean>
+  /**
+   * 宿主提供的自定义滚动组件（可选）。
+   * 传入后每个缓存页的内容区由该组件承载滚动，库通过其 expose 的适配器
+   * 读写滚动位置与计算阴影；未传入时保持内建 `overflow: auto` 行为。
+   */
+  scrollContainer: Ref<Component | null>
   sessionPrefix: Ref<string>
   iframePath: Ref<string>
   eventBus: Emitter<TabEventPayloadMap>
@@ -42,6 +48,7 @@ export interface CreateStackTabsRuntimeContextOptions {
   iframePath?: string
   maxTabCount?: number
   useGlobalScroll?: boolean
+  scrollContainer?: Component
   sessionPrefix?: string
 }
 
@@ -71,6 +78,8 @@ export const createStackTabsRuntimeContext = (
     ...state,
     maxTabCount: ref(options.maxTabCount ?? state.maxTabCount.value),
     useGlobalScroll: ref(options.useGlobalScroll ?? state.useGlobalScroll.value),
+    // 组件定义不应被深度响应式代理，使用 shallowRef。
+    scrollContainer: shallowRef<Component | null>(options.scrollContainer ?? null),
     sessionPrefix: ref(options.sessionPrefix ?? state.sessionPrefix.value),
     iframePath: ref(options.iframePath ?? ''),
     eventBus: mitt<TabEventPayloadMap>()

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,7 +40,12 @@ interface PageComponentFactoryOptions {
   evictMarkedCaches: () => void
   clearTabEvictionMarks: () => void
   addPageScroller: (pageId: string, ...selectors: string[]) => void
+  setPageScrollAdapter: (
+    pageId: string,
+    getter: (() => StackTabsScrollAdapter | null) | null
+  ) => void
   saveScroller: (pageId: string) => void
+  recordMainScroller: (pageId: string) => void
   restoreScroller: (pageId: string) => void
   removeScroller: (pageId: string) => void
 }
@@ -79,7 +90,9 @@ export const createPageComponentFactory = (options: PageComponentFactoryOptions)
     evictMarkedCaches,
     clearTabEvictionMarks,
     addPageScroller,
+    setPageScrollAdapter,
     saveScroller,
+    recordMainScroller,
     restoreScroller,
     removeScroller
   } = options
@@ -154,6 +167,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 +179,68 @@ 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()
+          // keep-alive 停用会先把 DOM 移入隐藏容器、让 scrollTop 归零，
+          // 因此滚动过程中就要记录位置，不能等到 onDeactivated 再读 DOM。
+          const handleScroll = () => {
+            recordMainScroller(cacheName)
+            listener()
+          }
+          if (adapter?.onScroll) return adapter.onScroll(handleScroll)
+          const element = adapter?.scrollElement
+          if (!element) return () => undefined
+          element.addEventListener('scroll', handleScroll, { passive: true })
+          return () => element.removeEventListener('scroll', handleScroll)
+        }
+
+        // 阴影类挂到不被刷新动画 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 +387,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 +410,9 @@ export const createPageComponentFactory = (options: PageComponentFactoryOptions)
         })
         onActivated(() => {
           context.emit('onLoaded')
+          syncScrollAdapter()
           restoreScroller(cacheName)
-          scrollShadow.sync()
+          scrollShadow.sync(true)
           evictMarkedCaches()
           clearTabEvictionMarks()
           checkAndConsumeBackParams()
@@ -336,12 +426,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 +455,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,45 @@
  *       避免每次 deactivate 都全量 querySelectorAll。
  */
 import type { StackTabsRuntimeContext } from '../stackTabsContext'
+import type { ScrollPosition } from './state'
+import {
+  readAdapterScrollPosition,
+  writeAdapterScrollPosition,
+  type StackTabsScrollAdapter
+} from '../../model/ScrollAdapter'
 
 export interface TabPanelScrollApi {
   restoreScroller: (pageCacheId: string) => void
   saveScroller: (pageCacheId: string) => void
+  /**
+   * 记录主滚动容器的实时位置（由页面滚动事件调用）。
+   *
+   * keep-alive 停用时会先把页面 DOM 移入隐藏容器，原生 scrollTop 随之归零；
+   * 因此不能只在 onDeactivated 时读取 DOM，必须在滚动过程中持续记录。
+   */
+  recordMainScroller: (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 isZeroPosition = (position: ScrollPosition | undefined): boolean =>
+  !position || (position.top === 0 && position.left === 0)
+
 const resolveScrollElement = (selector: string): HTMLElement | null =>
   selector.startsWith('#')
     ? document.getElementById(selector.slice(1))
@@ -88,12 +119,36 @@ 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 recordMainScroller = (pageCacheId: string): void => {
+    const positions = scrollPositionsByPageId.get(pageCacheId)
+    if (!positions) return
+
+    if (adapterGetters.has(pageCacheId)) {
+      const position = readAdapterScrollPosition(getPageAdapter(pageCacheId))
+      if (position) positions.set(MAIN_SCROLLER_KEY, position)
+      return
+    }
+
+    const wrapper =
+      typeof document !== 'undefined' ? document.getElementById(`W-${pageCacheId}`) : null
+    if (!wrapper) return
+    positions.set(`#W-${pageCacheId}`, { top: wrapper.scrollTop, left: wrapper.scrollLeft })
+  }
 
   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 +157,35 @@ 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))
+      const previous = positions.get(MAIN_SCROLLER_KEY)
+      // 停用时滚动元素可能已被移入隐藏容器而读到 0；保留滚动过程中的记录值。
+      if (position && (!isZeroPosition(position) || isZeroPosition(previous))) {
+        positions.set(MAIN_SCROLLER_KEY, position)
+      }
+    }
+
     // 与当前页面 DOM 同步自动标记的容器；移除的元素不保留过期位置。
     for (const key of positions.keys()) {
       if (key.startsWith(AUTO_SCROLLER_PREFIX)) positions.delete(key)
@@ -122,13 +200,17 @@ 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,
-        left: element?.scrollLeft ?? 0
-      })
+      const next = { top: element?.scrollTop ?? 0, left: element?.scrollLeft ?? 0 }
+      const previous = positions.get(selector)
+      // 元素不可用，或停用后读到 0 而此前记录过非零位置时，保留记录值。
+      if (!element || (isZeroPosition(next) && !isZeroPosition(previous))) {
+        if (previous) positions.set(selector, previous)
+        continue
+      }
+      positions.set(selector, next)
     }
   }
 
@@ -138,6 +220,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 +239,30 @@ 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,
+    recordMainScroller,
     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()