vue-stack-tabs 1.3.0 → 1.4.1

package/package.json

@@ -1,13 +1,17 @@
 {
   "name": "vue-stack-tabs",
-  "version": "1.3.0",
-  "packageManager": "pnpm@11.5.0+sha512.dbfcc4f81cf48597afd4bc391ffdf12c11f1a9fb83a395bfa6b0a2d9cc2fd8ffebafdb1ccbd529632153f793904c2615b7f09fe1a345473fd1c35845172a8eb1",
+  "version": "1.4.1",
   "private": false,
   "type": "module",
+  "description": "Vue 3 multi-tab manager built on Vue Router with iframe-like tab isolation: per-tab component scope, stack-based forward/backward navigation, keep-alive page caching, scroll position memory, i18n and a Nuxt 3/4 module.",
   "files": [
     "src/lib",
     "dist"
   ],
+  "sideEffects": [
+    "**/*.css",
+    "**/*.scss"
+  ],
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -25,7 +29,9 @@
     "./dist/vue-stack-tabs.css": "./dist/vue-stack-tabs.css"
   },
   "peerDependencies": {
-    "nuxt": "^3.0.0 || ^4.0.0"
+    "nuxt": "^3.0.0 || ^4.0.0",
+    "vue": "^3.5.43",
+    "vue-router": "^5.4.0"
   },
   "peerDependenciesMeta": {
     "nuxt": {
@@ -34,6 +40,7 @@
   },
   "main": "./dist/vue-stack-tabs.es.js",
   "module": "./dist/vue-stack-tabs.es.js",
+  "types": "./dist/index.d.ts",
   "typings": "./dist/index.d.ts",
   "repository": {
     "type": "git",
@@ -41,20 +48,39 @@
   },
   "keywords": [
     "vue",
-    "vue router",
+    "vue3",
+    "vue-router",
+    "router",
     "tabs",
-    "nuxt"
+    "tab",
+    "tab-panel",
+    "multi-tab",
+    "tabs-router",
+    "keep-alive",
+    "cache",
+    "iframe",
+    "nuxt",
+    "nuxt3",
+    "nuxt-module",
+    "navigation",
+    "vue-component",
+    "typescript"
   ],
   "author": "tantan",
-  "license": "Apache License, Version 2.0",
+  "license": "Apache-2.0",
   "bugs": {
     "url": "https://github.com/jktantan/vue-stack-tabs/issues"
   },
-  "homepage": "https://github.com/jktantan/vue-stack-tabs.git",
+  "homepage": "https://jktantan.github.io/vue-stack-tabs/",
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "clean:ports": "node -e \"const { execSync } = require('child_process'); try { if (process.platform === 'win32') { execSync('netstat -ano | findstr \":5173\" | findstr \"LISTENING\"').toString().split('\\n').forEach(line => { const pid = line.trim().split(/\\s+/)[4]; if (pid) try { execSync(`taskkill /F /PID ${pid}`, { stdio: 'ignore' }); } catch(e) {} }); execSync('netstat -ano | findstr \":5174\" | findstr \"LISTENING\"').toString().split('\\n').forEach(line => { const pid = line.trim().split(/\\s+/)[4]; if (pid) try { execSync(`taskkill /F /PID ${pid}`, { stdio: 'ignore' }); } catch(e) {} }); } else { execSync('lsof -ti:5173 | xargs kill -9 || true', { shell: '/bin/bash' }); execSync('lsof -ti:5174 | xargs kill -9 || true', { shell: '/bin/bash' }); } console.log('✅ 端口清理完成'); } catch(e) { console.log('✅ 端口已经空闲或清理完成'); }\"",
-    "docs:dev": "vitepress dev docs",
-    "docs:build": "vitepress build docs && vite build --config vite.config.docs-demo.ts && node -e \"const fs=require('fs');const p='docs/.vitepress/dist/demo';fs.mkdirSync(p+'/demo',{recursive:true});fs.copyFileSync(p+'/index.html',p+'/demo/index.html');\"",
+    "docs:dev": "run-p docs:dev:docs docs:dev:demo",
+    "docs:dev:docs": "vitepress dev docs",
+    "docs:dev:demo": "vite --config vite.config.docs-demo.ts",
+    "docs:build": "vitepress build docs && vite build --config vite.config.docs-demo.ts",
     "dev": "vite  --host ",
     "build": "run-p type-check \"build-only {@}\" --",
     "preview": "vite preview",
@@ -64,83 +90,81 @@
     "lint:check": "eslint .",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
-    "lib:build": "vite --config vite.config.lib.ts build && vite --config vite.config.iframe-bridge.ts build && vite --config vite.config.nuxt.ts build && node -e \"const fs=require('fs');fs.copyFileSync('dist/vue-stack-tabs.css','dist/style.css');fs.copyFileSync('dist/src/lib/iframe-bridge.d.ts','dist/iframe-bridge.d.ts');fs.mkdirSync('dist/utils',{recursive:true});fs.copyFileSync('dist/src/lib/utils/iframeBridge.d.ts','dist/utils/iframeBridge.d.ts');fs.mkdirSync('dist/nuxt',{recursive:true});fs.copyFileSync('dist/src/lib/nuxt/module.d.ts','dist/nuxt/module.d.ts');fs.mkdirSync('dist/nuxt/runtime',{recursive:true});fs.copyFileSync('dist/src/lib/nuxt/runtime/plugin.d.ts','dist/nuxt/runtime/plugin.d.ts');fs.copyFileSync('dist/nuxt/plugin.mjs','dist/nuxt/runtime/plugin.mjs')\"",
+    "lib:build": "vite --config vite.config.lib.ts build && vite --config vite.config.iframe-bridge.ts build && vite --config vite.config.nuxt.ts build && node -e \"const fs=require('fs');fs.copyFileSync('dist/vue-stack-tabs.css','dist/style.css');fs.rmSync('dist/src',{recursive:true,force:true});\"",
     "test": "vitest run",
     "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage",
-    "test:prepack": "node scripts/verify-prepack.mjs",
-    "test:packaged": "pnpm run lib:build && node scripts/verify-packaged.mjs"
+    "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
     "defu": "^6.1.7",
     "mitt": "^3.0.1",
+    "nostics": "^1.3.0",
     "throttle-debounce": "^5.0.2",
-    "vue": "^3.5.35",
-    "vue-i18n-lite": "^1.0.2",
-    "vue-router": "^5.1.0"
+    "vue-i18n-lite": "^1.0.2"
   },
   "devDependencies": {
-    "@ctrl/tinycolor": "^4.2.0",
+    "@ctrl/tinycolor": "^4.2.1",
     "@element-plus/icons-vue": "^2.3.2",
     "@eslint/js": "^10.0.1",
-    "@floating-ui/core": "^1.7.5",
-    "@floating-ui/dom": "^1.7.6",
-    "@floating-ui/utils": "^0.2.11",
-    "@mdit/plugin-tasklist": "^0.23.2",
+    "@floating-ui/core": "^1.8.0",
+    "@floating-ui/dom": "^1.8.0",
+    "@floating-ui/utils": "^0.2.12",
+    "@mdit/plugin-tasklist": "^1.1.3",
     "@popperjs/core": "^2.11.8",
     "@rushstack/eslint-patch": "^1.16.1",
-    "@tsconfig/node20": "^20.1.9",
+    "@tsconfig/node26": "^26.0.1",
     "@types/lodash-es": "^4.17.12",
-    "@types/node": "^25.9.1",
+    "@types/node": "^26.6.5",
     "@types/throttle-debounce": "^5.0.2",
-    "@vitejs/plugin-vue": "^6.0.7",
-    "@vitejs/plugin-vue-jsx": "^5.1.5",
-    "@vitest/coverage-v8": "4.1.7",
-    "@vue/compiler-core": "^3.5.35",
-    "@vue/compiler-dom": "^3.5.35",
-    "@vue/devtools-api": "^8.1.2",
-    "@vue/devtools-kit": "^8.1.2",
-    "@vue/devtools-shared": "^8.1.2",
+    "@vitejs/plugin-vue": "^6.0.10",
+    "@vitejs/plugin-vue-jsx": "^5.1.6",
+    "@vitest/coverage-v8": "4.1.10",
+    "@vue/compiler-core": "^3.5.43",
+    "@vue/compiler-dom": "^3.5.43",
+    "@vue/devtools-api": "^8.2.1",
+    "@vue/devtools-kit": "^8.2.1",
+    "@vue/devtools-shared": "^8.2.1",
     "@vue/eslint-config-prettier": "^10.2.0",
-    "@vue/eslint-config-typescript": "^14.7.0",
-    "@vue/reactivity": "^3.5.35",
-    "@vue/runtime-core": "^3.5.35",
-    "@vue/runtime-dom": "^3.5.35",
-    "@vue/shared": "^3.5.35",
-    "@vue/test-utils": "^2.4.10",
+    "@vue/eslint-config-typescript": "^14.9.0",
+    "@vue/reactivity": "^3.5.43",
+    "@vue/runtime-core": "^3.5.43",
+    "@vue/runtime-dom": "^3.5.43",
+    "@vue/shared": "^3.5.43",
+    "@vue/test-utils": "^2.5.1",
     "@vue/tsconfig": "^0.9.1",
-    "@vueuse/core": "^14.3.0",
-    "@vueuse/shared": "^14.3.0",
+    "@vueuse/core": "^14.4.0",
+    "@vueuse/shared": "^14.4.0",
     "async-validator": "^4.2.5",
-    "birpc": "^4.0.0",
-    "dayjs": "^1.11.21",
-    "element-plus": "^2.14.1",
-    "eslint": "^10.4.1",
+    "birpc": "^4.2.0",
+    "dayjs": "^1.11.23",
+    "element-plus": "^2.14.7",
+    "eslint": "^10.12.0",
     "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-vue": "^10.9.1",
-    "globals": "^17.6.0",
-    "happy-dom": "^20.9.0",
-    "hookable": "^6.1.1",
+    "eslint-plugin-vue": "^10.11.1",
+    "globals": "^17.13.0",
+    "happy-dom": "^20.14.6",
+    "hookable": "^6.1.2",
     "lodash-es": "^4.18.1",
     "lodash-unified": "^1.0.3",
     "memoize-one": "^6.0.0",
     "normalize-wheel-es": "^1.2.0",
     "normalize.css": "^8.0.1",
-    "npm-run-all2": "^9.0.1",
+    "npm-run-all2": "^9.0.3",
     "perfect-debounce": "^2.1.0",
-    "prettier": "^3.8.3",
-    "sass": "^1.100.0",
-    "sass-loader": "^17.0.0",
-    "terser": "^5.48.0",
-    "typescript": "~6.0.3",
-    "typescript-eslint": "^8.60.0",
-    "unplugin-auto-import": "^21.0.0",
+    "prettier": "^3.9.10",
+    "sass-embedded": "^1.105.1",
+    "terser": "^5.51.2",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.71.1",
+    "unplugin-auto-import": "^21.1.0",
     "unplugin-vue-components": "^32.1.0",
-    "vite": "^8.0.14",
-    "vite-plugin-dts": "5.0.1",
+    "vite": "^8.3.4",
+    "vite-plugin-dts": "5.0.3",
     "vite-plugin-package-version": "^1.1.0",
     "vitepress": "^1.6.4",
-    "vitest": "^4.1.7",
-    "vue-tsc": "^3.3.3"
+    "vitest": "^4.1.11",
+    "vue": "^3.5.43",
+    "vue-router": "^5.4.0",
+    "vue-tsc": "^3.3.13"
   }
 }

