vue-stack-tabs 1.0.1 → 1.1.0

package/dist/iframe-child.html

@@ -0,0 +1,75 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Iframe 子页面测试</title>
+    <style>
+      body {
+        font-family: system-ui, sans-serif;
+        padding: 20px;
+        background: #f0f9eb;
+      }
+      .card {
+        background: white;
+        padding: 20px;
+        border-radius: 8px;
+        box-shadow: 0 2px 12px 0 rgba(0, 0, 0, 0.1);
+      }
+      button {
+        padding: 10px 20px;
+        background: #409eff;
+        color: white;
+        border: none;
+        border-radius: 4px;
+        cursor: pointer;
+      }
+      input {
+        padding: 8px;
+        width: 200px;
+        margin-right: 10px;
+        border: 1px solid #dcdfe6;
+        border-radius: 4px;
+      }
+    </style>
+  </head>
+  <body>
+    <div class="card">
+      <h2>此页面运行在隔离的 iframe 中</h2>
+      <p>页面加载时间: <span id="time"></span></p>
+      <p>
+        用于测试 iframe 页面的加载、刷新隔离，以及通过 `postMessage` 向外层通信请求打开新 Tab
+        的功能。
+      </p>
+
+      <div style="margin: 20px 0">
+        <label>隔离缓存测试输入框：</label>
+        <input type="text" id="ipt" placeholder="切走该页签是否会销毁内容？" />
+      </div>
+
+      <div style="margin: 20px 0">
+        <button onclick="requestNewTab()">向父级发送 postMessage 请求在外部打开新 Tab</button>
+      </div>
+    </div>
+
+    <script>
+      document.getElementById('time').innerText = new Date().toLocaleTimeString()
+
+      function requestNewTab() {
+        window.parent.postMessage(
+          {
+            type: 'openTab',
+            payload: {
+              id: 'iframe_triggered_tab',
+              title: 'IFrame 弹出的新页签',
+              path: '/demo/page2',
+              closable: true
+            },
+            refresh: true
+          },
+          '*'
+        )
+      }
+    </script>
+  </body>
+</html>

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

@@ -1,24 +1,62 @@
 import { ITabPage } from '../../model/TabModel';
-/** 标记缓存为待驱逐 */
+/**
+ * 将指定 cacheName 放入待驱逐集合。
+ * 不立即清除，等叫到 evictMarkedCaches 时统一处理。
+ */
 export declare const markCacheForEviction: (cacheName: string) => void;
-/** 标记标签下所有页面为可驱逐，并标记该标签（关闭场景） */
+/**
+ * 标记某个标签下所有页面为待驱逐，并标记该标签本身（用于「关闭标签」场景）。
+ * tabIdsToEvict 中的标签 ID 会在 updatePageState 中被检测到，
+ * 阻止被关闭的标签重新路由时意外复活。
+ */
 export declare const markTabPagesForEviction: (tab: {
     id: string;
     pages: {
         list(): ITabPage[];
     };
 }) => void;
-/** 仅标记标签下所有页面为可驱逐（续签场景） */
+/**
+ * 仅标记标签下所有页面为待驱逐，不标记标签本身（用于「续签/换页」场景）。
+ * 适用于刷新标签：旧页面缓存清零，标签本身仍然存活，
+ * 导航后由 updatePageState 重新创建页面。
+ */
 export declare const markTabPagesForEvictionOnly: (tab: {
     pages: {
         list(): ITabPage[];
     };
 }) => void;
-/** 将缓存 id 加入 caches */
+/**
+ * 将 cacheName 加入 <keep-alive> 的 include 列表（caches）。
+ * 幂等：已存在时不重复添加，避免 include 数组中出现重复项
+ * 影响 <keep-alive> 缓存范围，决定哪些 cacheComponent 实例会被保留。
+ */
 export declare const addCache: (cacheName: string) => void;
-/** 从 caches 中移除指定 id */
+/**
+ * 将 cacheName 从 include 列表（caches）中移除。
+ * Vue 的 <keep-alive> 会以 flush:'post' 的 watcher 检测 include 变更，
+ * 在下次渲染后自动销毁不再被 include 的缓存实例。
+ */
 export declare const removeCache: (cacheName: string) => void;
-/** 立即驱逐单个页面缓存 */
+/**
+ * 立即、同步、彻底驱逐单个页面的缓存。
+ *
+ * 操作步骤：
+ * 1. 从 cacheIdsToEvict 移除（若存在，防止后续 evictMarkedCaches 二次处理）
+ * 2. removeCache(cacheName)   → 从 <keep-alive> include 列表删除，触发 Vue 销毁缓存组件实例
+ * 3. components.delete(...)   → 从 components Map 删除组件定义，
+ *    使 resolvePageComponent 下次进入时必须重新创建全新的 cacheComponent 实例
+ *
+ * ⚠️ 调用时机要求：
+ * 必须在 router.push() 完成（.then()）之后调用，
+ * 不能在导航前调用，否则驱逐触发的响应式更新会导致 StackTabs 以旧路由重渲染，
+ * 进而重建刚被删除的组件（竞态）。详见 useTabRouter.ts backward 的注释。
+ */
 export declare const evictPageCache: (cacheName: string) => void;
