vue-stack-tabs 1.4.2 → 2.3.0

package/README.en.md

@@ -368,6 +368,7 @@ fetchData().finally(() => closeTabLoading())
 | `iframeAllow`          | `string`                    | `''`                                                                       | iframe allow attribute, e.g. `fullscreen`                                                                                                                                             |
 | `iframeLoadTimeout`    | `number`                    | `15000`                                                                    | iframe load timeout in ms                                                                                                                                                             |
 | `defaultTabs`          | `ITabData[]`                | `[]`                                                                       | Initial tab list                                                                                                                                                                      |
+| `homeTab`              | `ITabData`                  | —                                                                          | Pinned home tab: always first, non-closable and non-draggable; other tabs cannot move before it. Omit to keep the previous behavior.                                                  |
 | `max`                  | `number`                    | `20`                                                                       | Maximum number of tabs                                                                                                                                                                |
 | `contextmenu`          | `boolean \| object`         | `true`                                                                     | Enable context menu                                                                                                                                                                   |
 | `pageTransition`       | `string`                    | `'stack-tab-swap'`                                                         | Page transition animation name for forward navigation                                                                                                                                 |

package/README.md

@@ -372,6 +372,7 @@ fetchData().finally(() => closeTabLoading())
 | `iframeAllow`          | `string`                    | `''`                                                                       | iframe allow 属性，例如 `fullscreen`                                                                              |
 | `iframeLoadTimeout`    | `number`                    | `15000`                                                                    | iframe 加载超时时间，单位 ms                                                                                      |
 | `defaultTabs`          | `ITabData[]`                | `[]`                                                                       | 初始标签列表                                                                                                      |
+| `homeTab`              | `ITabData`                  | —                                                                          | 固定首页：始终第一位、不可关闭、不可拖动；其他标签不能排到它前面；不配置时保持原行为                              |
 | `max`                  | `number`                    | `20`                                                                       | 最大标签数量                                                                                                      |
 | `contextmenu`          | `boolean \| object`         | `true`                                                                     | 是否启用右键菜单                                                                                                  |
 | `pageTransition`       | `string`                    | `'stack-tab-swap'`                                                         | 前进时的页面转场动画名                                                                                            |

package/README.ru.md

@@ -372,6 +372,7 @@ fetchData().finally(() => closeTabLoading())
 | `iframeAllow`          | `string`                    | `''`                                                                       | Атрибут allow для iframe, например `fullscreen`                                                                                                                                     |
 | `iframeLoadTimeout`    | `number`                    | `15000`                                                                    | Тайм-аут загрузки iframe в мс                                                                                                                                                       |
 | `defaultTabs`          | `ITabData[]`                | `[]`                                                                       | Начальный список вкладок                                                                                                                                                            |
+| `homeTab`              | `ITabData`                  | —                                                                          | Закреплённая домашняя вкладка: всегда первая, не закрывается и не перемещается; другие вкладки не могут встать перед ней                                                            |
 | `max`                  | `number`                    | `20`                                                                       | Максимальное количество вкладок                                                                                                                                                     |
 | `contextmenu`          | `boolean \| object`         | `true`                                                                     | Включить контекстное меню                                                                                                                                                           |
 | `pageTransition`       | `string`                    | `'stack-tab-swap'`                                                         | Имя анимации перехода при навигации вперёд                                                                                                                                          |

package/dist/StackTabs.vue.d.ts

