vue-stack-tabs 2.3.0 → 2.4.0

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

@@ -8,6 +8,9 @@
 $stack-tab-color-white: #fff !default;
 $stack-tab-color-black: #000 !default;
 
+// 主色上的文字/图标（深色主题下会反转为深色）
+$stack-tab-color-accent-contrast: $stack-tab-color-white !default;
+
 // 主色
 $stack-tab-color-primary: #409eff !default;
 $stack-tab-color-primary-invert: #ffac30 !default;
@@ -42,6 +45,7 @@ $stack-tab-iframe-error-bg: rgb(255 255 255 / 92%) !default;
 
 $stack-tab-border-color: #f0f0f0 !default;
 $stack-tab-border: 1px solid $stack-tab-border-color !default;
+$stack-tab-color-divider: #a9a9a9 !default;
 $stack-tab-tab-radius: 8px 8px 0 0 !default;
 $stack-tab-contextmenu-radius: 10px 0 !default;
 
@@ -88,13 +92,14 @@ $stack-tab-transition-slide:
 // ============================================================
 
 $stack-tab-shadow-color: rgb(0 0 0 / 60%) !default;
+$stack-tab-shadow-soft-color: rgb(0 0 0 / 10%) !default;
 $stack-tab-shadow-left: -5px 0 5px -5px $stack-tab-shadow-color !default;
 $stack-tab-shadow-right: 5px 0 5px -5px $stack-tab-shadow-color !default;
 $stack-tab-shadow-right-inset: inset -5px 0 5px -5px $stack-tab-shadow-color !default;
 $stack-tab-shadow-left-inset: inset 5px 0 5px -5px $stack-tab-shadow-color !default;
 $stack-tab-shadow-top-inset: inset 0 5px 5px -5px $stack-tab-shadow-color !default;
 $stack-tab-shadow-bottom-inset: inset 0 -5px 5px -5px $stack-tab-shadow-color !default;
-$stack-tab-shadow-context-menu: 5px 5px 5px rgb(0 0 0 / 10%) !default;
+$stack-tab-shadow-context-menu: 5px 5px 5px $stack-tab-shadow-soft-color !default;
 
 // ============================================================
 // 加载态
@@ -106,3 +111,101 @@ $stack-tab-loading-size: 50px !default;
 $stack-tab-loading-border-width: 8px !default;
 $stack-tab-loading-color: #007bff97 !default;
 $stack-tab-loading-duration: 1s !default;