-/** 执行所有待驱逐缓存的驱逐 */
+/**
+ * 执行所有已标记缓存的批量驱逐（由 cacheComponent 的 onActivated 调用）。
+ *
+ * 调用时机：
+ * 当 cacheComponent 切换到激活（activated）状态时，说明用户切换到了一个新页面，
+ * 相关的旧页面已经稳定进入「不活跃/待驱逐」状态，此时批量清理是安全的。
+ */
 export declare const evictMarkedCaches: () => void;

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

@@ -16,8 +16,8 @@ export declare const tabs: import('vue').Ref<{
         size: () => number;
         clear: () => void;
         list: () => import('../..').ITabPage[];
-        toString: () => string;
         toJSON: () => import('../..').ITabPage[];
+        toString: () => string;
     };
     title: string;
 }[], ITabItem[] | {
@@ -36,8 +36,8 @@ export declare const tabs: import('vue').Ref<{
         size: () => number;
         clear: () => void;
         list: () => import('../..').ITabPage[];
-        toString: () => string;
         toJSON: () => import('../..').ITabPage[];
+        toString: () => string;
     };
     title: string;
 }[]>;
@@ -54,7 +54,6 @@ 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;

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

@@ -37,8 +37,8 @@ export default function useTabActions(): {
             size: () => number;
             clear: () => void;
             list: () => import('..').ITabPage[];
-            toString: () => string;
             toJSON: () => import('..').ITabPage[];
+            toString: () => string;
         };
         title: string;
     }[], import('..').ITabItem[] | {
@@ -57,8 +57,8 @@ export default function useTabActions(): {
             size: () => number;
             clear: () => void;
             list: () => import('..').ITabPage[];
-            toString: () => string;
             toJSON: () => import('..').ITabPage[];
+            toString: () => string;
         };
         title: string;
     }[]>;

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

@@ -20,8 +20,8 @@ declare const _default: () => {
             size: () => number;
             clear: () => void;
             list: () => ITabPage[];
-            toString: () => string;
             toJSON: () => ITabPage[];
+            toString: () => string;
         };
         title: string;
     }[], ITabItem[] | {
@@ -40,20 +40,21 @@ declare const _default: () => {
             size: () => number;
             clear: () => void;
             list: () => ITabPage[];
-            toString: () => string;
             toJSON: () => ITabPage[];
+            toString: () => string;
         };
         title: string;
     }[]>;
     caches: import('vue').Ref<string[], string[]>;
     refreshKey: import('vue').Ref<number, number>;
-    excludedCacheIdsForRefresh: import('vue').Ref<string[], string[]>;
+    activeCacheKey: import('vue').Ref<string, string>;
     isInitialized: import('vue').Ref<boolean, boolean>;
     setMaxSize: (n: number) => void;
     canAddTab: () => boolean;
     initialize: (staticTabs: ITabData[]) => void;
     size: () => number;
     active: (id: string, route?: boolean) => void;
+    getCacheName: () => string;
     destroy: () => void;
     reset: () => void;
     addCache: (cacheName: string) => void;
@@ -74,8 +75,8 @@ declare const _default: () => {
             size: () => number;
             clear: () => void;
             list: () => ITabPage[];
-            toString: () => string;
             toJSON: () => ITabPage[];
+            toString: () => string;
         };
         title: string;
     } | null;
@@ -93,6 +94,7 @@ declare const _default: () => {
     removeComponent: (id: string) => boolean;
     markCacheForEviction: (cacheName: string) => void;
     evictMarkedCaches: () => void;
+    evictPageCache: (cacheName: string) => void;
     refreshTab: (id: string) => void;
     refreshAllTabs: () => void;
     iframeRefreshKeys: import('vue').Ref<Record<string, number>, Record<string, number>>;

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

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

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

@@ -61,6 +61,8 @@ export interface ITabPage {
     tabId: string;
     path: string;
     query?: Record<string, string>;
+    /** 该页面从别的页面被后退唤醒时附带的临时闭包参数，不污染 URL */
+    _backParams?: Record<string, unknown>;
 }
 /** 右键菜单项：图标、标题、回调、禁用条件 */
 export interface IContextMenu {
@@ -71,7 +73,7 @@ export interface IContextMenu {
 }
 /** 使用 Map 实现的栈结构，用于标签内的 pages 页面栈 */
 export declare class Stack<T> {
-    private items;
+    protected items: Map<number, T>;
     constructor(items?: T[]);
     /**
      * @description: 入栈
@@ -99,14 +101,22 @@ export declare class Stack<T> {
      */
     size(): number;
     /**
-     * @description: 清空栈
+     * @description: 清空栈内存
      */
     clear(): void;
+    /**
+     * @description: 将栈中的元素转换为数组
+     * @return {T[]}
+     */
     list(): T[];
+    /**
+     * @description: 用于控制 JSON.stringify 时的序列化输出
+     * @return {T[]}
+     */
+    toJSON(): T[];
     /**
      * @description: 覆盖Object默认的toString
      * @return {String}
      */
     toString(): string;
-    toJSON(): T[];
 }

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

@@ -13,7 +13,7 @@ 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，需稳定且唯一
+ * 生成页面缓存 ID (CacheName)
+ * 采用全局唯一的 ULID 确保同一个路由在栈内打开多少次都是绝对隔离的不同实例。
  */
-export declare const createPageId: (tabId: string, path: string, query: object) => string;
+export declare const createPageId: () => string;