@@ -3,6 +3,8 @@ import { ITabData, TabScrollMode } from './model/TabModel';
 type StackTabsIframeReferrerPolicy = '' | 'no-referrer' | 'no-referrer-when-downgrade' | 'origin' | 'origin-when-cross-origin' | 'same-origin' | 'strict-origin' | 'strict-origin-when-cross-origin' | 'unsafe-url';
 type __VLS_Props = {
     defaultTabs?: ITabData[];
+    /** 固定首页：始终位于第一位、不可关闭、不可移动，其他标签也不能排到它前面。 */
+    homeTab?: ITabData;
     max?: number;
     contextmenu?: boolean | object;
     pageTransition?: string;
@@ -45,13 +47,14 @@ declare const __VLS_base: import('vue').DefineComponent<__VLS_Props, {}, {}, {},
     onOnPageLoaded?: ((...args: any[]) => any) | undefined;
 }>, {
     contextmenu: boolean | object;
-    defaultTabs: ITabData[];
     max: number;
     space: number;
-    width: string;
     tabScrollMode: TabScrollMode;
     tabTransition: string | TransitionProps;
+    width: string;
     iframeLoadTimeout: number;
+    defaultTabs: ITabData[];
+    homeTab: ITabData;
     pageTransition: string;
     pageTransitionBack: string;
     height: string;

package/dist/components/ContextMenu/ContextMenuItem.vue.d.ts

@@ -1,5 +1,5 @@
 type __VLS_Props = {
-    /** 图标 class，如 stack-tab__icon-reload svg-mask */
+    /** 图标 class，如 stack-tab__icon stack-tab__icon--reload stack-tab__icon--mask */
     icon?: string;
     /** 显示文本 */
     title: string;

package/dist/components/StackKeepAlive/StackCacheRenderer.vue.d.ts

@@ -7,8 +7,6 @@ interface StackCacheRendererProps {
 interface StackCacheRendererSlotProps {
     wrappedComponent: DefineComponent;
     activeCacheKey: string;
-    refreshKey: number;
-    activePageRefreshVersion: number;
     component?: VNode | null;
 }
 type __VLS_Slots = {

package/dist/hooks/stackTabsContext.d.ts

@@ -7,7 +7,6 @@ export declare const STACK_TABS_CONTEXT_UNAVAILABLE_MESSAGE = "VueStackTabs runt
 export declare const STACK_TABS_DUPLICATE_INSTANCE_MESSAGE = "VueStackTabs only supports one <VueStackTabs> instance per Vue app.";
 export interface StackTabsRuntimeContext {
     tabs: Ref<ITabItem[]>;
-    defaultTabs: Ref<ITabItem[]>;
     caches: ShallowRef<string[]>;
     components: Map<string, DefineComponent>;
     cacheIdsToEvict: Set<string>;

package/dist/hooks/tabPanel/evict.d.ts

@@ -5,12 +5,12 @@ export interface TabPanelEvictionApi {
     markTabPagesForEviction: (tab: {
         id: string;
         pages: {
-            list(): ITabPage[];
+            readonlyList(): readonly ITabPage[];
         };
     }) => void;
     markTabPagesForEvictionOnly: (tab: {
         pages: {
-            list(): ITabPage[];
+            readonlyList(): readonly ITabPage[];
         };
     }) => void;
     addCache: (cacheName: string) => void;

package/dist/hooks/tabPanel/refresh.d.ts

@@ -1,6 +1,6 @@
 import { Ref } from 'vue';
 import { ITabItem, ITabPage } from '../../model/TabModel';
-import { PagePatch } from './tabStore';
+import { PagePatch, PageUpdate } from './tabStore';
 export interface TabPanelRefreshApi {
     refreshTab: (id: string) => void;
     refreshAllTabs: () => void;
@@ -8,8 +8,10 @@ export interface TabPanelRefreshApi {
 export interface CreateTabPanelRefreshOptions {
     getTabs: () => readonly ITabItem[];
     getTopPage: (tabId: string) => ITabPage | null;
-    /** 修改页面字段（刷新版本 / 页面 id）并触发 tabs 更新 */
+    /** 修改页面字段（刷新版本 / 页面 id） */
     updatePage: (tabId: string, pageId: string, patch: PagePatch) => boolean;
+    /** 批量修改页面字段，refreshAllTabs 最后统一触发一次 tabs 更新 */
+    updatePages: (updates: readonly PageUpdate[]) => void;
     iframeRefreshKeys: Ref<Record<string, number>>;
     createPageId: () => string;
     addCache: (cacheName: string) => void;

package/dist/hooks/tabPanel/scroll.d.ts

@@ -4,7 +4,5 @@ export interface TabPanelScrollApi {
     saveScroller: (pageCacheId: string) => void;
     removeScroller: (pageCacheId: string) => void;
     addPageScroller: (pageCacheId: string, ...selectorIds: string[]) => void;
-    /** 主动失效某页面的滚动元素缓存，例如外部强制刷新缓存页时 */
-    invalidateAutoScrollCache: (pageCacheId: string) => void;
 }
 export declare const createTabPanelScroll: (context: StackTabsRuntimeContext) => TabPanelScrollApi;

package/dist/hooks/tabPanel/state.d.ts

@@ -6,7 +6,6 @@ export interface ScrollPosition {
 }
 export interface TabPanelRuntimeState {
     tabs: Ref<ITabItem[]>;
-    defaultTabs: Ref<ITabItem[]>;
     caches: ShallowRef<string[]>;
     components: Map<string, DefineComponent>;
     cacheIdsToEvict: Set<string>;

package/dist/hooks/tabPanel/tabStore.d.ts

@@ -8,6 +8,11 @@ export interface RemoveTabResult {
     /** 关闭后应激活的相邻标签；没有可激活标签时为空字符串 */
     nextActiveId: string;
 }
+export interface PageUpdate {
+    tabId: string;
+    pageId: string;
+    patch: PagePatch;
+}
 /** updatePage 允许修改的字段；页面身份与刷新版本必须通过 store 写入 */
 export interface PagePatch {
     id?: string;
@@ -25,12 +30,16 @@ export interface TabStoreApi extends TabPanelEvictionApi {
     canAddTab: () => boolean;
     getPages: (tabId: string) => readonly ITabPage[];
     getTopPage: (tabId: string) => ITabPage | null;
+    /** 读取任意页面的刷新版本；渲染层据此只重建对应页面 */
+    getPageRefreshVersion: (pageId: string) => number;
     /** 返回深拷贝的页面栈快照，可直接用于 rollback */
     getPageSnapshot: (tabId: string) => ITabPage[];
     addTab: (tab: ITabItem) => void;
     addTabs: (tabs: readonly ITabItem[]) => void;
     /** 唯一 active 写入口 */
     activateTab: (id: string) => ITabItem | null;
+    /** 动态更新标签标题；返回 false 表示标签不存在 */
+    updateTabTitle: (id: string, title: string) => boolean;
     moveTab: (id: string, targetIndex: number) => boolean;
     removeTab: (id: string) => RemoveTabResult;
     removeTabs: (shouldRemove: (tab: ITabItem, index: number) => boolean) => ITabItem[];
@@ -40,8 +49,10 @@ export interface TabStoreApi extends TabPanelEvictionApi {
     /** 用给定页面替换整个栈（内部深拷贝页面） */
     replacePages: (tabId: string, pages: readonly ITabPage[]) => void;
     clearPages: (tabId: string) => void;
-    /** 修改页面字段（id / refreshVersion / _backParams），并触发 tabs 更新 */
+    /** 修改页面字段（id / refreshVersion / _backParams）；仅 id 变化时重建 tabs 数组 */
     updatePage: (tabId: string, pageId: string, patch: PagePatch) => boolean;
+    /** 批量修改页面字段，最后最多重建一次 tabs 数组（供 refreshAllTabs 使用） */
+    updatePages: (updates: readonly PageUpdate[]) => void;
     /** 取出并清除栈顶页面的 _backParams；pageId 不是当前栈顶时返回 null */
     consumeBackParams: (tabId: string, pageId: string) => Record<string, unknown> | null;
     isTabMarkedForEviction: (id: string) => boolean;

package/dist/hooks/useIframeManager.d.ts

@@ -8,7 +8,7 @@ interface IframeLoadState {
 export interface UseIframeManagerOptions {
     tabs: Ref<ITabItem[]>;
     iframeRefreshKeys: Ref<Record<string, number>>;
-    iframeLoadTimeout: number;
+    iframeLoadTimeout: Ref<number>;
     t: (key: string) => string;
 }
 export declare function useIframeManager(options: UseIframeManagerOptions): {

package/dist/hooks/useScrollShadow.d.ts

@@ -1,7 +1,14 @@
 import { Ref } from 'vue';
 export interface UseScrollShadowOptions {
-    /** 容器元素的 ref，可以是 Ref<HTMLElement | null> 或 getter 函数 */
+    /** 滚动容器：用于监听 scroll / resize 并读取滚动尺寸 */
     target: Ref<HTMLElement | null> | (() => HTMLElement | null);
+    /**
+     * 阴影类挂载目标，默认与 target 相同。
+     * 当 target 参与 transform 动画（如刷新转场）时，应传入不参与动画的祖先
+     * （例如 .stack-tab__keep-alive-panel），否则 ::after 的绝对定位包含块会变化，
+     * 阴影会随动画错位或消失。
+     */
+    classTarget?: Ref<HTMLElement | null> | (() => HTMLElement | null);
     /**
      * 是否监听内容缩放/尺寸变化（默认 true）。
      * 启用后会用 ResizeObserver 监视目标尺寸，容器或子树尺寸变化都会重新计算阴影边界。
@@ -14,7 +21,9 @@ export interface UseScrollShadowOptions {
     edgeThreshold?: number;
 }
 export interface UseScrollShadowReturn {
-    /** 手动同步一次（用于内容变化/resize 后） */
+    /** 重新解析滚动/阴影目标并同步一次（用于 keep-alive 激活、DOM 重新挂载后） */
     sync: () => void;
+    /** 移除阴影类并取消待执行的 rAF（用于 keep-alive 失活） */
+    clear: () => void;
 }
 export declare const useScrollShadow: (options: UseScrollShadowOptions) => UseScrollShadowReturn;

package/dist/hooks/useTabActions.d.ts

@@ -21,6 +21,7 @@ export default function useTabActions(providedRuntimeContext?: StackTabsRuntimeC
     refreshAllTabs: () => void;
     activeTab: (id: string, route?: boolean) => Promise<void | import('vue-router').NavigationFailure | undefined>;
     moveTab: (id: string, targetIndex: number) => boolean;
+    updateTabTitle: (tabId: string, title: string) => boolean;
     reset: () => void;
     tabs: import('vue').Ref<import('..').ITabItem[], import('..').ITabItem[]>;
     setIFramePath: (path: string) => void;

package/dist/hooks/useTabEventBus.d.ts

@@ -10,6 +10,8 @@ declare module '@vue/runtime-core' {
 export declare enum TabEventType {
     PAGE_LOADING = "PAGE_LOADING",
     TAB_ACTIVE = "TAB_ACTIVE",
+    /** 请求标签栏将指定标签滚动到可视区域（不改变激活状态） */
+    TAB_SCROLL_TO = "TAB_SCROLL_TO",
     FORWARD = "FORWARD",
     BACKWARD = "BACKWARD",
     REFRESH_IFRAME_POSTMESSAGE = "REFRESH_IFRAME_POSTMESSAGE"
@@ -23,6 +25,9 @@ export interface TabEventPayloadMap extends Record<EventType, unknown> {
         id: string;
         isRoute?: boolean;
     };
+    [TabEventType.TAB_SCROLL_TO]: {
+        id: string;
+    };
     [TabEventType.FORWARD]: void;
     [TabEventType.BACKWARD]: void;
     [TabEventType.REFRESH_IFRAME_POSTMESSAGE]: string;

package/dist/hooks/useTabPanel.d.ts

@@ -4,7 +4,7 @@ import { RouteLocationNormalizedLoaded } from 'vue-router';
 import { StackTabsRuntimeContext } from './stackTabsContext';
 /** 规范化路径（nginx 等可能加尾部斜杠） */
 export declare const normalizePathForCache: (route: RouteLocationNormalizedLoaded) => string;
-declare const _default: (providedRuntimeContext?: StackTabsRuntimeContext) => {
+declare const createTabPanelApi: (runtimeContext: StackTabsRuntimeContext) => {
     tabs: import('vue').Ref<ITabItem[], ITabItem[]>;
     caches: import('vue').ShallowRef<string[]>;
     refreshKey: import('vue').Ref<number, number>;
@@ -13,9 +13,10 @@ declare const _default: (providedRuntimeContext?: StackTabsRuntimeContext) => {
     isInitialized: import('vue').Ref<boolean, boolean>;
     setMaxSize: (value: number) => void;
     canAddTab: () => boolean;
-    initialize: (staticTabs: ITabData[]) => void;
+    initialize: (staticTabs: ITabData[], homeTab?: ITabData) => void;
     size: () => number;
     active: (id: string, route?: boolean) => Promise<void | import('vue-router').NavigationFailure | undefined>;
+    updateTabTitle: (tabId: string, title: string) => boolean;
     getCacheName: () => string;
     destroy: () => void;
     reset: () => void;
@@ -25,6 +26,7 @@ declare const _default: (providedRuntimeContext?: StackTabsRuntimeContext) => {
     getActiveTab: () => ITabItem | null;
     getTopPage: (tabId: string) => ITabPage | null;
     getPages: (tabId: string) => readonly ITabPage[];
+    getPageRefreshVersion: (pageId: string) => number;
     getPageSnapshot: (tabId: string) => ITabPage[];
     moveTab: (id: string, targetIndex: number) => boolean;
     addTab: (tab: ITabItem) => void;
@@ -33,6 +35,7 @@ declare const _default: (providedRuntimeContext?: StackTabsRuntimeContext) => {
     replacePages: (tabId: string, pages: readonly ITabPage[]) => void;
     clearPages: (tabId: string) => void;
     updatePage: (tabId: string, pageId: string, patch: import('./tabPanel/tabStore').PagePatch) => boolean;
+    updatePages: (updates: readonly import('./tabPanel/tabStore').PageUpdate[]) => void;
     removeTab: (id: string) => string;
     removeAllTabs: () => void;
     removeLeftTabs: (id: string) => void;
@@ -56,4 +59,13 @@ declare const _default: (providedRuntimeContext?: StackTabsRuntimeContext) => {
     clearSession: () => void;
     setSessionPrefix: (value: string) => void;
 };
+type TabPanelApi = ReturnType<typeof createTabPanelApi>;
+/**
+ * 同一个运行时上下文复用同一套 panel API。
+ *
+ * StackTabs、StackKeepAlive、StackCacheRenderer、ContextMenu 与页面内的 useTabRouter
+ * 都会调用本 hook；首次调用在 setup 上下文中完成 useRouter/useI18n 注入，
+ * 后续调用直接返回缓存，避免重复创建 scroll/session/refresh 闭包与局部状态。
+ */
+declare const _default: (providedRuntimeContext?: StackTabsRuntimeContext) => TabPanelApi;
 export default _default;

package/dist/model/TabModel.d.ts

@@ -11,22 +11,29 @@ export declare enum TabScrollMode {
     BUTTON = "button",
     BOTH = "both"
 }
-/** 标签栏滚动条拖拽时的临时状态 */
+/**
+ * @deprecated 标签栏拖拽内部已不再使用该类型；保留仅为兼容 2.x 的公开类型导出，
+ * 将在下一个大版本移除。
+ */
 export interface DragData {
     thumbLeft: number;
     startScrollLeft: number;
     startThumbLeft: number;
     startPageX: number;
 }
-/** 滚动条滑块计算所需的数据 */
+/**
+ * @deprecated 内部滚轮/滚动事件常量已不再使用该类型；保留仅为兼容 2.x 的公开类型导出，
+ * 将在下一个大版本移除。
+ */
+export type ScrollEvents = {
+    ScrollUpdate: void;
+};
+/** 滚动条滑块计算所需的数据（滚动过程中保持非响应式） */
 export interface ScrollData {
     clientWidth: number;
     scrollWidth: number;
     scrollLeft: number;
 }
-export type ScrollEvents = {
-    ScrollUpdate: void;
-};
 /** 打开标签时传入的完整数据（含 path、query） */
 export interface ITabData extends ITabBase {
     title: string;
@@ -55,6 +62,11 @@ export interface ITabItem extends ITabBase {
     url?: string;
     active: boolean;
     pages: Stack<ITabPage>;
+    /**
+     * 固定在标签栏最前方的内部标记（目前仅 homeTab 使用）。
+     * pinned 标签不可被拖动，其他标签也不能排到它前面；仅存在于运行时，不写入 __tab。
+     */
+    pinned?: boolean;
 }
 /** 标签内的单个页面（对应 keep-alive 的一个缓存实例） */
 export interface ITabPage {

package/dist/nuxt/module.mjs

@@ -11,7 +11,7 @@ var a = i({
 		a.options.runtimeConfig.public.vueStackTabs = { locale: i.locale }, n({ src: o("./runtime/plugin") }), e({
 			name: "VueStackTabs",
 			export: "VueStackTabs",
-			filePath: o("../index.ts")
+			filePath: o("../vue-stack-tabs.es.js")
 		}), t([
 			{
 				name: "useTabActions",