vue-stack-tabs 1.1.0 → 1.3.1

package/src/lib/hooks/useTabRouter.ts

@@ -1,19 +1,34 @@
 import { defu } from 'defu'
 import { getCurrentInstance } from 'vue'
 import type { ComponentInternalInstance } from 'vue'
-import type { RouteLocationPathRaw } from 'vue-router'
-import { useRoute, useRouter } from 'vue-router'
+import type { LocationQueryRaw, RouteLocationPathRaw } from 'vue-router'
+import type { ITabPage } from '../model/TabModel'
+import { isNavigationFailure, useRoute, useRouter } from 'vue-router'
 
 import useTabPanel from './useTabPanel'
-import { parseUrl } from '../utils/urlParser'
-import { useTabEmitter } from './useTabEventBus'
+import {
+  parseUrl,
+  cloneLocationQuery,
+  clonePage,
+  isSameQueryIgnoringReserved
+} from '../utils/urlParser'
+import { TabEventType, useTabEmitter } from './useTabEventBus'
+
+import { runNavigationTransaction } from './tabPanel/navigationTransaction'
 
 import { createPageId } from '../utils/tabInfoEncoder'
 
-/** StackTabs 监听此事件切换前进动画 */
-const ROUTER_EVENT_FORWARD = 'FORWARD'
-/** StackTabs 监听此事件切换后退动画 */
-const ROUTER_EVENT_BACKWARD = 'BACKWARD'
+interface PageStackLike {
+  clear: () => void
+  push: (page: ITabPage) => void
+}
+
+const restorePages = (stack: PageStackLike, pages: ITabPage[]) => {
+  stack.clear()
+  for (const page of pages) {
+    stack.push(clonePage(page))
+  }
+}
 
 /**
  * useTabRouter - 标签内路由 Hook
@@ -47,7 +62,7 @@ export default function useTabRouter() {
   const route = useRoute()
   const router = useRouter()
   const emitter = useTabEmitter()
-  const { getTab, evictPageCache, addPageScroller } = useTabPanel()
+  const { getTab, evictPageCache, addPageScroller, active: activateTab } = useTabPanel()
 
   /**
    * 当前标签的编码信息字符串，存于 URL query.__tab。
@@ -62,35 +77,62 @@ export default function useTabRouter() {
     addPageScroller(pageId, ...selectors)
   }
 
+  let navigationVersion = 0
+
   /**
    * 前进：将新路由推入该标签的 pages 栈，并触发前进动画。
-   *
-   * 实现细节：
-   * 1. 通过 defu 将 __tab 合并进 query，确保目标页面也携带正确的标签标识
-   *    （用户传入的 to.query 优先级更高，__tab 作为默认补全）
-   * 2. 发出 FORWARD 事件，StackTabs 切换为前进方向的转场动画
-   * 3. router.push 触发路由变更，StackTabs 的 tabWrapper → updatePageState
-   *    会在下次渲染时把目标页面压入 tab.pages 栈
    */
   const forward = (to: RouteLocationPathRaw) => {
     const tab = getTab(tabId)
-    const targetQuery = (to.query || {}) as Record<string, string>
+    const targetQuery = (to.query || {}) as LocationQueryRaw
 
     if (tab) {
-      // 【核心重构：数据前置压栈】
-      // 生成崭新独立的 CacheName，并推入专属页面栈
-      const newPageId = createPageId()
-      tab.pages.push({
-        id: newPageId,
-        tabId: tab.id,
-        path: to.path,
-        query: targetQuery
-      })
+      const top = tab.pages.peek()
+      if (top && top.path === to.path) {
+        if (isSameQueryIgnoringReserved(targetQuery, top.query || {})) {
+          if (!tab.active) {
+            activateTab(tab.id)
+          }
+          return
+        }
+      }
     }
 
     const query = defu({ __tab: tabInfo }, to.query)
-    emitter.emit(ROUTER_EVENT_FORWARD)
-    router.push({ path: to.path, query })
+    const transactionVersion = ++navigationVersion
+    emitter.emit(TabEventType.FORWARD)
+
+    let optimisticPageId = ''
+    runNavigationTransaction({
+      apply: () => {
+        const snapshot = tab ? tab.pages.readonlyList().map((p) => clonePage(p)) : []
+        if (tab) {
+          optimisticPageId = createPageId()
+          tab.pages.push({
+            id: optimisticPageId,
+            tabId: tab.id,
+            path: to.path,
+            query: cloneLocationQuery(targetQuery)
+          })
+        }
+        return snapshot
+      },
+      navigate: () => router.push({ path: to.path, query }),
+      rollback: (snapshot) => {
+        if (tab) restorePages(tab.pages, snapshot)
+      },
+      isFailureResult: isNavigationFailure,
+      isCurrent: () => navigationVersion === transactionVersion,
+      cleanupStale: () => {
+        if (!tab || !optimisticPageId) return
+        const pages = tab.pages.list().filter((page) => page.id !== optimisticPageId)
+        restorePages(tab.pages, pages)
+      }
+    }).catch((error: unknown) => {
+      if (!import.meta.env.PROD) {
+        console.warn('[vue-stack-tabs] forward navigation failed:', error)
+      }
+    })
   }
 
   /**
@@ -99,24 +141,7 @@ export default function useTabRouter() {
    * @param to        数字 = 退几步；字符串路径 = 回退到栈中首个路径匹配的页面
    * @param backQuery 可选，回退后传递给目标页面的额外参数（目标页通过 props 接收）
    *
-   * ───────────────────────────────────────────────────────
-   * ⚠️  关键时序约束 — 为什么必须先导航再驱逐？
-   * ───────────────────────────────────────────────────────
-   * evictPageCache 会立即同步修改响应式数组 caches.value（即 <keep-alive :include>）。
-   * 这个修改会触发 Vue 将 StackTabs 组件标记为 "需要重渲染"。
-   *
-   * 由于 router.push 是异步的（微任务队列），重渲染在 push 完成前就可能发生。
-   * 此时路由对象仍然指向被退出的页面，tabWrapper 以旧路由调用 resolvePageComponent，
-   * 而 components 里对应的 cacheName 已被删除 → resolvePageComponent 误判为"新页面"，
-   * 立刻重建组件 + 调用 addCache 将其加回 caches。
-   * 结果：驱逐了又原地复活，<keep-alive> 保留了旧实例（含用户输入状态）。
-   *
-   * ✅ 正确做法（本实现）：
-   *   1. 仅从 pages 栈中 pop，不立即驱逐
-   *   2. router.push(target) — 导航到前一页，路由切换后重渲染以新路由为基础
-   *   3. .then() 回调里安全执行 evictPageCache
-   *      此时旧页面已不再是"当前渲染目标"，不会被误重建
-   * ───────────────────────────────────────────────────────
+   * ⚠️ 关键时序约束 — 必须先导航再驱逐（详见原注释）
    */
   const backward = (to: number | string, backQuery?: Record<string, unknown>) => {
     const tab = getTab(tabId)
@@ -126,96 +151,85 @@ export default function useTabRouter() {
     let steps = 0
 
     if (typeof to === 'number') {
-      // 按步数退：取绝对值，防止调用方传入负数导致逻辑异常
       steps = Math.abs(to)
     } else {
-      // 按路径退：从栈顶向下扫描，找第一个 path 完全匹配的历史页面
       const parsed = parseUrl(to)
       const targetQuery = parsed.query || {}
-      const pages = stack.list()
+      const pages = stack.readonlyList()
       let found = false
 
-      // 精简版的参数匹配：如果调用方指定的 to.query 为空，就只要 path 匹配即可
-      // 若调用方指定了 query，则该 query 的每个键值必须在历史页面的 query 中存在且相等
-      const isQueryMatch = (pageQuery?: Record<string, unknown>) => {
-        const pq = { ...(pageQuery || {}) }
-        const tq = { ...targetQuery }
-        delete pq.__tab
-        delete pq._back
-        delete tq.__tab
-        delete tq._back
-
-        const tqKeys = Object.keys(tq)
-        if (tqKeys.length === 0) return true // 回退意图只要路径对了即可，不管历史曾有啥参数
-
-        return tqKeys.every((k) => String(tq[k] ?? '') === String(pq[k] ?? ''))
-      }
-
-      // 从 size-2 开始（size-1 是当前页，不算在候选范围内）
       for (let i = stack.size() - 2; i >= 0; i--) {
         steps++
         const page = pages[i]
-        const isSamePath = page?.path === parsed.path
-        const isSameQuery = isQueryMatch(page?.query)
-        console.log(
-          `[vue-stack-tabs backward] Checking pop candidate ${i}: path=${page?.path}, isSamePath=${isSamePath}, isSameQuery=${isSameQuery}`
-        )
-        if (isSamePath && isSameQuery) {
+        if (
+          page?.path === parsed.path &&
+          isSameQueryIgnoringReserved(targetQuery, page?.query || {})
+        ) {
           found = true
           break
         }
       }
-      // 栈中找不到目标路径，无法后退，返回警告
       if (!found) {
-        console.warn(
-          `[vue-stack-tabs] backward failed: target url '${to}' not found in history stack. Current stack: `,
-          JSON.parse(JSON.stringify(pages))
-        )
+        if (!import.meta.env.PROD) {
+          console.warn(
+            `[vue-stack-tabs] backward failed: target url '${to}' not found in history stack. Current stack: `,
+            pages.map((page) => clonePage(page))
+          )
+        }
         return false
       }
     }
 
-    // 边界保护：
-    // - steps <= 0：无效步数，不操作
     if (steps <= 0) return false
 
-    // - stack.size() <= steps：栈深不足，如果步数超限，最多只能退到首页（即首个页面，清空其他）。
     if (stack.size() <= steps) {
-      steps = stack.size() - 1 // 保留最后一层（首个推入的根页面）
+      steps = stack.size() - 1
     }
 
-    // 若修复后退之后步数仍为0，说明已经在根页面无可后退
     if (steps <= 0) return false
 
-    // 阶段 1：仅从 pages 栈弹出，收集 ID 入回收站
-    // （keep-alive 驱逐推迟到导航完成后，这就相当于您的回收站概念）
+    const originalPages = stack.readonlyList().map((p) => clonePage(p))
     const recyclingBin: string[] = []
     for (let i = 0; i < steps; i++) {
       const popped = stack.pop()
       if (popped) recyclingBin.push(popped.id)
     }
 
-    // 弹出后，栈顶即为目标回退页
     const target = stack.peek()
-    if (!target) return false
+    if (!target) {
+      restorePages(stack, originalPages)
+      return false
+    }
 
     if (backQuery) {
-      // 按照需求，将回退参数挂载在 _backParams 这个只活在页表栈的内存变量上
-      // 绝对隔离与不再污染真实 route.query 和 URL 跳转。
       target._backParams = backQuery
     }
 
-    emitter.emit(ROUTER_EVENT_BACKWARD)
+    emitter.emit(TabEventType.BACKWARD)
 
-    // 阶段 2：先导航，再清理回收站
-    // 对于 targetQuery 只需要带一个能够给框架定锚的 __tab。其他参数其实已经在 target.query 里。
     const targetQueryWithTab = defu({ __tab: tabInfo }, target.query || {})
-
-    // 用编程式导航发起回退路由
-    router.push({ path: target.path, query: targetQueryWithTab }).then(() => {
-      // 导航完成且微任务结束后，说明新目标已稳坐栈顶，此时清理回收站安全
-      for (const id of recyclingBin) {
-        evictPageCache(id)
+    const transactionVersion = ++navigationVersion
+
+    runNavigationTransaction({
+      apply: () => originalPages,
+      navigate: () => router.push({ path: target.path, query: targetQueryWithTab }),
+      rollback: (snapshot) => restorePages(stack, snapshot),
+      isFailureResult: isNavigationFailure,
+      isCurrent: () => navigationVersion === transactionVersion,
+      commit: () => {
+        for (const id of recyclingBin) {
+          evictPageCache(id)
+        }
+      },
+      cleanupStale: () => {
+        const activePageIds = new Set(stack.list().map((page) => page.id))
+        for (const id of recyclingBin) {
+          if (!activePageIds.has(id)) evictPageCache(id)
+        }
+      }
+    }).catch((error: unknown) => {
+      if (!import.meta.env.PROD) {
+        console.warn('[vue-stack-tabs] backward navigation failed:', error)
       }
     })
     return true

package/src/lib/i18n/index.ts

@@ -1,14 +1,59 @@
+/**
+ * 国际化模块。
+ *
+ * 自动加载 lang/ 目录下的语言文件，支持用户通过 plugin options
+ * 传入自定义语言包并与内置语言深度合并。
+ */
 import { createI18n } from 'vue-i18n-lite'
 
+export interface LocaleMessageOption {
+  locale: string
+  messages?: Record<string, unknown>
+}
+
+const DANGEROUS_MESSAGE_KEYS = new Set(['__proto__', 'constructor', 'prototype'])
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value)
+
+const mergeMessageRecord = (
+  baseMessage: Record<string, unknown>,
+  overrideMessage: Record<string, unknown>
+): Record<string, unknown> => {
+  const mergedMessage = { ...baseMessage }
+  for (const [key, value] of Object.entries(overrideMessage)) {
+    if (DANGEROUS_MESSAGE_KEYS.has(key)) continue
+    const existing = mergedMessage[key]
+    mergedMessage[key] =
+      isRecord(existing) && isRecord(value) ? mergeMessageRecord(existing, value) : value
+  }
+  return mergedMessage
+}
+
+export const mergeLocaleMessages = (
+  baseMessages: Record<string, Record<string, unknown>>,
+  localeI18n?: LocaleMessageOption[]
+): Record<string, Record<string, unknown>> => {
+  const combinedMessages = { ...baseMessages }
+  if (!localeI18n) return combinedMessages
+
+  for (const item of localeI18n) {
+    if (!item.messages || DANGEROUS_MESSAGE_KEYS.has(item.locale)) continue
+    combinedMessages[item.locale] = mergeMessageRecord(
+      combinedMessages[item.locale] ?? {},
+      item.messages
+    )
+  }
+
+  return combinedMessages
+}
+
 export default () => {
   // 引入lang目录下文件
   // 此处使用了 VITE 的 import.meta.globEager。非 VITE 的 可以使用 require.context
   const modules = import.meta.glob('./lang/*', { eager: true })
 
-  /**
-   * 获取所有语言文件
-   * @param {Object} mList
-   */
+  /** 从 glob 导入结果中提取语言文件并合并到 msg 对象 */
   function getLangFiles(
     mList: Record<string, { default?: Record<string, unknown> }>,
     msg: Record<string, Record<string, unknown>>
@@ -23,57 +68,20 @@ export default () => {
     }
   }
 
-  /**
-   * 注册i18n实例并引入语言文件
-   */
-  // const i18n = createI18n({
-  //   fallbackLocale: 'zh-CN',
-  //   // 定义默认语言为中文
-  //   locale: 'zh-CN',
-  //   legacy: false,
-  //   // 挂载到全局，不然会报错
-  //   // globalInjection: true,
-  //   messages: getAllLang(),
-  // })
-  /**
-   * 局部使用i18n
-   */
-  // const i18n = useI18n({
-  //   useScope: 'local',
-  //   locale: 'zh-CN',
-  //   messages: getAllLang(),
-  // })
-
-  // 假设你还有其他目录下的语言文件 它的路径是 src/views/home/locales/en-US.ts
-  // 那么你就可以 使用 :lower:（小写） :upper:（大写） 来引入文件
-  // const viewModules = import.meta.globEager('../views/**/locales/[[:lower:]][[:lower:]]-[[:upper:]][[:upper:]].ts')
-
   const allLangs = (): Record<string, Record<string, unknown>> => {
     const message: Record<string, Record<string, unknown>> = {}
     getLangFiles(modules as Record<string, { default?: Record<string, unknown> }>, message)
     return message
   }
-  // const localeI18n = inject('locales') as { locale: string; messages: object }
-  const getI18n = (localeI18n?: { locale: string; messages: Record<string, unknown> }[]) => {
-    const combinateMessage = { ...allLangs() }
-    if (localeI18n) {
-      for (const l of localeI18n) {
-        combinateMessage[l.locale] = l.messages
-      }
-      // combinateMessage = { ...allLangs(), ...localeI18n.messages }
-    }
+  /** 创建 i18n 实例，合并内置语言与用户自定义语言包 */
+  const getI18n = (localeI18n?: LocaleMessageOption[]) => {
+    const combinateMessage = mergeLocaleMessages(allLangs(), localeI18n)
 
     return createI18n({
-      locale: 'zh-CN',
+      locale: localeI18n?.[0]?.locale ?? 'zh-CN',
       fallbackLocale: 'en',
       messages: combinateMessage as Record<string, Record<string, string>>
     })
-    // const combinateMessage = { ...allLangs(), ...localeI18n.messages }
-    // return useI18n({
-    //   useScope: 'local',
-    //   locale: localeI18n.locale,
-    //   messages: combinateMessage
-    // })
   }
   return {
     getI18n

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

@@ -11,6 +11,11 @@ export default {
     restore: 'restore',
     undefined: 'undefined',
     loading: 'loading',
-    openInNewWindow: 'Open in new window'
+    iframeTitle: 'Embedded tab page',
+    iframeLoadTimeout: 'IFrame loading timed out',
+    retry: 'Retry',
+    openInNewWindow: 'Open in new window',
+    scrollLeft: 'Scroll left',
+    scrollRight: 'Scroll right'
   }
 }

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

@@ -11,6 +11,11 @@ export default {
     restore: '还原',
     undefined: '未命名',
     loading: '加载中',
-    openInNewWindow: '在新窗口打开'
+    iframeTitle: '标签页内嵌页面',
+    iframeLoadTimeout: 'iframe 加载超时',
+    retry: '重试',
+    openInNewWindow: '在新窗口打开',
+    scrollLeft: '向左滚动',
+    scrollRight: '向右滚动'
   }
 }

package/src/lib/i18n/stackTabsLocale.ts

@@ -0,0 +1,8 @@
+/** 将指定的 locale 应用到 vue-stack-tabs 内部 i18n 实例 */
+export const applyStackTabsLocale = (
+  changeLocale: (locale: string) => void,
+  locale?: string
+): void => {
+  if (!locale) return
+  changeLocale(locale)
+}

package/src/lib/iframe-bridge.ts

@@ -0,0 +1,12 @@
+/**
+ * iframe-bridge 子入口（vue-stack-tabs/iframe-bridge）。
+ *
+ * 供 iframe 内部页面引用，不包含 Vue 组件和样式等副作用，
+ * 仅导出 postMessage 通信工具。
+ */
+export { MSG_OPEN_TAB, MSG_REFRESH, onRefreshRequest, postOpenTab } from './utils/iframeBridge'
+export type {
+  IframeBridgeOptions,
+  IframeOpenTabPayload,
+  RefreshRequestOptions
+} from './utils/iframeBridge'

package/src/lib/index.ts

@@ -5,25 +5,21 @@
  * 安装：Vue.use(plugin) 注册全局组件 VueStackTabs、事件总线、i18n
  */
 import type { App } from 'vue'
-import i18n from './i18n'
+import i18n, { type LocaleMessageOption } from './i18n'
 import StackTab from './StackTabs.vue'
 import logVersion from './versionLogger'
+import { createStackTabsRuntimeContext, stackTabsContextKey } from './hooks/stackTabsContext'
+import { tabEmitterKey } from './hooks/useTabEventBus'
 import IFrame from './iframe.vue'
 import useTabLoading from './hooks/useTabLoading'
 import useTabRouter from './hooks/useTabRouter'
 import useTabActions from './hooks/useTabActions'
-import TabHeaderButton from '@/lib/components/TabHeader/TabHeaderButton.vue'
-import useTabEventBus from '@/lib/hooks/useTabEventBus'
+import TabHeaderButton from './components/TabHeader/TabHeaderButton.vue'
 import './assets/style/index.scss'
-//
-// const i18n = createI18n({
-//   legacy: false,
-//   locale: 'zh-CN',
-//   fallbackLocale: 'en-US'
-// })
+
+export type VueStackTabsPluginOptions = LocaleMessageOption[]
 
 export * from './model/TabModel'
-// Cutsom type
 declare module '@vue/runtime-core' {
   export interface GlobalComponents {
     VueStackTabs: typeof StackTab
@@ -36,18 +32,17 @@ export {
   useTabLoading,
   useTabRouter,
   TabHeaderButton,
-  StackTab
+  StackTab,
+  StackTab as VueStackTabs
 }
-export {
-  postOpenTab,
-  onRefreshRequest,
-  MSG_REFRESH,
-  MSG_OPEN_TAB
-} from './utils/iframeBridge'
+export { postOpenTab, onRefreshRequest, MSG_REFRESH, MSG_OPEN_TAB } from './utils/iframeBridge'
 export type { IframeOpenTabPayload } from './utils/iframeBridge'
 export default {
-  install(Vue: App, options?: { locale: string; messages: Record<string, unknown> }[]): void {
+  install(Vue: App, options?: VueStackTabsPluginOptions): void {
     logVersion(import.meta.env.PACKAGE_VERSION)
-    Vue.component('VueStackTabs', StackTab).use(useTabEventBus).use(i18n().getI18n(options))
+    const runtimeContext = createStackTabsRuntimeContext()
+    Vue.provide(stackTabsContextKey, runtimeContext)
+    Vue.provide(tabEmitterKey, runtimeContext.eventBus)
+    Vue.component('VueStackTabs', StackTab).use(i18n().getI18n(options))
   }
 }