vue-stack-tabs 2.2.0 → 2.3.0

package/src/lib/components/TabHeader/TabHeaderScroll.vue

@@ -2,6 +2,10 @@
   TabHeaderScroll - 可横向滚动的标签栏容器
 
   职责：左右箭头滚动、滚轮滚动、自定义滚动条拖拽、确保激活标签在可视区域内
+
+  滚动条是自绘的：原生滚动条隐藏，滚动位置通过 scrollLeft 驱动。
+  滚动过程中滑块位置直接写 DOM（不经过响应式），避免每帧触发组件重渲染、
+  进而重新执行 slot 并 patch 整个标签列表。
 -->
 <template>
   <tab-header-button
@@ -35,11 +39,11 @@
         ref="thumb"
         class="stack-tab__scrollbar-thumb"
         :class="{ 'stack-tab__scrollbar-thumb--dragging': scrollDragging }"
-        :style="{
-          width: `${thumbWidth}px`,
-          transform: `translateX(${thumbLeft}px)`
-        }"
-        @mousedown.prevent="handleScrollbarDragStart"
+        @pointerdown.prevent="handleScrollbarDragStart"
+        @pointermove="handleScrollbarDragMove"
+        @pointerup="handleScrollbarDragEnd"
+        @pointercancel="handleScrollbarDragEnd"
+        @lostpointercapture="handleScrollbarDragEnd"
       />
     </div>
   </div>
@@ -55,8 +59,8 @@
 
 <script lang="ts" setup>
 import { useI18n } from 'vue-i18n-lite'