package/src/lib/StackTabs.vue

@@ -22,7 +22,7 @@ import {
   watch
 } from 'vue'
 import type { TransitionProps } from 'vue'
-import { getMaxZIndex } from './utils/scrollUtils'
+import { getMaxZIndex, invalidateZIndexCache } from './utils/scrollUtils'
 import { isAllowedTabUrl } from './utils/urlParser'
 import { applyStackTabsLocale } from './i18n/stackTabsLocale'
 import { type ITabData, TabScrollMode } from './model/TabModel'
@@ -96,6 +96,17 @@ const props = withDefaults(
     iframeLoadTimeout: 15000
   }
 )
+
+// iframePath 必填：用于 iframe 占位页（StackTabs 把 iframe 标签路由到这个 path 渲染）。
+// 这里在开发期给出明确错误，避免空字符串导致 router.push({ path: '' }) 跳到首页的隐式行为。
+if (typeof props.iframePath !== 'string' || props.iframePath.trim() === '') {
+  const message = '[vue-stack-tabs] <VueStackTabs> requires the "iframePath" prop (e.g. "/iframe").'
+  if (!import.meta.env.PROD) {
+    throw new Error(message)
+  }
+  console.error(message)
+}
+
 const { changeLocale, t } = useI18n()
 const runtimeContext =
   inject(stackTabsContextKey, null) ??
