vue-stack-tabs 1.4.2 → 2.3.0

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

@@ -7,58 +7,58 @@
 <template>
   <div
     ref="menuElementRef"
-    class="stack-tab__contextmenu"
+    class="stack-tab__context-menu"
     role="menu"
     tabindex="-1"
     :style="{
       left: `${menuPosition.left}px`,
       top: `${menuPosition.top}px`,
-      'z-index': menuZIndex()
+      'z-index': menuZIndexValue
     }"
     @keydown="handleMenuKeydown"
   >
     <context-menu-item
-      icon="stack-tab__icon-reload svg-mask"
+      icon="stack-tab__icon stack-tab__icon--reload stack-tab__icon--mask"
       :title="t('VueStackTab.reload')"
       :disabled="!tabItem.refreshable"
       @click="handleMenuItemClick(() => refreshTab(tabItem.id))"
     />
     <context-menu-item
-      icon="stack-tab__icon-reload-all svg-mask"
+      icon="stack-tab__icon stack-tab__icon--reload-all stack-tab__icon--mask"
       :title="t('VueStackTab.reloadAll')"
       @click="handleMenuItemClick(refreshAllTabs)"
     />
     <context-menu-item
-      icon="stack-tab__icon-close svg-mask"
+      icon="stack-tab__icon stack-tab__icon--close stack-tab__icon--mask"
       :title="t('VueStackTab.close')"
       :disabled="!tabItem.closable"
       @click="handleMenuItemClick(() => closeTab(tabItem.id))"
     />
     <context-menu-item
-      icon="stack-tab__icon-close-lefts svg-mask"
+      icon="stack-tab__icon stack-tab__icon--close-lefts stack-tab__icon--mask"
       :title="t('VueStackTab.closeLeft')"
       :disabled="index <= 0"
       @click="handleMenuItemClick(() => removeLeftTabs(tabItem.id))"
     />
     <context-menu-item
-      icon="stack-tab__icon-close-rights svg-mask"
+      icon="stack-tab__icon stack-tab__icon--close-rights stack-tab__icon--mask"
       :title="t('VueStackTab.closeRight')"
       :disabled="index >= max - 1"
       @click="handleMenuItemClick(() => removeRightTabs(tabItem.id))"
     />
     <context-menu-item
-      icon="stack-tab__icon-close-others svg-mask"
+      icon="stack-tab__icon stack-tab__icon--close-others stack-tab__icon--mask"
       :title="t('VueStackTab.closeOthers')"
       @click="handleMenuItemClick(() => removeOtherTabs(tabItem.id))"
     />
     <context-menu-item
-      icon="stack-tab__icon-close-all svg-mask"
+      icon="stack-tab__icon stack-tab__icon--close-all stack-tab__icon--mask"
       :title="t('VueStackTab.closeAll')"
       @click="handleMenuItemClick(closeAllTabs)"
     />
     <context-menu-item
       v-if="tabItem.iframe && tabItem.url"
-      icon="stack-tab__icon-open svg-mask"
+      icon="stack-tab__icon stack-tab__icon--open stack-tab__icon--mask"
       :title="t('VueStackTab.openInNewWindow')"
       @click="handleMenuItemClick(() => openInNewWindow(tabItem.id))"
     />
@@ -115,13 +115,8 @@ const menuPosition = reactive({ left: props.left, top: props.top })
 const { closeTab, closeAllTabs, refreshTab, refreshAllTabs, openInNewWindow } = useTabActions()
 const { removeLeftTabs, removeRightTabs, removeOtherTabs } = useTabPanel()
 