-import { computed, ref, reactive, onMounted, watch, onUnmounted } from 'vue'
-import type { ScrollData, DragData } from '../../model/TabModel'
+import { ref, onMounted, watch, onUnmounted } from 'vue'
+import type { ScrollData } from '../../model/TabModel'
 import {
   scrollTo as scrollToUtil,
   scrollIntoView as scrollIntoViewUtil
@@ -79,6 +83,8 @@ const isDisabledLeftButton = ref<boolean>(false)
 const isDisabledRightButton = ref<boolean>(false)
 /** 是否显示左右滚动按钮：必须启用按钮模式且内容横向溢出 */
 const isScrollButtonVisible = ref<boolean>(false)
+/** 内容是否超出容器宽度，需要显示滚动条 */
+const hasScroller = ref<boolean>(false)
 /** 外层滚动区域，用于 ResizeObserver */
 const headerScroll = ref<HTMLElement>()
 const props = withDefaults(
@@ -96,66 +102,84 @@ const props = withDefaults(
     isScrollButton: true
   }
 )
-/** 滚动容器尺寸与滚动位置，用于计算滑块和按钮状态 */
-const scrollData = reactive<ScrollData>({
+
+/**
+ * 滚动容器的尺寸与位置。
+ * 刻意保持非响应式：滚动时每帧更新它，若走 reactive 会触发组件重渲染。
+ */
+const scrollData: ScrollData = {
   clientWidth: 0,
   scrollWidth: 0,
   scrollLeft: 0
-})
-/** 拖拽滚动条时的起始状态 */
-const dragData = reactive<DragData>({
-  thumbLeft: 0,
-  startScrollLeft: 0,
-  startThumbLeft: 0,
-  startPageX: 0
-})
-
-/** 滚动数据变化时更新箭头与滚动条的启用状态 */
-watch(scrollData, (data) => {
-  updateScrollButtonState(data)
-})
-
-watch(
-  () => props.isScrollButton,
-  () => updateScrollButtonState(scrollData)
-)
-
-/** 根据滚动位置更新左右箭头禁用状态及滚动按钮可见性 */
-const updateScrollButtonState = (data: ScrollData) => {
-  const hasHorizontalOverflow = data.scrollWidth > data.clientWidth
-
-  isDisabledLeftButton.value = data.scrollLeft <= 10
-  isDisabledRightButton.value = data.clientWidth + data.scrollLeft - data.scrollWidth >= -10
-  isScrollButtonVisible.value = props.isScrollButton && hasHorizontalOverflow
 }
 
-/** 内容是否超出容器宽度，需要显示滚动条 */
-const hasScroller = computed<boolean>(() => {
-  return scrollData.scrollWidth > scrollData.clientWidth
-})
+/** 拖拽起始状态（非响应式，避免 pointermove 触发渲染） */
+const dragData = {
+  startPageX: 0,
+  startThumbLeft: 0
+}
+/** 拖拽指针位置与 rAF 句柄，用于合并高频 pointermove */
+let dragRafId = 0
+let pendingPageX = 0
+let capturedPointerId: number | null = null
 
 /** 滚动条滑块宽度（按内容比例计算） */
-const thumbWidth = computed<number>(() => {
-  if (!hasScroller.value) return 0
-
+const getThumbWidth = (): number => {
   const { clientWidth, scrollWidth } = scrollData
+  if (scrollWidth <= clientWidth || scrollWidth === 0) return 0
+
   return (clientWidth / scrollWidth) * clientWidth
-})
+}
 
 /** 滚动条滑块 left 偏移（与 scrollLeft 对应） */
-const thumbLeft = computed(() => {
-  if (!hasScroller.value) return 0
+const getThumbLeft = (scrollLeft: number): number => {
+  const { clientWidth, scrollWidth } = scrollData
+  const maxScrollLeft = scrollWidth - clientWidth
+  if (maxScrollLeft <= 0) return 0
 
-  const { clientWidth, scrollWidth, scrollLeft } = scrollData
+  return (clientWidth - getThumbWidth()) * (scrollLeft / maxScrollLeft)
+}
 
-  return (clientWidth - thumbWidth.value) * (scrollLeft / (scrollWidth - clientWidth))
-})
+/**
+ * 直接写滑块样式，绕过模板绑定。
+ * 这是滚动路径上唯一的 DOM 写入，不触发组件重渲染。
+ */
+const updateThumb = (scrollLeft: number) => {
+  const thumbEl = thumb.value
+  if (!thumbEl || !hasScroller.value) return
+
+  thumbEl.style.width = `${getThumbWidth()}px`
+  thumbEl.style.transform = `translateX(${getThumbLeft(scrollLeft)}px)`
+}
+
+/** 根据滚动位置更新左右箭头禁用状态 */
+const updateScrollButtonState = () => {
+  isDisabledLeftButton.value = scrollData.scrollLeft <= 10
+  isDisabledRightButton.value =
+    scrollData.clientWidth + scrollData.scrollLeft - scrollData.scrollWidth >= -10
+}
+
+/** 更新溢出判断与滚动按钮可见性 */
+const updateScrollVisibility = () => {
+  hasScroller.value = scrollData.scrollWidth > scrollData.clientWidth
+  isScrollButtonVisible.value = props.isScrollButton && hasScroller.value
+}
 
-/** 更新滚动条数据 */
+/**
+ * 同步容器尺寸与滚动位置。
+ * scroll 与 ResizeObserver 共用：尺寸只在滚动时顺带读取，不写入响应式状态，
+ * 因此不会触发组件重渲染。
+ */
 const updateScrollState = () => {
-  if (!container.value) return
-  const { clientWidth, scrollWidth, scrollLeft } = container.value
-  Object.assign(scrollData, { clientWidth, scrollWidth, scrollLeft })
+  const el = container.value
+  if (!el) return
+
+  scrollData.clientWidth = el.clientWidth
+  scrollData.scrollWidth = el.scrollWidth
+  scrollData.scrollLeft = el.scrollLeft
+  updateScrollVisibility()
+  updateScrollButtonState()
+  updateThumb(scrollData.scrollLeft)
 }
 
 /** 确保激活的标签在可视区域内 */
@@ -170,6 +194,8 @@ const ensureActiveTabInView = () => {
 
 let scrollContainerResizeObserver: ResizeObserver | null = null
 let tabListResizeObserver: ResizeObserver | null = null
+/** 上一次观察到的标签数量，用于区分“标签增删”和普通的尺寸抖动 */
+let lastTabCount = 0
 /** 滚动到指定 left 位置 */
 const scrollTo = (left: number, smooth = true) => {
   scrollToUtil({ wrap: container.value, left, top: 0, smooth })
@@ -181,62 +207,103 @@ const handleScrollButtonClick = (delta: number) => {
 
 const handleWheelScroll = (e: WheelEvent) => {
   if (!props.isScrollWheel || !container.value) return
+  // 触控板横向手势交给原生滚动，避免与下面的定距滚动叠加
+  if (Math.abs(e.deltaX) > Math.abs(e.deltaY)) return
+  if (!e.deltaY) return
 
   const isScrollUp = e.deltaY < 0
   scrollTo(container.value.scrollLeft + (isScrollUp ? -props.space : props.space))
 }
 
-const handleScrollbarDragStart = (e: MouseEvent) => {
-  Object.assign(dragData, {
-    startPageX: e.pageX,
-    startScrollLeft: container.value?.scrollLeft,
-    startThumbLeft: thumbLeft.value,
-    thumbLeft: thumbLeft.value
+/** 应用一次拖拽位移（在 rAF 中执行，合并高频 pointermove） */
+const applyDrag = () => {
+  dragRafId = 0
+  if (!scrollDragging.value || !container.value) return
+
+  const { clientWidth, scrollWidth } = scrollData
+  const maxScrollLeft = scrollWidth - clientWidth
+  const maxThumbLeft = clientWidth - getThumbWidth()
+  if (maxScrollLeft <= 0 || maxThumbLeft <= 0) return
+
+  const thumbLeft = Math.min(
+    Math.max(dragData.startThumbLeft + pendingPageX - dragData.startPageX, 0),
+    maxThumbLeft
+  )
+
+  // 同步滚动与滑块位置，拖拽跟手，不依赖异步 scroll 事件
+  scrollToUtil({
+    wrap: container.value,
+    left: (thumbLeft * maxScrollLeft) / maxThumbLeft,
+    top: 0,
+    smooth: false
   })
+  if (thumb.value) {
+    thumb.value.style.transform = `translateX(${thumbLeft}px)`
+  }
+}
+
+const handleScrollbarDragStart = (e: PointerEvent) => {
+  const thumbEl = thumb.value
+  const isPrimaryButton = e.pointerType !== 'mouse' || e.button === 0
+  if (!thumbEl || !isPrimaryButton) return
+
+  const scrollLeft = container.value?.scrollLeft ?? 0
+  dragData.startPageX = e.pageX
+  dragData.startThumbLeft = getThumbLeft(scrollLeft)
+  pendingPageX = e.pageX
   scrollDragging.value = true
-  document.addEventListener('mousemove', handleScrollbarDragMove)
-  document.addEventListener('mouseup', handleScrollbarDragEnd)
+  capturedPointerId = e.pointerId
+  thumbEl.setPointerCapture?.(e.pointerId)
 }
 
-const handleScrollbarDragMove = (e: MouseEvent) => {
-  const { clientWidth, scrollWidth } = scrollData
-  let thumbLeft = dragData.startThumbLeft + e.pageX - dragData.startPageX
-  const maxThumbLeft = clientWidth - thumbWidth.value
+const handleScrollbarDragMove = (e: PointerEvent) => {
+  if (!scrollDragging.value) return
 
-  if (thumbLeft < 0) {
-    thumbLeft = 0
-  } else if (thumbLeft > maxThumbLeft) {
-    thumbLeft = maxThumbLeft
-  }
-  // 更新滑块定位
-  dragData.thumbLeft = thumbLeft
-  // 滚动
-  scrollTo((thumbLeft * (scrollWidth - clientWidth)) / (clientWidth - thumbWidth.value), false)
-  e.preventDefault()
+  pendingPageX = e.pageX
+  if (dragRafId) return
+  dragRafId = requestAnimationFrame(applyDrag)
 }
 
 const handleScrollbarDragEnd = () => {
+  if (dragRafId) {
+    cancelAnimationFrame(dragRafId)
+    dragRafId = 0
+  }
   scrollDragging.value = false
-  document.removeEventListener('mousemove', handleScrollbarDragMove)
-  document.removeEventListener('mouseup', handleScrollbarDragEnd)
+
+  const pointerId = capturedPointerId
+  capturedPointerId = null
+  const thumbEl = thumb.value
+  if (thumbEl && pointerId !== null && thumbEl.hasPointerCapture?.(pointerId)) {
+    thumbEl.releasePointerCapture(pointerId)
+  }
 }
 
 onMounted(() => {
-  if (typeof ResizeObserver === 'undefined') return
-
-  scrollContainerResizeObserver = new ResizeObserver(() => {
-    updateScrollState()
-    ensureActiveTabInView()
-  })
-  tabListResizeObserver = new ResizeObserver(() => {
-    // 内容溢出（存在滚动条）时才需要在标签增删后纠正滚动位置。
-    if (hasScroller.value) ensureActiveTabInView()
-    updateScrollState()
-  })
+  if (typeof ResizeObserver !== 'undefined') {
+    scrollContainerResizeObserver = new ResizeObserver(() => {
+      updateScrollState()
+      ensureActiveTabInView()
+    })
+    tabListResizeObserver = new ResizeObserver(() => {
+      // 只有标签增删（数量变化）才需要纠正滚动位置。
+      // hover 展开关闭按钮、标题动态变化等也会改变列表宽度并触发本回调，
+      // 若此时无条件 ensureActiveTabInView，会把用户主动滚开的标签栏强行拉回 active 标签。
+      const tabCount = container.value?.querySelectorAll('.stack-tab__item').length ?? 0
+      const tabCountChanged = tabCount !== lastTabCount
+      lastTabCount = tabCount
+
+      if (hasScroller.value && tabCountChanged) ensureActiveTabInView()
+      updateScrollState()
+    })
+
+    if (headerScroll.value) scrollContainerResizeObserver.observe(headerScroll.value)
+    const tabNav = container.value?.querySelector('.stack-tab__nav')
+    lastTabCount = container.value?.querySelectorAll('.stack-tab__item').length ?? 0
+    if (tabNav) tabListResizeObserver.observe(tabNav)
+  }
 
-  if (headerScroll.value) scrollContainerResizeObserver.observe(headerScroll.value)
-  const tabNav = container.value?.querySelector('.stack-tab__nav')
-  if (tabNav) tabListResizeObserver.observe(tabNav)
+  updateScrollState()
 })
 onUnmounted(() => {
   handleScrollbarDragEnd()
@@ -246,6 +313,13 @@ onUnmounted(() => {
   tabListResizeObserver = null
 })
 
+watch(
+  () => props.isScrollButton,
+  () => {
+    isScrollButtonVisible.value = props.isScrollButton && hasScroller.value
+  }
+)
+
 const scrollIntoView = (el: HTMLElement) => {
   scrollIntoViewUtil({ el, wrap: container.value, block: 'end', inline: 'center' })
 }

package/src/lib/components/TabHeader/index.vue

@@ -23,13 +23,10 @@
           <tab-header-item
             v-for="(item, index) in tabs"
             :key="item.id"
-            :item="item as ITabItem"
+            :item="item"
             :drop-position="dropIndicator?.tabId === item.id ? dropIndicator.position : undefined"
-            @contextmenu="
-              (e: MouseEvent) =>
-                handleTabContextMenu(e, item as unknown as ITabItem, index, tabs.length)
-            "
-            @click.middle.prevent="handleCloseTab(item as ITabItem)"
+            @contextmenu="(e: MouseEvent) => handleTabContextMenu(e, item, index, tabs.length)"
+            @click.middle.prevent="handleCloseTab(item)"
             @close="handleCloseTab"
             @active="handleActivateTab"
             @dragstart="handleTabDragStart"
@@ -75,7 +72,7 @@
   依赖：useTabActions(tabs/closeTab/activeTab)、useContextMenu
 -->
 <script lang="ts" setup>
-import { inject, computed, ref, nextTick } from 'vue'
+import { inject, computed, ref, nextTick, watch, onUnmounted } from 'vue'
 import type { TransitionProps } from 'vue'
 import { TabScrollMode } from '../../model/TabModel'
 import type { IContextMenu, ITabItem } from '../../model/TabModel'
@@ -87,6 +84,7 @@ import TabHeaderScroll from './TabHeaderScroll.vue'
 import TabHeaderButton from './TabHeaderButton.vue'
 import { useI18n } from 'vue-i18n-lite'
 import { maximumKey } from '../../hooks/stackTabsContext'
+import { TabEventType, useTabEmitter } from '../../hooks/useTabEventBus'
 const { t } = useI18n()
 /** 是否最大化，由上层 provide */
 const maximum = inject(maximumKey, ref(false))
@@ -121,6 +119,47 @@ const props = withDefaults(
   }
 )
 const { closeTab, activeTab, moveTab, tabs } = useTabActions()
+
+/** 当前激活标签 id */
+const activeTabId = computed<string>(() => tabs.value.find((tab) => tab.active)?.id ?? '')
+
+/**
+ * 将指定标签滚动到可视区域；未指定 id 时使用当前激活标签。
+ * 仅在标签确实不可见时才滚动，避免干扰用户的手动滚动。
+ */
+const ensureTabInView = (tabId?: string) => {
+  const scrollContainer = scrollContainerRef.value
+  if (!scrollContainer) return
+
+  const target = headerRef.value?.querySelector<HTMLElement>(
+    tabId
+      ? `.stack-tab__nav [role="tab"][data-tab-id="${CSS.escape(tabId)}"]`
+      : '.stack-tab__nav .stack-tab__item--active'
+  )
+  const tabElement = target?.closest<HTMLElement>('.stack-tab__item')
+  if (tabElement && !scrollContainer.isInView(tabElement)) {
+    scrollContainer.scrollIntoView(tabElement)
+  }
+}
+
+/**
+ * 激活标签变化后确保其位于可视区域：
+ * 覆盖新开标签、通过 openTab 唤醒已有标签、关闭标签后顺延激活等场景。
+ * 仅响应用户主动滚动时不会触发（滚动不改变 active），因此不会把视图强行拉回。
+ */
+watch(activeTabId, () => {
+  nextTick(() => ensureTabInView())
+})
+
+/** 标签已是 active 但被滚开时，显式打开/激活请求仍需把标签栏滚动到它。 */
+const emitter = useTabEmitter()
+const handleTabScrollTo = ({ id }: { id: string }) => {
+  nextTick(() => ensureTabInView(id))
+}
+emitter.on(TabEventType.TAB_SCROLL_TO, handleTabScrollTo)
+onUnmounted(() => {
+  emitter.off(TabEventType.TAB_SCROLL_TO, handleTabScrollTo)
+})
 const draggingTabId = ref<string | null>(null)
 type DropPosition = 'before' | 'after'
 const dropIndicator = ref<{ tabId: string; position: DropPosition } | null>(null)
@@ -219,7 +258,7 @@ const handleTabListDragOver = (event: DragEvent) => {
 const handleTabListDrop = (event: DragEvent) => {
   if (isTabItemDragEvent(event)) return
   const lastTab = tabs.value[tabs.value.length - 1]
-  if (lastTab) handleTabDrop(lastTab as ITabItem)
+  if (lastTab) handleTabDrop(lastTab)
 }
 
 /** 标签列表 transition 的 props，支持 string 或对象 */
@@ -248,7 +287,7 @@ const focusTabById = (tabId: string) => {
 const activateTabByIndex = (index: number) => {
   const item = tabs.value[index]
   if (!item) return
-  handleActivateTab(item as ITabItem, undefined, true)
+  handleActivateTab(item, undefined, true)
   focusTabById(String(item.id))
 }
 
@@ -317,7 +356,9 @@ const handleActivateTab = (
   Promise.resolve(activeTab(item.id, isRoute))
     .then(() => emit('active', item.id))
     .catch((error: unknown) => {
-      console.warn('[vue-stack-tabs] Failed to activate tab:', error)
+      if (!import.meta.env.PROD) {
+        console.warn('[vue-stack-tabs] Failed to activate tab:', error)
+      }
     })
 }
 </script>

package/src/lib/hooks/stackTabsContext.ts

@@ -23,7 +23,6 @@ export const STACK_TABS_DUPLICATE_INSTANCE_MESSAGE =
 
 export interface StackTabsRuntimeContext {
   tabs: Ref<ITabItem[]>
-  defaultTabs: Ref<ITabItem[]>
   caches: ShallowRef<string[]>
   components: Map<string, DefineComponent>
   cacheIdsToEvict: Set<string>

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

@@ -9,8 +9,11 @@ import type { StackTabsRuntimeContext } from '../stackTabsContext'
 
 export interface TabPanelEvictionApi {
   markCacheForEviction: (cacheName: string) => void
-  markTabPagesForEviction: (tab: { id: string; pages: { list(): ITabPage[] } }) => void
-  markTabPagesForEvictionOnly: (tab: { pages: { list(): ITabPage[] } }) => void
+  markTabPagesForEviction: (tab: {
+    id: string
+    pages: { readonlyList(): readonly ITabPage[] }
+  }) => void
+  markTabPagesForEvictionOnly: (tab: { pages: { readonlyList(): readonly ITabPage[] } }) => void
   addCache: (cacheName: string) => void
   removeCache: (cacheName: string) => void
   evictPageCache: (cacheName: string) => void
@@ -39,13 +42,18 @@ export const createTabPanelEviction = (context: StackTabsRuntimeContext): TabPan
     cacheIdsToEvict.add(cacheName)
   }
 
-  const markTabPagesForEviction = (tab: { id: string; pages: { list(): ITabPage[] } }): void => {
-    for (const page of tab.pages.list()) markCacheForEviction(page.id)
+  const markTabPagesForEviction = (tab: {
+    id: string
+    pages: { readonlyList(): readonly ITabPage[] }
+  }): void => {
+    for (const page of tab.pages.readonlyList()) markCacheForEviction(page.id)
     tabIdsToEvict.add(tab.id)
   }
 
-  const markTabPagesForEvictionOnly = (tab: { pages: { list(): ITabPage[] } }): void => {
-    for (const page of tab.pages.list()) markCacheForEviction(page.id)
+  const markTabPagesForEvictionOnly = (tab: {
+    pages: { readonlyList(): readonly ITabPage[] }
+  }): void => {
+    for (const page of tab.pages.readonlyList()) markCacheForEviction(page.id)
   }
 
   const addCache = (cacheName: string): void => {