vue-stack-tabs 0.1.51 → 1.0.0

package/dist/src/lib/hooks/tabPanel/session.d.ts

@@ -0,0 +1,9 @@
+import { ITabItem } from '../../model/TabModel';
+/** 获取 sessionStorage 的 key */
+export declare const getSessionKey: () => string;
+/** 将当前激活的标签保存到 sessionStorage */
+export declare const saveActiveTabToSession: (tab: ITabItem) => void;
+/** 清除 sessionStorage 中的激活标签 */
+export declare const clearSession: () => void;
+/** 从 sessionStorage 解析恢复的标签（含 Stack 反序列化） */
+export declare const restoreTabFromSession: (storedJson: string | null) => ITabItem | null;

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

@@ -0,0 +1,77 @@
+import { ITabItem } from '../../model/TabModel';
+/** 当前打开的标签列表（含每个标签的页面栈） */
+export declare const tabs: import('vue').Ref<{
+    id: string;
+    closable: boolean;
+    refreshable: boolean;
+    iframe: boolean;
+    iframeRefreshMode?: import('../..').IframeRefreshMode | undefined;
+    url?: string | undefined;
+    active: boolean;
+    pages: {
+        push: (element: import('../..').ITabPage) => void;
+        pop: () => import('../..').ITabPage | undefined;
+        peek: () => import('../..').ITabPage | undefined;
+        isEmpty: () => boolean;
+        size: () => number;
+        clear: () => void;
+        list: () => import('../..').ITabPage[];
+        toString: () => string;
+        toJSON: () => import('../..').ITabPage[];
+    };
+    title: string;
+}[], ITabItem[] | {
+    id: string;
+    closable: boolean;
+    refreshable: boolean;
+    iframe: boolean;
+    iframeRefreshMode?: import('../..').IframeRefreshMode | undefined;
+    url?: string | undefined;
+    active: boolean;
+    pages: {
+        push: (element: import('../..').ITabPage) => void;
+        pop: () => import('../..').ITabPage | undefined;
+        peek: () => import('../..').ITabPage | undefined;
+        isEmpty: () => boolean;
+        size: () => number;
+        clear: () => void;
+        list: () => import('../..').ITabPage[];
+        toString: () => string;
+        toJSON: () => import('../..').ITabPage[];
+    };
+    title: string;
+}[]>;
+/** 初始化时传入的默认标签（用于对比 session 恢复） */
+export declare const defaultTabs: ITabItem[];
+/** keep-alive include 数组，与 Vue 的 keep-alive :include 绑定 */
+export declare const caches: import('vue').Ref<string[], string[]>;
+/** 页面缓存 ID -> 包装后的 DefineComponent */
+export declare const components: Map<string, import('vue').DefineComponent<{}, {}, {}, import('vue').ComputedOptions, import('vue').MethodOptions, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<import('vue').ExtractPropTypes<{}>>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, any>>;
+/** 待驱逐的页面缓存 ID 集合 */
+export declare const cacheIdsToEvict: Set<string>;
+/** 待驱逐的标签 ID 集合 */
+export declare const tabIdsToEvict: Set<string>;
+/** 刷新计数器，变更时触发 component :key 变化 */
+export declare const refreshKey: import('vue').Ref<number, number>;
+/** 刷新时临时加入 keep-alive exclude 的缓存 ID */
+export declare const excludedCacheIdsForRefresh: import('vue').Ref<string[], string[]>;
+/** pageCacheId -> Map<selector, { top, left }> 滚动位置存储 */
+export declare const scrollPositionsByPageId: Map<string, Map<string, {
+    top: number;
+    left: number;
+}>>;
+/** 是否已完成初始化 */
+export declare const isInitialized: import('vue').Ref<boolean, boolean>;
+/** sessionStorage 中存储当前激活标签的 key 前缀 */
+export declare const SESSION_TAB_NAME = "stacktab-active-tab";
+/** iframe 标签 tabId -> 刷新序号，变更时触发 iframe 重载 */
+export declare const iframeRefreshKeys: import('vue').Ref<Record<string, number>, Record<string, number>>;
+/** 最大标签数量，0 表示不限制 */
+export declare let maxTabCount: number;
+/** 是否使用页面级滚动 */
+export declare let useGlobalScroll: boolean;
+/** sessionStorage key 前缀 */
+export declare let sessionPrefix: string;
+export declare const setMaxTabCount: (n: number) => void;
+export declare const setUseGlobalScroll: (v: boolean) => void;
+export declare const setSessionPrefix: (p: string) => void;

