vue-stack-tabs 1.3.0 → 1.4.1

package/src/lib/hooks/useScrollShadow.ts

@@ -0,0 +1,124 @@
+/**
+ * useScrollShadow - 为可滚动容器动态切换上下阴影类。
+ *
+ * 职责：在 scroll 事件触发时根据 scrollTop / scrollHeight 边界，
+ *       给目标元素动态加上/移除 stack-tab__shadow-inset-top / -bottom 类，
+ *       距离边界 > 阈值时显示阴影（提示用户"还能往这个方向滚"），
+ *       已贴边（距离边界 ≤ 阈值）时隐藏阴影，避免到顶/到底后阴影残留误导。
+ *
+ * 设计要点：
+ *  - 使用 passive scroll 监听，不阻塞滚动
+ *  - 使用 ResizeObserver 监视子页面缩放/尺寸变化，重新计算阴影边界
+ *  - 使用 rAF 节流，避免一帧内多次写 class
+ *  - 阈值（默认 5px）内视为已贴边（≤ 阈值）→ 隐藏阴影；超过阈值视为可继续滚动 → 显示阴影
+ *  - SSR 安全：在 document 不存在时直接返回
+ *  - 自动清理：onScopeDispose 移除监听并取消 rAF/disconnect observer
+ */
+import { onScopeDispose, type Ref } from 'vue'
+
+const SHADOW_TOP_CLASS = 'stack-tab__shadow-inset-top'
+const SHADOW_BOTTOM_CLASS = 'stack-tab__shadow-inset-bottom'
+const SHADOW_VERTICAL_CLASS = 'stack-tab__shadow-inset-vertical'
+const DEFAULT_EDGE_THRESHOLD = 5
+
+export interface UseScrollShadowOptions {
+  /** 容器元素的 ref，可以是 Ref<HTMLElement | null> 或 getter 函数 */
+  target: Ref<HTMLElement | null> | (() => HTMLElement | null)
+  /**
+   * 是否监听内容缩放/尺寸变化（默认 true）。
+   * 启用后会用 ResizeObserver 监视目标尺寸，容器或子树尺寸变化都会重新计算阴影边界。
+   */
+  watchResize?: boolean
+  /**
+   * 到顶/到底的判定阈值（px，默认 5）。
+   * 距离边界 ≤ 阈值视为已贴边（不显示阴影）；距离边界 > 阈值视为可继续滚动（显示阴影）。
+   */
+  edgeThreshold?: number
+}
+
+export interface UseScrollShadowReturn {
+  /** 手动同步一次（用于内容变化/resize 后） */
+  sync: () => void
+}
+
+const resolveTarget = (
+  target: Ref<HTMLElement | null> | (() => HTMLElement | null)
+): HTMLElement | null => (typeof target === 'function' ? target() : target.value)
+
+export const useScrollShadow = (options: UseScrollShadowOptions): UseScrollShadowReturn => {
+  if (typeof document === 'undefined') {
+    return { sync: () => 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 resizeObserver: ResizeObserver | null = null
+
+  const recompute = (): void => {
+    if (!attached) return
+    const target = attached
+    const { scrollTop, scrollHeight, clientHeight } = target
+    const distanceToTop = scrollTop
+    const distanceToBottom = scrollHeight - clientHeight - scrollTop
+    // 顶部阴影：表示上方还有内容，离开顶部（距离顶部 > 阈值）时显示。
+    // 底部阴影：表示下方还有内容，离开底部（距离底部 > 阈值）时显示。
+    const showTopShadow = distanceToTop > edgeThreshold
+    const showBottomShadow = distanceToBottom > edgeThreshold
+    // 注意：-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)
+  }
+
+  const schedule = (): void => {
+    if (rafId !== null) return
+    rafId = requestAnimationFrame(() => {
+      rafId = null
+      recompute()
+    })
+  }
+
+  const attach = (): void => {
+    const el = resolveTarget(options.target)
+    if (!el || el === attached) return
+    if (attached) {
+      attached.removeEventListener('scroll', schedule)
+      resizeObserver?.disconnect()
+      resizeObserver = null
+    }
+    attached = el
+    el.addEventListener('scroll', schedule, { passive: true })
+    if (watchResize && typeof ResizeObserver !== 'undefined') {
+      resizeObserver = new ResizeObserver(() => schedule())
+      resizeObserver.observe(el)
+    }
+    schedule()
+  }
+
+  const detach = (): void => {
+    if (attached) {
+      attached.removeEventListener('scroll', schedule)
+      attached.classList.remove(SHADOW_TOP_CLASS, SHADOW_BOTTOM_CLASS, SHADOW_VERTICAL_CLASS)
+      attached = null
+    }
+    resizeObserver?.disconnect()
+    resizeObserver = null
+    if (rafId !== null) {
+      cancelAnimationFrame(rafId)
+      rafId = null
+    }
+  }
+
+  // 初始挂载（target 可能是异步插入的 DOM，使用 microtask 等一帧）
+  queueMicrotask(attach)
+
+  onScopeDispose(detach)
+
+  return {
+    sync: () => schedule()
+  }
+}

package/src/lib/hooks/useTabActions.ts

@@ -11,7 +11,7 @@ import {
 } from '../utils/urlParser'
 import type { ITabData, IframeRefreshMode } from '../model/TabModel'
 import { runNavigationTransaction } from './tabPanel/navigationTransaction'
-import { resolveStackTabsRuntimeContext } from './stackTabsContext'
+import { resolveStackTabsRuntimeContext, type StackTabsRuntimeContext } from './stackTabsContext'
 
 /**
  * useTabActions - 标签操作对外 Hook
@@ -26,9 +26,9 @@ import { resolveStackTabsRuntimeContext } from './stackTabsContext'
  * - activeTab(id, isRoute?) 激活标签
  * - reset() 重置（关闭所有）
  */
-export default function useTabActions() {
+export default function useTabActions(providedRuntimeContext?: StackTabsRuntimeContext) {
   const router = useRouter()
-  const runtimeContext = resolveStackTabsRuntimeContext()
+  const runtimeContext = providedRuntimeContext ?? resolveStackTabsRuntimeContext()
   const {
     active,
     hasTab,
@@ -38,11 +38,12 @@ export default function useTabActions() {
     renewTab,
     getTab,
     tabs,
+    moveTab,
     removeTab,
     removeAllTabs,
     refreshTab,
     refreshAllTabs
-  } = useTabPanel()
+  } = useTabPanel(runtimeContext)
 
   /** 合并默认值，生成完整 tabInfo */
   const prepareTabInfo = (tab: ITabData): ITabData => {
@@ -79,7 +80,7 @@ export default function useTabActions() {
       let refreshKeySnapshot: number | undefined
 
       if (tabInfo.id && renew && isExistingTab) {
-        const currentTab = getTab(tab.id!)
+        const currentTab = getTab(tabInfo.id!)
         rollbackRenew = renewTab(tab)
         if (currentTab?.active) {
           refreshKeySnapshot = refreshKey.value
@@ -142,9 +143,19 @@ export default function useTabActions() {
     runtimeContext.iframePath.value = path
   }
 
-  /** 获取当前页面的缓存容器 DOM（用于某些需要直接操作 DOM 的场景） */
-  const getWrapper = () => {
-    return document.getElementsByClassName('cache-page-wrapper')[0]
+  /**
+   * 获取缓存页面容器。
+   * 不传参数时保留旧行为并返回第一个容器；多标签场景应传 tabId 或 pageId，
+   * 避免因 DOM 排序而取得错误页面。
+   */
+  const getWrapper = (
+    target: { tabId?: string; pageId?: string } = {}
+  ): HTMLElement | undefined => {
+    if (typeof document === 'undefined') return undefined
+    const pageId =
+      target.pageId ?? (target.tabId ? getTab(target.tabId)?.pages.peek()?.id : undefined)
+    if (pageId) return document.getElementById(`W-${pageId}`) ?? undefined
+    return document.querySelector<HTMLElement>('.cache-page-wrapper') ?? undefined
   }
 
   /** iframe 标签在新窗口打开（无法嵌入时降级） */
@@ -169,6 +180,7 @@ export default function useTabActions() {
 
     // 激活与重置
     activeTab: active,
+    moveTab,
     reset,
 
     // 数据与配置

package/src/lib/hooks/useTabEventBus.ts

@@ -7,7 +7,7 @@
 import type { InjectionKey } from 'vue'
 import { hasInjectionContext, inject } from 'vue'
 import type { Emitter, EventType } from 'mitt'
-import { resolveStackTabsRuntimeContext } from './stackTabsContext'
+import { resolveStackTabsRuntimeContext, type StackTabsRuntimeContext } from './stackTabsContext'
 
 declare module '@vue/runtime-core' {
   export interface ComponentCustomProperties {
@@ -35,7 +35,9 @@ export interface TabEventPayloadMap extends Record<EventType, unknown> {
 export const tabEmitterKey: InjectionKey<Emitter<TabEventPayloadMap>> = Symbol('tabEmitter')
 
 /** 获取标签事件总线，用于组件间通信 */
-export const useTabEmitter = (): Emitter<TabEventPayloadMap> => {
+export const useTabEmitter = (
+  runtimeContext?: StackTabsRuntimeContext
+): Emitter<TabEventPayloadMap> => {
   const injected = hasInjectionContext() ? inject(tabEmitterKey, null) : null
-  return injected ?? resolveStackTabsRuntimeContext().eventBus
+  return injected ?? runtimeContext?.eventBus ?? resolveStackTabsRuntimeContext().eventBus
 }