@@ -120,10 +131,12 @@ if (isRuntimeContextOwner) {
   provide(maximumKey, maximum)
 }
 watch(maximum, (isMaximum) => {
+  // 最大化切换会显著改变 body 下元素层叠顺序，先失效缓存再读取避免过期结果。
+  invalidateZIndexCache()
   maximumZIndex.value = isMaximum ? getMaxZIndex('body *:not(.stack-tab,.stack-tab *)') : undefined
 })
 const panelApi = isRuntimeContextOwner
-  ? useTabPanel()
+  ? useTabPanel(runtimeContext)
   : {
       tabs: runtimeContext.tabs,
       iframeRefreshKeys: runtimeContext.iframeRefreshKeys,
@@ -143,7 +156,7 @@ const {
   setSessionPrefix
 } = panelApi
 const tabActions = isRuntimeContextOwner
-  ? useTabActions()
+  ? useTabActions(runtimeContext)
   : {
       setIFramePath: () => undefined,
       openTab: () => Promise.resolve(undefined),

package/src/lib/assets/style/common/var.scss

@@ -63,4 +63,6 @@ $stack-tab-shadow-left: -5px 0 5px -5px rgb(0 0 0 / 60%); //#ccc;
 $stack-tab-shadow-right: 5px 0 5px -5px rgb(0 0 0 / 60%); //#ccc;
 $stack-tab-shadow-right-inset: inset -5px 0 5px -5px rgb(0 0 0 / 60%); //#ccc;
 $stack-tab-shadow-left-inset: inset 5px 0 5px -5px rgb(0 0 0 / 60%); //#ccc;
+$stack-tab-shadow-top-inset: inset 0 5px 5px -5px rgb(0 0 0 / 60%); //#ccc;
+$stack-tab-shadow-bottom-inset: inset 0 -5px 5px -5px rgb(0 0 0 / 60%); //#ccc;
 $stack-tab-shadow-context-menu: 5px 5px 5px rgb(0 0 0 / 10%);

package/src/lib/assets/style/stackTab.scss

@@ -164,7 +164,7 @@
     position: relative;
     display: inline-flex;
     height: 100%;
-    padding: 0;
+    padding: 0 16px 0 0;
     margin: 0;
     list-style: none;
     flex-wrap: nowrap;
@@ -197,6 +197,31 @@
       border-left: $stack-tab-border;
     }
 
+    &.is-dragging {
+      opacity: 0.55;
+    }
+
+    &.is-drop-before::before,
+    &.is-drop-after::after {
+      position: absolute;
+      z-index: 2;
+      top: 2px;
+      bottom: 2px;
+      width: 5px;
+      content: '';
+      background: $stack-tab-color-primary;
+      border-radius: 2px;
+      box-shadow: 0 0 6px rgba($stack-tab-color-primary, 0.8);
+    }
+
+    &.is-drop-before::before {
+      left: -3px;
+    }
+
+    &.is-drop-after::after {
+      right: -3px;
+    }
+
     /*
     激活右键菜单的页签
      */
@@ -418,7 +443,6 @@
     border-radius: 10px 0;
     box-shadow: $stack-tab-shadow-context-menu;
     transform-origin: left top;
-    transition: all 0.25s ease-in;
 
     &-item {
       display: flex;
@@ -439,7 +463,10 @@
       background: transparent;
       border: 0;
       border-radius: 10px 0;
-      transition: all 0.2s ease-in-out;
+      // 仅过渡悬停态实际会改变的颜色，避免触发菜单布局与合成层的无关动画。
+      transition:
+        color 0.2s ease-in-out,
+        background-color 0.2s ease-in-out;
       user-select: none;
 
       &:hover,
@@ -472,7 +499,7 @@
     &-icon {
       width: $stack-tab-font-size;
       height: $stack-tab-font-size;
-      transition: all 0.2s ease-in-out;
+      transition: background-color 0.2s ease-in-out;
 
       &.svg-mask {
         width: $stack-tab-font-size;
@@ -507,4 +534,16 @@
     @include mixins.insetShadow();
     box-shadow: $stack-tab-shadow-left-inset, $stack-tab-shadow-right-inset;
   }
+  &-top::after {
+    @include mixins.insetShadow();
+    box-shadow: $stack-tab-shadow-top-inset;
+  }
+  &-bottom::after {
+    @include mixins.insetShadow();
+    box-shadow: $stack-tab-shadow-bottom-inset;
+  }
+  &-vertical::after {
+    @include mixins.insetShadow();
+    box-shadow: $stack-tab-shadow-top-inset, $stack-tab-shadow-bottom-inset;
+  }
 }

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

@@ -13,7 +13,7 @@
     :style="{
       left: `${menuPosition.left}px`,
       top: `${menuPosition.top}px`,
-      'z-index': getMaxZIndex('.stack-tab,.stack-tab *')
+      'z-index': menuZIndex()
     }"
     @keydown="handleMenuKeydown"
   >
@@ -84,7 +84,7 @@
 import { ref, onMounted, reactive, nextTick } from 'vue'
 import type { ITabItem, IContextMenu } from '../../model/TabModel'
 import { useI18n } from 'vue-i18n-lite'
-import { getMaxZIndex } from '../../utils/scrollUtils'
+import { getMaxZIndex, invalidateZIndexCache } from '../../utils/scrollUtils'
 import useTabActions from '../../hooks/useTabActions'
 import useTabPanel from '../../hooks/useTabPanel'
 import ContextMenuItem from './ContextMenuItem.vue'
@@ -115,6 +115,14 @@ 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 *')
+}
+
 const focusActiveTabFallback = () => {
   const activeTab = document.querySelector<HTMLElement>('[role="tab"][aria-selected="true"]')
   activeTab?.focus()
@@ -193,7 +201,8 @@ const handleMenuKeydown = (event: KeyboardEvent) => {
   }
 }
 