package/dist/src/lib/hooks/useContextMenu.d.ts

@@ -1,5 +1,10 @@
 import { ITabItem } from '../model/TabModel';
-
+/**
+ * useContextMenu - 标签右键菜单 Hook
+ *
+ * 职责：管理右键菜单的显示/隐藏、定位，点击菜单外区域关闭
+ * 使用：TabHeader 中右键标签时调用 showContextMenu
+ */
 declare const _default: () => {
     shown: import('vue').Ref<boolean, boolean>;
     contextMenuData: {

package/dist/src/lib/hooks/useTabActions.d.ts

@@ -0,0 +1,68 @@
+import { throttle } from 'throttle-debounce';
+import { ITabData, IframeRefreshMode } from '../model/TabModel';
+/**
+ * useTabActions - 标签操作对外 Hook
+ *
+ * 职责：提供打开、关闭、刷新标签等用户级 API，内部委托 useTabPanel 执行
+ * 使用范围：业务代码、ContextMenu、TabHeader 等
+ *
+ * 主要 API：
+ * - openTab(tab, renew?) 打开或续签标签
+ * - closeTab(id) / closeAllTabs() 关闭标签
+ * - refreshTab(id) / refreshAllTabs() 刷新
+ * - activeTab(id, isRoute?) 激活标签
+ * - reset() 重置（关闭所有）
+ */
+export default function useTabActions(): {
+    openTab: throttle<(tab: ITabData, renew?: any) => Promise<string | undefined>>;
+    closeTab: (id: string) => string;
+    closeAllTabs: () => void;
+    refreshTab: (id: string) => void;
+    refreshAllTabs: () => void;
+    activeTab: (id: string, route?: boolean) => void;
+    reset: () => void;
+    tabs: import('vue').Ref<{
+        id: string;
+        closable: boolean;
+        refreshable: boolean;
+        iframe: boolean;
+        iframeRefreshMode?: IframeRefreshMode | undefined;
+        url?: string | undefined;
+        active: boolean;
+        pages: {
+            push: (element: import('..').ITabPage) => void;
+            pop: () => import('..').ITabPage | undefined;
+            peek: () => import('..').ITabPage | undefined;
+            isEmpty: () => boolean;
+            size: () => number;
+            clear: () => void;
+            list: () => import('..').ITabPage[];
+            toString: () => string;
+            toJSON: () => import('..').ITabPage[];
+        };
+        title: string;
+    }[], import('..').ITabItem[] | {
+        id: string;
+        closable: boolean;
+        refreshable: boolean;
+        iframe: boolean;
+        iframeRefreshMode?: IframeRefreshMode | undefined;
+        url?: string | undefined;
+        active: boolean;
+        pages: {
+            push: (element: import('..').ITabPage) => void;
+            pop: () => import('..').ITabPage | undefined;
+            peek: () => import('..').ITabPage | undefined;
+            isEmpty: () => boolean;
+            size: () => number;
+            clear: () => void;
+            list: () => import('..').ITabPage[];
+            toString: () => string;
+            toJSON: () => import('..').ITabPage[];
+        };
+        title: string;
+    }[]>;
+    setIFramePath: (path: string) => void;
+    getWrapper: () => Element | undefined;
+    openInNewWindow: (id: string) => void;
+};

package/dist/src/lib/hooks/{useTabMitt.d.ts → useTabEventBus.d.ts}

@@ -1,6 +1,5 @@
 import { Emitter, EventType } from 'mitt';
 import { App } from 'vue';
-
 declare module '@vue/runtime-core' {
     interface ComponentCustomProperties {
         $layerEmitter: Emitter<Record<EventType, unknown>>;
@@ -9,8 +8,10 @@ declare module '@vue/runtime-core' {
 declare const plugin: {
     install(app: App): void;
 };
-export declare const useEmitter: <T extends Record<EventType, unknown>>() => Emitter<T>;
-export declare enum MittType {
+/** 获取标签事件总线，用于组件间通信 */
+export declare const useTabEmitter: <T extends Record<EventType, unknown>>() => Emitter<T>;
+/** 标签相关事件类型 */
+export declare enum TabEventType {
     PAGE_LOADING = "PAGE_LOADING",
     TAB_ACTIVE = "TAB_ACTIVE"
 }

package/dist/src/lib/hooks/useTabLoading.d.ts

@@ -1,3 +1,9 @@
+/**
+ * useTabLoading - 标签内页面加载状态 Hook
+ *
+ * 职责：通过 PAGE_LOADING 事件控制 PageLoading 组件的显示/隐藏
+ * 使用范围：标签内的页面组件（需有 tId 通过 attrs 传入）
+ */
 declare const _default: () => {
     openTabLoading: () => void;
     closeTabLoading: () => void;

package/dist/src/lib/hooks/{useTabpanel.d.ts → useTabPanel.d.ts}

@@ -1,13 +1,15 @@
 import { ITabData, ITabItem, ITabPage } from '../model/TabModel';
 import { DefineComponent, VNode } from 'vue';
 import { RouteLocationNormalizedLoaded } from 'vue-router';
-
+/** 规范化路径（nginx 等可能加尾部斜杠） */
+export declare const normalizePathForCache: (route: RouteLocationNormalizedLoaded) => string;
 declare const _default: () => {
     tabs: import('vue').Ref<{
         id: string;
         closable: boolean;
         refreshable: boolean;
         iframe: boolean;
+        iframeRefreshMode?: import('..').IframeRefreshMode | undefined;
         url?: string | undefined;
         active: boolean;
         pages: {
@@ -27,6 +29,7 @@ declare const _default: () => {
         closable: boolean;
         refreshable: boolean;
         iframe: boolean;
+        iframeRefreshMode?: import('..').IframeRefreshMode | undefined;
         url?: string | undefined;
         active: boolean;
         pages: {
@@ -43,11 +46,12 @@ declare const _default: () => {
         title: string;
     }[]>;
     caches: import('vue').Ref<string[], string[]>;
-    pageShown: import('vue').Ref<boolean, boolean>;
-    initialed: import('vue').Ref<boolean, boolean>;
-    setMaxSize: (size: number) => void;
+    refreshKey: import('vue').Ref<number, number>;
+    excludedCacheIdsForRefresh: import('vue').Ref<string[], string[]>;
+    isInitialized: import('vue').Ref<boolean, boolean>;
+    setMaxSize: (n: number) => void;
     canAddTab: () => boolean;
-    initial: (staticTabs: ITabData[]) => void;
+    initialize: (staticTabs: ITabData[]) => void;
     size: () => number;
     active: (id: string, route?: boolean) => void;
     destroy: () => void;
@@ -59,6 +63,7 @@ declare const _default: () => {
         closable: boolean;
         refreshable: boolean;
         iframe: boolean;
+        iframeRefreshMode?: import('..').IframeRefreshMode | undefined;
         url?: string | undefined;
         active: boolean;
         pages: {
@@ -74,7 +79,7 @@ declare const _default: () => {
         };
         title: string;
     } | null;
-    addTab: (tab: ITabItem) => Promise<unknown>;
+    addTab: (tab: ITabItem) => Promise<boolean>;
     removeTab: (id: string) => string;
     removeAllTabs: () => void;
     removeLeftTabs: (id: string) => void;
@@ -83,16 +88,17 @@ declare const _default: () => {
     hasTab: (id: string) => boolean;
     renewTab: (tab: ITabData) => void;
     addPage: (route: RouteLocationNormalizedLoaded, component: VNode) => DefineComponent;
-    addComponent: (id: string, comp: DefineComponent) => void;
-    getComponent: (id: string) => any;
-    removeComponent: (id: string) => void;
-    markDeletableCache: (cacheName: string) => void;
-    removeDeletableCache: () => void;
+    addComponent: (id: string, comp: DefineComponent) => Map<string, DefineComponent<{}, {}, {}, import('vue').ComputedOptions, import('vue').MethodOptions, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<import('vue').ExtractPropTypes<{}>>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, any>>;
+    getComponent: (id: string) => DefineComponent<{}, {}, {}, import('vue').ComputedOptions, import('vue').MethodOptions, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<import('vue').ExtractPropTypes<{}>>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, any> | undefined;
+    removeComponent: (id: string) => boolean;
+    markCacheForEviction: (cacheName: string) => void;
+    evictMarkedCaches: () => void;
     refreshTab: (id: string) => void;
     refreshAllTabs: () => void;
-    addPageScroller: (pageId: string, ...scrollerIds: string[]) => void;
-    setGlobalScroll: (globalScroll: boolean) => void;
+    iframeRefreshKeys: import('vue').Ref<Record<string, number>, Record<string, number>>;
+    addPageScroller: (pageCacheId: string, ...selectorIds: string[]) => void;
+    setGlobalScroll: (v: boolean) => void;
     clearSession: () => void;
-    setSessionPrefix: (prefix: string) => void;
+    setSessionPrefix: (p: string) => void;
 };
 export default _default;

package/dist/src/lib/hooks/useTabPanel.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/lib/hooks/useTabRouter.d.ts

@@ -1,8 +1,17 @@
 import { RouteLocationPathRaw } from 'vue-router';
-
-declare const _default: () => {
+/**
+ * useTabRouter - 标签内路由 Hook
+ *
+ * 职责：在单个标签内实现「前进/后退」栈式导航，以及滚动位置的记录与恢复
+ * 使用范围：仅在标签内的页面组件中使用，依赖 router-view 传入的 tId、pId
+ *
+ * 主要 API：
+ * - forward(to) 前进：push 新页面到该标签的 pages 栈
+ * - backward(to, backQuery?) 后退：pop 栈顶、markCacheForEviction，跳转到新栈顶
+ * - addScrollTarget(...selectors) 注册需要记录滚动位置的选择器
+ */
+export default function useTabRouter(): {
     forward: (to: RouteLocationPathRaw) => void;
-    backward: (to: number | string, query?: Object) => void;
-    addScroller: (...scroller: string[]) => void;
+    backward: (to: number | string, backQuery?: object) => void;
+    addScrollTarget: (...selectors: string[]) => void;
 };
-export default _default;

package/dist/src/lib/i18n/index.d.ts

@@ -1,7 +1,7 @@
 declare const _default: () => {
     getI18n: (localeI18n?: {
         locale: string;
-        messages: any;
+        messages: Record<string, unknown>;
     }[]) => import('vue-i18n-lite').I18n;
 };
 export default _default;

package/dist/src/lib/i18n/lang/en.d.ts

@@ -11,6 +11,7 @@ declare const _default: {
         restore: string;
         undefined: string;
         loading: string;
+        openInNewWindow: string;
     };
 };
 export default _default;

package/dist/src/lib/i18n/lang/zh-CN.d.ts

@@ -11,6 +11,7 @@ declare const _default: {
         restore: string;
         undefined: string;
         loading: string;
+        openInNewWindow: string;
     };
 };
 export default _default;

package/dist/src/lib/index.d.ts

@@ -3,20 +3,21 @@ import { default as StackTab } from './StackTabs.vue';
 import { default as IFrame } from './iframe.vue';
 import { default as useTabLoading } from './hooks/useTabLoading';
 import { default as useTabRouter } from './hooks/useTabRouter';
-import { default as useStackTab } from './hooks/useStackTab';
+import { default as useTabActions } from './hooks/useTabActions';
 import { default as TabHeaderButton } from './components/TabHeader/TabHeaderButton.vue';
-
 export * from './model/TabModel';
 declare module '@vue/runtime-core' {
     interface GlobalComponents {
         VueStackTabs: typeof StackTab;
     }
 }
-export { IFrame, useTabLoading, useTabRouter, useStackTab, TabHeaderButton, StackTab };
+export { IFrame, useTabActions, useTabLoading, useTabRouter, TabHeaderButton, StackTab };
+export { postOpenTab, onRefreshRequest, MSG_REFRESH, MSG_OPEN_TAB } from './utils/iframeBridge';
+export type { IframeOpenTabPayload } from './utils/iframeBridge';
 declare const _default: {
     install(Vue: App, options?: {
         locale: string;
-        messages: any;
+        messages: Record<string, unknown>;
     }[]): void;
 };
 export default _default;

package/dist/src/lib/model/TabModel.d.ts

@@ -1,14 +1,23 @@
+/**
+ * TabModel - 标签页数据模型
+ *
+ * 职责：定义标签、页面、栈结构及右键菜单的数据结构
+ * 使用：useTabPanel、useTabActions、ContextMenu 等
+ */
+/** 标签栏滚动方式：滚轮、按钮、或两者 */
 export declare enum TabScrollMode {
     WHEEL = "wheel",
     BUTTON = "button",
     BOTH = "both"
 }
+/** 标签栏滚动条拖拽时的临时状态 */
 export interface DragData {
     thumbLeft: number;
     startScrollLeft: number;
     startThumbLeft: number;
     startPageX: number;
 }
+/** 滚动条滑块计算所需的数据 */
 export interface ScrollData {
     clientWidth: number;
     scrollWidth: number;
@@ -17,42 +26,50 @@ export interface ScrollData {
 export type ScrollEvents = {
     ScrollUpdate: void;
 };
-/**
- * Tab data for open
- */
+/** 打开标签时传入的完整数据（含 path、query） */
 export interface ITabData extends ITabBase {
     title: string;
     path: string;
     query?: Record<string, string>;
 }
+/** iframe 刷新方式：postMessage 由 iframe 内页自行刷新（不重建 DOM，动画正常）；reload 强制重载 iframe */
+export type IframeRefreshMode = 'postMessage' | 'reload';
+/** 标签基础信息（id、title、是否可关闭/刷新、是否 iframe） */
 export interface ITabBase {
     id?: string;
     title: string;
     closable?: boolean;
     refreshable?: boolean;
     iframe?: boolean;
+    /** iframe 刷新方式，默认 postMessage */
+    iframeRefreshMode?: IframeRefreshMode;
 }
+/** 内部使用的标签项，含 active 状态和 pages 栈 */
 export interface ITabItem extends ITabBase {
     id: string;
     closable: boolean;
     refreshable: boolean;
     iframe: boolean;
+    iframeRefreshMode?: IframeRefreshMode;
     url?: string;
     active: boolean;
     pages: Stack<ITabPage>;
 }
+/** 标签内的单个页面（对应 keep-alive 的一个缓存实例） */
 export interface ITabPage {
     id: string;
     tabId: string;
     path: string;
     query?: Record<string, string>;
 }
+/** 右键菜单项：图标、标题、回调、禁用条件 */
 export interface IContextMenu {
     icon?: string;
     title: string;
     callback(id: string): void;
     disabled: (tabData: ITabBase) => boolean;
 }
+/** 使用 Map 实现的栈结构，用于标签内的 pages 页面栈 */
 export declare class Stack<T> {
     private items;
     constructor(items?: T[]);

package/dist/src/lib/model/TabModel.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/lib/utils/iframeBridge.d.ts

@@ -0,0 +1,31 @@
+/**
+ * iframe 与父窗口的 postMessage 桥接
+ *
+ * 在 iframe 内的页面中引入，用于：
+ * - 接收父窗口的刷新指令并执行
+ * - 向父窗口发送打开新标签的请求
+ */
+/** 刷新消息：父 -> iframe，iframe 内页面需监听并执行 location.reload() 或自身刷新逻辑 */
+export declare const MSG_REFRESH = "vue-stack-tabs:refresh";
+/** 打开标签消息：iframe -> 父，payload 为 ITabData */
+export declare const MSG_OPEN_TAB = "vue-stack-tabs:openTab";
+export interface IframeOpenTabPayload {
+    id?: string;
+    title: string;
+    path: string;
+    query?: Record<string, string>;
+    closable?: boolean;
+    refreshable?: boolean;
+    iframe?: boolean;
+}
+/**
+ * 在 iframe 内调用：向父窗口请求打开新标签
+ * @param payload 标签数据，至少需 title、path
+ */
+export declare function postOpenTab(payload: IframeOpenTabPayload): void;
+/**
+ * 在 iframe 内调用：注册刷新监听，收到父窗口刷新指令时执行 callback
+ * @param callback 默认 location.reload()，可自定义
+ * @returns 取消监听的函数
+ */
+export declare function onRefreshRequest(callback?: () => void): () => void;

package/dist/src/lib/utils/iframeBridge.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/lib/utils/scrollUtils.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 滚动工具函数
+ *
+ * 职责：页面/标签切换时保存与恢复滚动位置，以及 z-index 计算
+ * 使用：useTabPanel 的 scrollPositionsByPageId、TabHeader 滚动条
+ */
+/**
+ * 将指定容器滚动到 (left, top)，支持 smooth
+ */
+export declare const scrollTo: ({ wrap, left, top, smooth }: {
+    wrap: HTMLElement | null;
+    left?: number;
+    top?: number;
+    smooth?: boolean;
+}) => void;
+/** 将指定元素滚动到容器可视区域内，支持 block/inline 对齐方式 */
+export declare function scrollIntoView({ el, wrap, block, inline }: {
+    el: HTMLElement;
+    wrap: HTMLElement | {
+        value: HTMLElement | null;
+    } | null;
+    block?: ScrollLogicalPosition;
+    inline?: ScrollLogicalPosition;
+}): void;
+/** 获取系统滚动条宽度（用于布局计算） */
+export declare const getScrollbarWidth: () => number;
+/** 获取指定选择器下元素的最大 z-index + 1，用于最大化时置顶 */
+export declare const getMaxZIndex: (key?: string) => number;

package/dist/src/lib/utils/tabInfoEncoder.d.ts

@@ -0,0 +1,19 @@
+import { ITabBase } from '../model/TabModel';
+/**
+ * 标签信息编解码器
+ *
+ * 职责：将标签元数据压缩为 URL query 可用的短字符串，用于 __tab 参数
+ * 格式: id|title|iframe|closable|refreshable，压缩后写入 query.__tab
+ */
+/**
+ * 编码标签基础信息为压缩字符串（用于 query.__tab）
+ * @param tabData 标签基础数据
+ */
+export declare const encodeTabInfo: (tabData: ITabBase) => string;
+/** 从 query.__tab 解压并解析为 ITabBase */
+export declare const decodeTabInfo: (encoded: string) => ITabBase;
+/**
+ * 根据 tabId + path + query 生成页面缓存 ID
+ * 用于 keep-alive 的 include 和 exclude，需稳定且唯一
+ */
+export declare const createPageId: (tabId: string, path: string, query: object) => string;

package/dist/src/lib/utils/tabInfoEncoder.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/lib/utils/urlParser.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 判断是否为不可嵌入 iframe 的协议
+ * @param url - 待检查的 URL 字符串
+ * @returns javascript:、data: 等返回 true
+ */
+export declare function isInvalidIframeUrl(url: string): boolean;
+/**
+ * 判断 URL 是否为跨域（相对路径或同源视为同域）
+ * @param url - 待检查的 URL
+ */
+export declare function isCrossOriginUrl(url: string): boolean;
+/**
+ * 解析 URL 字符串为 path 和 query
+ * @param uri 完整 URL 或 path?query 字符串
+ */
+export declare function parseUrl(uri: string): {
+    path: string;
+    query: Record<string, string>;
+};

package/dist/src/lib/utils/urlParser.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/lib/versionLogger.d.ts

@@ -0,0 +1,2 @@
+declare const logVersion: (version: string) => void;
+export default logVersion;