+
+// ============================================================
+// 主题令牌（运行时 CSS 变量）
+//
+// 规则统一消费这一组变量；默认值定义在 theme.scss 的 :root 中。
+// var() 的 fallback 使用上面的编译期变量，保证单独编译的 scoped
+// 样式或未加载主题入口时仍有正确颜色，同时保留 SCSS 变量定制能力。
+// ============================================================
+
+// accent
+$stack-tab-accent: var(--stack-tab-accent, #{$stack-tab-color-primary}) !default;
+$stack-tab-accent-active: var(
+  --stack-tab-accent-active,
+  #{$stack-tab-color-primary-activate}
+) !default;
+$stack-tab-accent-contrast: var(
+  --stack-tab-accent-contrast,
+  #{$stack-tab-color-accent-contrast}
+) !default;
+$stack-tab-accent-shadow: var(
+  --stack-tab-accent-shadow,
+  #{rgba($stack-tab-color-primary, 0.8)}
+) !default;
+
+// surface
+$stack-tab-surface: var(--stack-tab-surface, #{$stack-tab-background-color-base}) !default;
+$stack-tab-surface-muted: var(
+  --stack-tab-surface-muted,
+  #{$stack-tab-background-color-inactive}
+) !default;
+$stack-tab-overlay: var(--stack-tab-overlay, #{$stack-tab-loading-mask-color}) !default;
+
+// text / icon
+$stack-tab-text: var(--stack-tab-text, #{$stack-tab-text-color}) !default;
+$stack-tab-text-strong: var(--stack-tab-text-strong, #{$stack-tab-color-black}) !default;
+$stack-tab-text-disabled: var(--stack-tab-text-disabled, #{$stack-tab-color-disabled}) !default;
+$stack-tab-icon-mask: var(--stack-tab-mask, #{$stack-tab-text-color}) !default;
+$stack-tab-font-size-token: var(--stack-tab-font-size, #{$stack-tab-font-size}) !default;
+
+// feedback
+$stack-tab-scrollbar: var(--stack-tab-scrollbar, #{$stack-tab-color-scrollbar}) !default;
+
+// border
+$stack-tab-border-color-token: var(--stack-tab-border, #{$stack-tab-border-color}) !default;
+$stack-tab-border-token: 1px solid $stack-tab-border-color-token !default;
+$stack-tab-divider: var(--stack-tab-divider, #{$stack-tab-color-divider}) !default;
+
+// shadow：颜色层
+$stack-tab-shadow-color-token: var(--stack-tab-shadow-color, #{$stack-tab-shadow-color}) !default;
+
+// shadow：整体层
+$stack-tab-shadow-tab: var(
+  --stack-tab-shadow-tab,
+  #{$stack-tab-shadow-left},
+  #{$stack-tab-shadow-right}
+) !default;
+$stack-tab-shadow-tab-left: var(--stack-tab-shadow-tab-left, #{$stack-tab-shadow-left}) !default;
+$stack-tab-shadow-tab-right: var(--stack-tab-shadow-tab-right, #{$stack-tab-shadow-right}) !default;
+$stack-tab-shadow-menu: var(
+  --stack-tab-shadow-menu,
+  5px 5px 5px #{$stack-tab-shadow-soft-color}
+) !default;
+$stack-tab-shadow-drop: var(--stack-tab-shadow-drop, 0 0 6px #{$stack-tab-accent-shadow}) !default;
+
+// shadow：inset 工具类
+$stack-tab-shadow-inset-left: var(
+  --stack-tab-shadow-inset-left,
+  #{$stack-tab-shadow-left-inset}
+) !default;
+$stack-tab-shadow-inset-right: var(
+  --stack-tab-shadow-inset-right,
+  #{$stack-tab-shadow-right-inset}
+) !default;
+$stack-tab-shadow-inset-top: var(
+  --stack-tab-shadow-inset-top,
+  #{$stack-tab-shadow-top-inset}
+) !default;
+$stack-tab-shadow-inset-bottom: var(
+  --stack-tab-shadow-inset-bottom,
+  #{$stack-tab-shadow-bottom-inset}
+) !default;
+$stack-tab-shadow-inset-all: var(
+  --stack-tab-shadow-inset-all,
+  #{$stack-tab-shadow-left-inset},
+  #{$stack-tab-shadow-right-inset}
+) !default;
+$stack-tab-shadow-inset-vertical: var(
+  --stack-tab-shadow-inset-vertical,
+  #{$stack-tab-shadow-top-inset},
+  #{$stack-tab-shadow-bottom-inset}
+) !default;
+
+// badge
+$stack-tab-badge-default: var(--stack-tab-badge-default, #{$stack-tab-color-danger}) !default;
+$stack-tab-badge-primary: var(--stack-tab-badge-primary, #{$stack-tab-color-primary}) !default;
+
+// loading
+$stack-tab-loading-accent: var(--stack-tab-loading-accent, #{$stack-tab-loading-color}) !default;

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

@@ -1,3 +1,4 @@
+@use 'common/theme.scss';
 @use 'stack-tab.scss';
 @use 'icon.scss';
 @use 'transition.scss';

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

@@ -6,7 +6,7 @@
   &__mask {
     @include absolute-fill;
     @include flex-center;
-    background-color: $stack-tab-loading-mask-color;
+    background-color: $stack-tab-overlay;
     opacity: $stack-tab-loading-mask-opacity;
   }
 
@@ -16,7 +16,7 @@
     width: $stack-tab-loading-size;
     aspect-ratio: 1;
     border: $stack-tab-loading-border-width solid transparent;
-    border-right-color: $stack-tab-loading-color;
+    border-right-color: $stack-tab-loading-accent;
     border-radius: 50%;
     animation: stack-tab-loading-rotate $stack-tab-loading-duration infinite linear;
 
@@ -26,7 +26,7 @@
       position: absolute;
       inset: -$stack-tab-loading-border-width;
       border: $stack-tab-loading-border-width solid transparent;
-      border-right-color: $stack-tab-loading-color;
+      border-right-color: $stack-tab-loading-accent;
       border-radius: 50%;
       animation: stack-tab-loading-rotate $stack-tab-loading-duration * 2 infinite linear;
     }

package/src/lib/assets/style/stack-tab.scss

@@ -5,7 +5,7 @@
 .stack-tab {
   display: flex;
   min-height: 300px;
-  background-color: $stack-tab-background-color-base;
+  background-color: $stack-tab-surface;
   flex-direction: column;
   gap: 5px;
 
@@ -41,7 +41,7 @@
 
     .stack-tab__header-button[disabled] & {
       cursor: not-allowed;
-      background-color: $stack-tab-color-disabled;
+      background-color: $stack-tab-text-disabled;
       transition: none;
     }
   }
@@ -57,7 +57,7 @@
     display: flex;
     width: 100%;
     height: $stack-tab-head-height;
-    border-bottom: 1px solid $stack-tab-border-color;
+    border-bottom: 1px solid $stack-tab-border-color-token;
     box-sizing: border-box;
 
     // tab header 上面的按钮
@@ -66,7 +66,7 @@
       height: $stack-tab-head-height;
       width: fit-content;
       overflow: hidden;
-      background-color: $stack-tab-background-color-base;
+      background-color: $stack-tab-surface;
       cursor: pointer;
       display: flex;
       align-items: center;
@@ -76,7 +76,7 @@
 
       // 按钮禁用样式
       &[disabled] {
-        background-color: $stack-tab-background-color-inactive;
+        background-color: $stack-tab-surface-muted;
         box-shadow: none;
         cursor: not-allowed;
       }
@@ -113,7 +113,7 @@
     bottom: 0;
     left: 0;
     height: $stack-tab-scroll-height;
-    background-color: $stack-tab-color-scrollbar;
+    background-color: $stack-tab-scrollbar;
     border-radius: $stack-tab-scroll-border-radius;
     opacity: 0;
     transition: $stack-tab-transition-fast;
@@ -129,7 +129,7 @@
     top: 0;
     left: 0;
     height: 100%;
-    background-color: $stack-tab-color-scrollbar;
+    background-color: $stack-tab-scrollbar;
     border-radius: $stack-tab-scroll-border-radius;
     transition: background-color $stack-tab-transition-duration ease-in-out;
     // 拖拽由 Pointer Events 接管，避免触摸时被浏览器手势打断
@@ -145,7 +145,7 @@
 
     .stack-tab__scrollbar--dragging &,
     &:hover {
-      background-color: $stack-tab-color-primary !important;
+      background-color: $stack-tab-accent !important;
     }
   }
 
@@ -166,11 +166,11 @@
     position: relative;
     display: flex;
     padding: 0 $stack-tab-padding;
-    font-size: $stack-tab-font-size;
-    color: $stack-tab-text-color;
+    font-size: $stack-tab-font-size-token;
+    color: $stack-tab-text;
     cursor: pointer;
-    background-color: $stack-tab-background-color-inactive;
-    border: $stack-tab-border;
+    background-color: $stack-tab-surface-muted;
+    border: $stack-tab-border-token;
     border-left: none;
     border-radius: $stack-tab-tab-radius;
     transition: $stack-tab-transition-fast;
@@ -182,7 +182,7 @@
     margin-top: 5px;
 
     &:first-child {
-      border-left: $stack-tab-border;
+      border-left: $stack-tab-border-token;
     }
 
     &--dragging {
@@ -197,9 +197,9 @@
       bottom: 2px;
       width: 5px;
       content: '';
-      background: $stack-tab-color-primary;
+      background: $stack-tab-accent;
       border-radius: 2px;
-      box-shadow: 0 0 6px rgba($stack-tab-color-primary, 0.8);
+      box-shadow: $stack-tab-shadow-drop;
     }
 
     &--drop-before::before {
@@ -212,21 +212,21 @@
 
     // 激活右键菜单的页签
     &--context-menu {
-      color: $stack-tab-color-black;
+      color: $stack-tab-text-strong;
     }
 
     // 激活的页签
     &--active {
       z-index: 1;
-      background-color: $stack-tab-background-color-base;
-      border-bottom-color: $stack-tab-background-color-base;
-      box-shadow: $stack-tab-shadow-left, $stack-tab-shadow-right;
+      background-color: $stack-tab-surface;
+      border-bottom-color: $stack-tab-surface;
+      box-shadow: $stack-tab-shadow-tab;
       margin-top: unset;
     }
 
     &:hover,
     &--active {
-      color: $stack-tab-color-primary;
+      color: $stack-tab-accent;
     }
 
     // 可关闭标签在悬停/激活时给关闭按钮腾出空间
@@ -300,19 +300,19 @@
       padding: 0.3rem;
       font-size: 0.5rem;
       line-height: 0.4rem;
-      color: $stack-tab-color-white;
+      color: $stack-tab-accent-contrast;
       text-align: center;
-      border: 1px solid $stack-tab-background-color-base;
+      border: 1px solid $stack-tab-surface;
       border-radius: 0.5rem;
       transform: translateX(100%) translateY(-50%);
       box-sizing: border-box;
 
       &--default {
-        background: $stack-tab-color-danger;
+        background: $stack-tab-badge-default;
       }
 
       &--primary {
-        background: $stack-tab-color-primary;
+        background: $stack-tab-badge-primary;
       }
     }
   }
@@ -361,11 +361,11 @@
 
     &-retry,
     &-open {
-      border: $stack-tab-border;
+      border: $stack-tab-border-token;
       padding: 4px 10px;
-      color: $stack-tab-text-color;
+      color: $stack-tab-text;
       cursor: pointer;
-      background: $stack-tab-background-color-base;
+      background: $stack-tab-surface;
       border-radius: 6px;
       font: inherit;
     }
@@ -377,11 +377,11 @@
     z-index: 999;
     min-width: 120px;
     padding: 8px;
-    font-size: $stack-tab-font-size;
-    background: $stack-tab-background-color-base;
-    border: $stack-tab-border;
+    font-size: $stack-tab-font-size-token;
+    background: $stack-tab-surface;
+    border: $stack-tab-border-token;
     border-radius: $stack-tab-contextmenu-radius;
-    box-shadow: $stack-tab-shadow-context-menu;
+    box-shadow: $stack-tab-shadow-menu;
     transform-origin: left top;
 
     &-item {
@@ -396,7 +396,7 @@
       padding: 0 10px;
       line-height: 30px;
       box-sizing: border-box;
-      color: $stack-tab-text-color;
+      color: $stack-tab-text;
       cursor: pointer;
       background: transparent;
       border-radius: $stack-tab-contextmenu-radius;
@@ -409,11 +409,11 @@
       &:hover,
       &:active,
       &:focus-visible {
-        color: $stack-tab-color-white;
-        background-color: $stack-tab-color-primary;
+        color: $stack-tab-accent-contrast;
+        background-color: $stack-tab-accent;
 
         .stack-tab__icon--mask {
-          background-color: $stack-tab-color-white;
+          background-color: $stack-tab-accent-contrast;
         }
       }
 
@@ -422,62 +422,62 @@
       }
 
       &[disabled] {
-        color: $stack-tab-color-disabled;
+        color: $stack-tab-text-disabled;
         pointer-events: none;
         cursor: default;
         background: none;
 
         .stack-tab__icon--mask {
-          background-color: $stack-tab-color-disabled;
+          background-color: $stack-tab-text-disabled;
         }
       }
     }
 
     &-icon {
-      width: $stack-tab-font-size;
-      height: $stack-tab-font-size;
+      width: $stack-tab-font-size-token;
+      height: $stack-tab-font-size-token;
       transition: background-color 0.2s ease-in-out;
 
       &.stack-tab__icon--mask {
-        width: $stack-tab-font-size;
-        height: $stack-tab-font-size;
-        background-color: $stack-tab-text-color;
+        width: $stack-tab-font-size-token;
+        height: $stack-tab-font-size-token;
+        background-color: $stack-tab-icon-mask;
       }
     }
   }
 }
 
 .stack-tab__shadow-left {
-  box-shadow: $stack-tab-shadow-left;
+  box-shadow: $stack-tab-shadow-tab-left;
 }
 
 .stack-tab__shadow-right {
-  box-shadow: $stack-tab-shadow-right;
+  box-shadow: $stack-tab-shadow-tab-right;
 }
 
 // 内阴影
 .stack-tab__shadow-inset {
   &-left {
-    @include inset-shadow($stack-tab-shadow-left-inset);
+    @include inset-shadow($stack-tab-shadow-inset-left);
   }
 
   &-right {
-    @include inset-shadow($stack-tab-shadow-right-inset);
+    @include inset-shadow($stack-tab-shadow-inset-right);
   }
 
   &-all {
-    @include inset-shadow($stack-tab-shadow-left-inset, $stack-tab-shadow-right-inset);
+    @include inset-shadow($stack-tab-shadow-inset-all);
   }
 
   &-top {
-    @include inset-shadow($stack-tab-shadow-top-inset);
+    @include inset-shadow($stack-tab-shadow-inset-top);
   }
 
   &-bottom {
-    @include inset-shadow($stack-tab-shadow-bottom-inset);
+    @include inset-shadow($stack-tab-shadow-inset-bottom);
   }
 
   &-vertical {
-    @include inset-shadow($stack-tab-shadow-top-inset, $stack-tab-shadow-bottom-inset);
+    @include inset-shadow($stack-tab-shadow-inset-vertical);
   }
 }

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

@@ -218,6 +218,8 @@ onMounted(() => {
 </script>
 
 <style lang="scss" scoped>
+@use '../../assets/style/common/var' as *;
+
 .divider {
   position: relative;
   height: 1px;
@@ -231,7 +233,7 @@ onMounted(() => {
   left: 0;
   width: 100%;
   height: 1px;
-  background-image: linear-gradient(to right, transparent, darkgrey, transparent);
+  background-image: linear-gradient(to right, transparent, $stack-tab-divider, transparent);
   content: '';
 }
 </style>

package/src/lib/hooks/tabPageContext.ts

@@ -0,0 +1,50 @@
+/**
+ * 页面级运行时上下文。
+ *
+ * 每个缓存页面（cacheName / pId）都归属于一个标签（tabId / tId）。
+ * 这组信息由页面缓存包装组件通过 provide 提供，页面内的 useTabRouter、
+ * useTabLoading 通过 inject 读取，不再作为 attrs 注入到用户页面组件。
+ *
+ * 这样做的原因：
+ * - 多根节点（Fragment）页面无法继承 attrs，Vue 会在开发环境提示
+ *   “Extraneous non-props attributes”；
+ * - 单根节点页面会把 tId / pId 透传到根 DOM 上，造成内部 ID 泄漏；
+ * - provide/inject 的边界与缓存包装组件一致，也允许页面内的嵌套组件复用。
+ */
+import type { InjectionKey } from 'vue'
+import { getCurrentInstance, hasInjectionContext, inject } from 'vue'
+
+export interface TabPageContext {
+  /** 当前页面所属的标签 id（旧实现中的 attrs.tId） */
+  tabId: string
+  /** 当前页面的缓存 id，即 cacheName（旧实现中的 attrs.pId） */
+  pageId: string
+}
+
+export const tabPageContextKey: InjectionKey<TabPageContext> = Symbol('tabPageContext')
+
+/**
+ * 解析当前页面上下文。
+ *
+ * 优先读取缓存包装组件 provide 的上下文；attrs / props 仅作为旧版
+ * cloneVNode 注入方式以及手工挂载场景的兼容回退。
+ *
+ * 返回值允许只包含其中一个字段：useTabLoading 只依赖 tabId，
+ * 旧代码或手工挂载可能只传了其中一个 id。
+ */
+export const resolveTabPageContext = (): Partial<TabPageContext> | null => {
+  if (hasInjectionContext()) {
+    const injected = inject(tabPageContextKey, null)
+    if (injected) return injected
+  }
+
+  const instance = getCurrentInstance()
+  if (!instance) return null
+
+  const tabId = instance.attrs.tId ?? instance.props.tId
+  const pageId = instance.attrs.pId ?? instance.props.pId
+  const context: Partial<TabPageContext> = {}
+  if (typeof tabId === 'string') context.tabId = tabId
+  if (typeof pageId === 'string') context.pageId = pageId
+  return context.tabId !== undefined || context.pageId !== undefined ? context : null
+}

package/src/lib/hooks/tabPanel/pageComponentFactory.tsx

@@ -13,6 +13,7 @@ import {
   onDeactivated,
   onMounted,
   onUnmounted,
+  provide,
   ref,
   shallowRef,
   watch
@@ -21,6 +22,7 @@ import type { DefineComponent, PropType, VNode } from 'vue'
 import type { ITabBase } from '../../model/TabModel'
 import PageLoading from '../../components/PageLoading.vue'
 import type { StackTabsRuntimeContext } from '../stackTabsContext'
+import { tabPageContextKey } from '../tabPageContext'
 import { useScrollShadow } from '../useScrollShadow'
 
 interface PageComponentFactoryOptions {
@@ -139,6 +141,14 @@ export const createPageComponentFactory = (options: PageComponentFactoryOptions)
       },
       emits: ['onLoaded'],
       setup(props, context) {
+        // 页面上下文只在缓存包装组件这一层 provide，页面组件及其嵌套组件都可 inject。
+        // 不再把 tId / pId 作为 attrs 注入页面：多根节点页面会触发 Vue 的
+        // “Extraneous non-props attributes”警告，单根节点页面则会把内部 ID 透传到 DOM。
+        provide(tabPageContextKey, {
+          tabId: tabInfo.id!,
+          pageId: cacheName
+        })
+
         const localBackParams = ref<Record<string, unknown> | null>(null)
         const lastVnode = shallowRef<VNode | null | undefined>(null)
         const lastCloned = shallowRef<VNode | null>(null)
@@ -337,12 +347,10 @@ export const createPageComponentFactory = (options: PageComponentFactoryOptions)
           const vnode = props.vnode
           const backParams = localBackParams.value
           if (vnode !== lastVnode.value || backParams !== lastBackParams.value) {
+            // _back 是页面需要读取的公开 prop，仍通过 cloneVNode 注入；
+            // tId / pId 已改为 provide/inject，不再污染页面 attrs。
             lastCloned.value = vnode
-              ? cloneVNode(vnode, {
-                  tId: tabInfo.id,
-                  pId: cacheName,
-                  ...(backParams ? { _back: backParams } : {})
-                })
+              ? cloneVNode(vnode, backParams ? { _back: backParams } : null)
               : null
             lastVnode.value = vnode
             lastBackParams.value = backParams

package/src/lib/hooks/useTabLoading.ts

@@ -1,16 +1,18 @@
-import { type ComponentInternalInstance, getCurrentInstance, onUnmounted } from 'vue'
+import { onUnmounted } from 'vue'
 import { TabEventType, useTabEmitter } from '../hooks/useTabEventBus'
+import { resolveTabPageContext } from './tabPageContext'
 
 /**
  * useTabLoading - 标签内页面加载状态 Hook
  *
  * 职责：通过 PAGE_LOADING 事件控制 PageLoading 组件的显示/隐藏
- * 使用范围：标签内的页面组件（需有 tId 通过 attrs 传入）
+ * 使用范围：标签内的页面组件；tabId 由缓存包装组件 provide，
+ * 页面通过 tabPageContext 解析（兼容旧版 attrs / props 注入）。
  */
 export default () => {
   const emitter = useTabEmitter()
-  const { attrs } = getCurrentInstance() as ComponentInternalInstance
-  const getTabId = () => String(attrs.tId ?? '')
+  const pageContext = resolveTabPageContext()
+  const getTabId = () => pageContext?.tabId ?? ''
   onUnmounted(() => {
     closeTabLoading()
   })

package/src/lib/hooks/useTabRouter.ts

@@ -1,9 +1,8 @@
-import { getCurrentInstance } from 'vue'
-import type { ComponentInternalInstance } from 'vue'
 import type { LocationQueryRaw, RouteLocationPathRaw } from 'vue-router'
 import { isNavigationFailure, useRoute, useRouter } from 'vue-router'
 
 import useTabPanel from './useTabPanel'
+import { resolveTabPageContext } from './tabPageContext'
 import {
   parseUrl,
   cloneLocationQuery,
@@ -22,30 +21,26 @@ import { createPageId } from '../utils/tabInfoEncoder'
  * useTabRouter - 标签内路由 Hook
  *
  * 职责：在单个标签内实现「前进/后退」栈式导航，以及滚动位置的记录与恢复
- * 使用范围：仅在标签内的页面组件中使用，依赖 StackTabs 通过 cloneVNode 注入的 tId / pId
+ * 使用范围：仅在标签内的页面组件中使用；页面上下文由缓存包装组件 provide，
+ * 通过 tabPageContext 解析（兼容旧版 attrs / props 注入）。
  *
  * 主要 API：
  * - forward(to)             前进：push 新页面到该标签的 pages 栈
  * - backward(to, backQuery) 后退：pop 栈顶、驱逐缓存，跳转到新栈顶
  * - addScrollTarget(...)    注册需要记录滚动位置的选择器
+ * - tabId / pageId          当前页面所属标签与缓存页 id（只读）
  */
 export default function useTabRouter() {
-  const instance = getCurrentInstance() as ComponentInternalInstance
-  const { attrs, props } = instance
+  const pageContext = resolveTabPageContext()
 
-  /**
-   * 当前标签 ID。
-   * StackTabs 在 StackTabs.vue 的 tabWrapper 里通过 cloneVNode(Node, { tId, pId }) 注入，
-   * 未在子组件 setup 中声明为 prop 的属性会落入 attrs，
-   * 因此优先读 attrs.tId，再 fallback 到 props.tId。
-   */
-  const tabId = (attrs.tId ?? props.tId) as string
+  /** 当前标签 ID，用于定位页面栈与标签激活状态。 */
+  const tabId = pageContext?.tabId ?? ''
 
   /**
    * 当前页面的缓存 ID（即 cacheName / keep-alive include 中的名称）。
    * 用于 addScrollTarget 向 useTabPanel 绑定该页面的可滚动容器选择器。
    */
-  const pageId = (attrs.pId ?? props.pId) as string
+  const pageId = pageContext?.pageId ?? ''
 
   const route = useRoute()
   const router = useRouter()
@@ -249,6 +244,8 @@ export default function useTabRouter() {
   return {
     forward,
     backward,
-    addScrollTarget
+    addScrollTarget,
+    tabId,
+    pageId
   }
 }