-const getCustomMenuKey = (item: IContextMenu): string => item.key ?? `${item.title}-${item.icon ?? ''}`
+const getCustomMenuKey = (item: IContextMenu): string =>
+  item.key ?? `${item.title}-${item.icon ?? ''}`
 
 /** 挂载后修正菜单位置，避免超出右边界 */
 onMounted(() => {

package/src/lib/components/PageLoading.vue

@@ -11,7 +11,7 @@
     role="status"
     aria-live="polite"
     :aria-label="t('VueStackTab.loading')"
-    :style="{ zIndex: getMaxZIndex('.cache-page-wrapper *') }"
+    :style="{ zIndex: loadingZIndex() }"
   >
     <div class="stack-tab-loading--spin turn" aria-hidden="true" />
   </div>
@@ -20,7 +20,15 @@
 import { ref, onUnmounted } from 'vue'
 import { useI18n } from 'vue-i18n-lite'
 import { TabEventType, useTabEmitter } from '../hooks/useTabEventBus'
-import { getMaxZIndex } from '../utils/scrollUtils'
+import { getMaxZIndex, invalidateZIndexCache } from '../utils/scrollUtils'
+
+/**
+ * loading 遮罩每次显隐都会改变 .cache-page-wrapper 子树层叠，先失效缓存再读取避免旧值。
+ */
+const loadingZIndex = () => {
+  invalidateZIndexCache('.cache-page-wrapper *')
+  return getMaxZIndex('.cache-page-wrapper *')
+}
 const props = defineProps<{
   /** 当前标签 id，用于过滤 PAGE_LOADING 事件 */
   tabId: string

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

@@ -11,10 +11,11 @@
   - 不负责 transition、keep-alive、TabHeader、iframe 或 session 初始化
 -->
 <script lang="ts" setup>
-import { defineComponent, shallowRef, watch } from 'vue'
+import { shallowRef, watch } from 'vue'
 import type { DefineComponent, VNode } from 'vue'
 import type { RouteLocationNormalizedLoaded } from 'vue-router'
 import useTabPanel from '../../hooks/useTabPanel'
+import { getEmptyPlaceholderComponent } from './emptyPlaceholder'
 
 interface StackCacheRendererProps {
   route: RouteLocationNormalizedLoaded
@@ -37,14 +38,7 @@ defineSlots<{
 
 const { refreshKey, activeCacheKey, activePageRefreshVersion, addPage } = useTabPanel()
 
-const EmptyRendererComponent = defineComponent({
-  name: 'StackCacheRendererEmpty',
-  setup() {
-    return () => null
-  }
-}) as DefineComponent
-
-const wrappedComponent = shallowRef<DefineComponent>(EmptyRendererComponent)
+const wrappedComponent = shallowRef<DefineComponent>(getEmptyPlaceholderComponent())
 
 const getComponentIdentity = (component?: VNode | null): unknown => {
   return component?.type ?? component

package/src/lib/components/StackKeepAlive/emptyPlaceholder.tsx

@@ -0,0 +1,18 @@
+/**
+ * 共享的 Empty 占位组件。
+ *
+ * useTabPanel 在「empty」/「recovered」分支会返回一个不渲染任何内容的占位组件。
+ * 原先在 pageComponentFactory.tsx 和 StackCacheRenderer.vue 各自定义了一份，
+ * 这里抽出唯一来源，避免两份略有差异的副本带来维护负担。
+ */
+import { defineComponent } from 'vue'
+import type { DefineComponent } from 'vue'
+
+export const EmptyPlaceholderComponent = defineComponent({
+  name: 'StackTabEmptyPlaceholder',
+  setup() {
+    return () => null
+  }
+}) as DefineComponent
+
+export const getEmptyPlaceholderComponent = (): DefineComponent => EmptyPlaceholderComponent

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

@@ -5,10 +5,18 @@
     class="stack-tab__item"
     :class="{
       'is-active': item.active,
-      'is-icon': item.closable
+      'is-icon': item.closable,
+      'is-dragging': dragging,
+      'is-drop-before': dropPosition === 'before',
+      'is-drop-after': dropPosition === 'after'
     }"
+    :draggable="true"
     @click.self="handleActivate(true)"
     @contextmenu="$emit('contextmenu', $event)"
+    @dragstart="handleDragStart"
+    @dragend="handleDragEnd"
+    @dragover.prevent="$emit('dragover', item, $event)"
+    @drop.prevent="$emit('drop', item, $event)"
   >
     <button
       :id="getStackTabTabId(item.id)"
@@ -52,13 +60,23 @@ import type { ITabItem } from '../../model/TabModel'
 import { TabEventType, useTabEmitter } from '../../hooks/useTabEventBus'
 import { getStackTabPanelId, getStackTabTabId } from '../../utils/stackTabsA11y'
 import { useI18n } from 'vue-i18n-lite'
-const emit = defineEmits(['close', 'active', 'contextmenu'])
+const emit = defineEmits([
+  'close',
+  'active',
+  'contextmenu',
+  'dragstart',
+  'dragover',
+  'drop',
+  'dragend'
+])
 const emitter = useTabEmitter()
 const { t } = useI18n()
 /** 当前标签 DOM 元素，用于滚动到可视区域 */
 const tabElementRef = ref<HTMLElement>()
+const dragging = ref(false)
 const props = defineProps<{
   item: ITabItem
+  dropPosition?: 'before' | 'after'
 }>()
 
 /** TAB_ACTIVE 事件 payload */
@@ -80,6 +98,16 @@ const title = computed<string>(() => props.item.title || t('VueStackTab.undefine
 const handleClose = () => {
   emit('close', props.item)
 }
+const handleDragStart = (event: DragEvent) => {
+  dragging.value = true
+  event.dataTransfer?.setData('text/plain', props.item.id)
+  if (event.dataTransfer) event.dataTransfer.effectAllowed = 'move'
+  emit('dragstart', props.item, event)
+}
+const handleDragEnd = (event: DragEvent) => {
+  dragging.value = false
+  emit('dragend', props.item, event)
+}
 /** 激活当前标签，向父级 emit active 并传递 DOM 引用 */
 const handleActivate = (isRoute = true) => {
   emit('active', props.item, tabElementRef.value, isRoute)

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

@@ -17,11 +17,14 @@
           v-bind="tabTransitionProps"
           appear
           @keydown="handleTabListKeydown"
+          @dragover.prevent="handleTabListDragOver"
+          @drop.prevent="handleTabListDrop"
         >
           <tab-header-item
             v-for="(item, index) in tabs"
             :key="item.id"
             :item="item as ITabItem"
+            :drop-position="dropIndicator?.tabId === item.id ? dropIndicator.position : undefined"
             @contextmenu="
               (e: MouseEvent) =>
                 handleTabContextMenu(e, item as unknown as ITabItem, index, tabs.length)
@@ -29,6 +32,10 @@
             @click.middle.prevent="handleCloseTab(item as ITabItem)"
             @close="handleCloseTab"
             @active="handleActivateTab"
+            @dragstart="handleTabDragStart"
+            @dragover="handleTabDragOver"
+            @drop="handleTabDrop"
+            @dragend="handleTabDragEnd"
           />
         </transition-group>
       </template>
@@ -109,7 +116,10 @@ const props = withDefaults(
     max: 20
   }
 )
-const { closeTab, activeTab, tabs } = useTabActions()
+const { closeTab, activeTab, moveTab, tabs } = useTabActions()
+const draggingTabId = ref<string | null>(null)
+type DropPosition = 'before' | 'after'
+const dropIndicator = ref<{ tabId: string; position: DropPosition } | null>(null)
 
 /** 右键菜单是否启用；仅 false 明确禁用，其余旧对象值保持启用以兼容历史写法 */
 const isContextMenuEnabled = computed<boolean>(() => props.contextmenu !== false)
@@ -137,6 +147,67 @@ const handleTabContextMenu = (e: MouseEvent, item: ITabItem, index: number, max:
   showContextMenu(e, item, index, max)
 }
 
+/** 原生拖放只在释放鼠标时更新顺序，避免拖动经过标签时反复变更响应式列表。 */
+const handleTabDragStart = (item: ITabItem) => {
+  draggingTabId.value = item.id
+}
+
+const handleTabDragOver = (item: ITabItem, event: DragEvent) => {
+  if (!draggingTabId.value || draggingTabId.value === item.id) {
+    dropIndicator.value = null
+    return
+  }
+  const tabElement = event.currentTarget instanceof HTMLElement ? event.currentTarget : null
+  if (!tabElement) return
+
+  const { left, width } = tabElement.getBoundingClientRect()
+  dropIndicator.value = {
+    tabId: item.id,
+    position: event.clientX < left + width / 2 ? 'before' : 'after'
+  }
+  if (event.dataTransfer) event.dataTransfer.dropEffect = 'move'
+}
+
+const handleTabDrop = (target: ITabItem) => {
+  const sourceId = draggingTabId.value
+  const indicator = dropIndicator.value
+  draggingTabId.value = null
+  dropIndicator.value = null
+  if (!sourceId || sourceId === target.id || indicator?.tabId !== target.id) return
+  const sourceIndex = tabs.value.findIndex((tab) => tab.id === sourceId)
+  const targetIndex = tabs.value.findIndex((tab) => tab.id === target.id)
+  if (sourceIndex < 0 || targetIndex < 0) return
+
+  let destinationIndex = targetIndex
+  if (indicator.position === 'before' && sourceIndex < targetIndex) destinationIndex--
+  if (indicator.position === 'after' && sourceIndex > targetIndex) destinationIndex++
+  moveTab(sourceId, destinationIndex)
+}
+
+const handleTabDragEnd = () => {
+  draggingTabId.value = null
+  dropIndicator.value = null
+}
+
+/** 标签列表末端的留白也是投放区，便于明确地将标签移动到最后。 */
+const isTabItemDragEvent = (event: DragEvent) =>
+  event.target instanceof Element && Boolean(event.target.closest('.stack-tab__item'))
+
+const handleTabListDragOver = (event: DragEvent) => {
+  if (!draggingTabId.value || isTabItemDragEvent(event)) return
+  const lastTab = tabs.value[tabs.value.length - 1]
+  if (!lastTab || lastTab.id === draggingTabId.value) return
+
+  dropIndicator.value = { tabId: lastTab.id, position: 'after' }
+  if (event.dataTransfer) event.dataTransfer.dropEffect = 'move'
+}
+
+const handleTabListDrop = (event: DragEvent) => {
+  if (isTabItemDragEvent(event)) return
+  const lastTab = tabs.value[tabs.value.length - 1]
+  if (lastTab) handleTabDrop(lastTab as ITabItem)
+}
+
 /** 标签列表 transition 的 props，支持 string 或对象 */
 const tabTransitionProps = computed<TransitionProps>(() =>
   typeof props.tabTransition === 'string'
@@ -172,17 +243,18 @@ const handleTabListKeydown = (event: KeyboardEvent) => {
   if (count <= 0) return
 
   const currentIndex = getActiveTabIndex()
-  const safeIndex = currentIndex >= 0 ? currentIndex : 0
 
   if (event.key === 'ArrowRight') {
     event.preventDefault()
-    activateTabByIndex((safeIndex + 1) % count)
+    // 无 active 标签时从 -1 起步，按右方向键跳到第 0 个；正常情况环绕到下一个。
+    activateTabByIndex(currentIndex === -1 ? 0 : (currentIndex + 1) % count)
     return
   }
 
   if (event.key === 'ArrowLeft') {
     event.preventDefault()
-    activateTabByIndex((safeIndex - 1 + count) % count)
+    // 无 active 标签时按左方向键跳到最后一个；正常情况环绕到上一个。
+    activateTabByIndex(currentIndex === -1 ? count - 1 : (currentIndex - 1 + count) % count)
     return
   }