-/**
- * 菜单挂载时 z-index 必须重新计算（DOM 层叠已变化），先用 invalidateZIndexCache 失效再读取。
- */
-const menuZIndex = () => {
-  invalidateZIndexCache('.stack-tab,.stack-tab *')
-  return getMaxZIndex('.stack-tab,.stack-tab *')
-}
+/** 菜单挂载时计算一次 z-index；菜单打开期间层叠关系不会变化。 */
+const menuZIndexValue = ref(0)
 
 const focusActiveTabFallback = () => {
   const activeTab = document.querySelector<HTMLElement>('[role="tab"][aria-selected="true"]')
@@ -204,12 +199,20 @@ const handleMenuKeydown = (event: KeyboardEvent) => {
 const getCustomMenuKey = (item: IContextMenu): string =>
   item.key ?? `${item.title}-${item.icon ?? ''}`
 
-/** 挂载后修正菜单位置，避免超出右边界 */
+/** 挂载后计算 z-index 并修正右/下边界，避免菜单溢出视口 */
 onMounted(() => {
-  const menuWidth = menuElementRef.value?.clientWidth ?? 0
+  invalidateZIndexCache('.stack-tab,.stack-tab *')
+  menuZIndexValue.value = getMaxZIndex('.stack-tab,.stack-tab *')
+
+  const menuElement = menuElementRef.value
+  const menuWidth = menuElement?.clientWidth ?? 0
+  const menuHeight = menuElement?.clientHeight ?? 0
   if (menuPosition.left + menuWidth > window.innerWidth) {
     menuPosition.left = window.innerWidth - menuWidth - 5
   }
+  if (menuPosition.top + menuHeight > window.innerHeight) {
+    menuPosition.top = Math.max(0, window.innerHeight - menuHeight - 5)
+  }
   focusMenuItem(0)
 })
 </script>

package/src/lib/components/PageLoading.vue

@@ -7,28 +7,23 @@
 <template>
   <div
     v-if="isLoading"
-    class="stack-tab-loading-mask"
+    class="stack-tab-loading__mask"
     role="status"
     aria-live="polite"
     :aria-label="t('VueStackTab.loading')"
-    :style="{ zIndex: loadingZIndex() }"
+    :style="{ zIndex: loadingZIndex }"
   >
-    <div class="stack-tab-loading--spin turn" aria-hidden="true" />
+    <div class="stack-tab-loading__spin" aria-hidden="true" />
   </div>
 </template>
 <script setup lang="ts">
-import { ref, onUnmounted } from 'vue'
+import { ref, onUnmounted, watch } from 'vue'
 import { useI18n } from 'vue-i18n-lite'
 import { TabEventType, useTabEmitter } from '../hooks/useTabEventBus'
 import { getMaxZIndex, invalidateZIndexCache } from '../utils/scrollUtils'
 
-/**
- * loading 遮罩每次显隐都会改变 .cache-page-wrapper 子树层叠，先失效缓存再读取避免旧值。
- */
-const loadingZIndex = () => {
-  invalidateZIndexCache('.cache-page-wrapper *')
-  return getMaxZIndex('.cache-page-wrapper *')
-}
+/** 遮罩显示时的层叠值；只在显示时计算一次，避免每次重渲染都全量扫描 DOM。 */
+const loadingZIndex = ref(0)
 const props = defineProps<{
   /** 当前标签 id，用于过滤 PAGE_LOADING 事件 */
   tabId: string
@@ -37,6 +32,12 @@ const { t } = useI18n()
 const emitter = useTabEmitter()
 /** 是否显示 loading 遮罩 */
 const isLoading = ref<boolean>(false)
+watch(isLoading, (loading) => {
+  if (!loading) return
+  // 遮罩显隐会改变 .stack-tab__cache-page-wrapper 子树层叠，先失效缓存再读取避免旧值。
+  invalidateZIndexCache('.stack-tab__cache-page-wrapper *')
+  loadingZIndex.value = getMaxZIndex('.stack-tab__cache-page-wrapper *')
+})
 /** 处理 PAGE_LOADING 事件，仅当 tId 匹配时更新 */
 const handleLoadingEvent = (payload: { tId: string; value: boolean }) => {
   if (payload.tId === props.tabId) {

package/src/lib/components/StackKeepAlive/StackCacheRenderer.vue

@@ -25,8 +25,6 @@ interface StackCacheRendererProps {
 interface StackCacheRendererSlotProps {
   wrappedComponent: DefineComponent
   activeCacheKey: string
-  refreshKey: number
-  activePageRefreshVersion: number
   component?: VNode | null
 }
 
@@ -36,7 +34,7 @@ defineSlots<{
   default(props: StackCacheRendererSlotProps): unknown
 }>()
 
-const { refreshKey, activeCacheKey, activePageRefreshVersion, addPage } = useTabPanel()
+const { refreshKey, activeCacheKey, addPage } = useTabPanel()
 
 const wrappedComponent = shallowRef<DefineComponent>(getEmptyPlaceholderComponent())
 
@@ -57,8 +55,6 @@ watch(
   <slot
     :wrapped-component="wrappedComponent"
     :active-cache-key="activeCacheKey"
-    :refresh-key="refreshKey"
-    :active-page-refresh-version="activePageRefreshVersion"
     :component="component"
   />
 </template>

package/src/lib/components/StackKeepAlive/StackKeepAlive.vue

@@ -27,7 +27,7 @@ const emit = defineEmits<{
   loaded: []
 }>()
 
-const { caches } = useTabPanel()
+const { caches, getPageRefreshVersion } = useTabPanel()
 
 /** 页面组件加载完成时向父组件转发 */
 const emitLoaded = () => {
@@ -38,7 +38,7 @@ const emitLoaded = () => {
 <template>
   <router-view v-slot="{ Component, route }">
     <StackCacheRenderer
-      v-slot="{ wrappedComponent, activeCacheKey, activePageRefreshVersion, component }"
+      v-slot="{ wrappedComponent, activeCacheKey, component }"
       :route="route"
       :component="Component"
     >
@@ -46,8 +46,10 @@ const emitLoaded = () => {
         <keep-alive :include="caches">
           <component
             :is="wrappedComponent"
-            :key="`${activeCacheKey}-${activePageRefreshVersion}`"
+            :key="activeCacheKey"
             :vnode="component"
+            :refresh-version="getPageRefreshVersion(activeCacheKey)"
+            :transition-name="transitionName"
             @on-loaded="emitLoaded"
           />
         </keep-alive>

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

@@ -4,13 +4,14 @@
     role="presentation"
     class="stack-tab__item"
     :class="{
-      'is-active': item.active,
-      'is-icon': item.closable,
-      'is-dragging': dragging,
-      'is-drop-before': dropPosition === 'before',
-      'is-drop-after': dropPosition === 'after'
+      'stack-tab__item--active': item.active,
+      'stack-tab__item--closable': item.closable,
+      'stack-tab__item--pinned': item.pinned,
+      'stack-tab__item--dragging': dragging,
+      'stack-tab__item--drop-before': dropPosition === 'before',
+      'stack-tab__item--drop-after': dropPosition === 'after'
     }"
-    :draggable="true"
+    :draggable="!item.pinned"
     @click.self="handleActivate(true)"
     @contextmenu="$emit('contextmenu', $event)"
     @dragstart="handleDragStart"
@@ -40,7 +41,7 @@
     <button
       v-if="item.closable"
       type="button"
-      class="stack-tab__icon-close-fill stack-tab__item-button"
+      class="stack-tab__icon stack-tab__icon--close-fill stack-tab__item-button"
       :title="t('VueStackTab.close')"
       :aria-label="`${t('VueStackTab.close')} ${title}`"
       :tabindex="item.active ? 0 : -1"
@@ -99,6 +100,11 @@ const handleClose = () => {
   emit('close', props.item)
 }
 const handleDragStart = (event: DragEvent) => {
+  // pinned 标签（home）固定在左侧，不参与拖拽。
+  if (props.item.pinned) {
+    event.preventDefault()
+    return
+  }
   dragging.value = true
   event.dataTransfer?.setData('text/plain', props.item.id)
   if (event.dataTransfer) event.dataTransfer.effectAllowed = 'move'

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

@@ -2,11 +2,15 @@
   TabHeaderScroll - 可横向滚动的标签栏容器
 
   职责：左右箭头滚动、滚轮滚动、自定义滚动条拖拽、确保激活标签在可视区域内
+
+  滚动条是自绘的：原生滚动条隐藏，滚动位置通过 scrollLeft 驱动。
+  滚动过程中滑块位置直接写 DOM（不经过响应式），避免每帧触发组件重渲染、
+  进而重新执行 slot 并 patch 整个标签列表。
 -->
 <template>
   <tab-header-button
     v-if="isScrollButtonVisible"
-    icon-class="stack-tab__icon-left-arrow"
+    icon-class="stack-tab__icon stack-tab__icon--left-arrow"
     :disabled="isDisabledLeftButton"
     :title="t('VueStackTab.scrollLeft')"
     :aria-label="t('VueStackTab.scrollLeft')"
@@ -29,23 +33,23 @@
       v-show="hasScroller"
       ref="bar"
       class="stack-tab__scrollbar"
-      :class="{ 'is-dragging': scrollDragging }"
+      :class="{ 'stack-tab__scrollbar--dragging': scrollDragging }"
     >
       <div
         ref="thumb"
         class="stack-tab__scrollbar-thumb"
-        :class="{ 'is-dragging': scrollDragging }"
-        :style="{
-          width: `${thumbWidth}px`,
-          transform: `translateX(${thumbLeft}px)`
-        }"
-        @mousedown.prevent="handleScrollbarDragStart"
+        :class="{ 'stack-tab__scrollbar-thumb--dragging': scrollDragging }"
+        @pointerdown.prevent="handleScrollbarDragStart"
+        @pointermove="handleScrollbarDragMove"
+        @pointerup="handleScrollbarDragEnd"
+        @pointercancel="handleScrollbarDragEnd"
+        @lostpointercapture="handleScrollbarDragEnd"
       />
     </div>
   </div>
   <tab-header-button
     v-if="isScrollButtonVisible"
-    icon-class="stack-tab__icon-right-arrow"
+    icon-class="stack-tab__icon stack-tab__icon--right-arrow"
     :disabled="isDisabledRightButton"
     :title="t('VueStackTab.scrollRight')"
     :aria-label="t('VueStackTab.scrollRight')"
@@ -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,72 +102,90 @@ 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)
 }
 
 /** 确保激活的标签在可视区域内 */
 const ensureActiveTabInView = () => {
   const activeTabEl = container.value?.querySelector(
-    '.stack-tab__item.is-active'
+    '.stack-tab__item--active'
   ) as HTMLElement | null
   if (activeTabEl && !isInView(activeTabEl)) {
     scrollIntoView(activeTabEl)
@@ -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,69 +207,119 @@ 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()
   scrollContainerResizeObserver?.disconnect()
   tabListResizeObserver?.disconnect()
   scrollContainerResizeObserver = null
   tabListResizeObserver = null
 })
 
+watch(
+  () => props.isScrollButton,
+  () => {
+    isScrollButtonVisible.value = props.isScrollButton && hasScroller.value
+  }
+)
+
 const scrollIntoView = (el: HTMLElement) => {
   scrollIntoViewUtil({ el, wrap: container.value, block: 'end', inline: 'center' })
 }