vue-stack-tabs 1.0.1 → 1.3.0

package/src/lib/hooks/useTabRouter.ts

@@ -1,65 +1,151 @@
 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'
 
-/** StackTabs 监听此事件切换前进动画 */
-const ROUTER_EVENT_FORWARD = 'FORWARD'
-/** StackTabs 监听此事件切换后退动画 */
-const ROUTER_EVENT_BACKWARD = 'BACKWARD'
+import { runNavigationTransaction } from './tabPanel/navigationTransaction'
+
+import { createPageId } from '../utils/tabInfoEncoder'
+
+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
  *
  * 职责：在单个标签内实现「前进/后退」栈式导航，以及滚动位置的记录与恢复
- * 使用范围：仅在标签内的页面组件中使用，依赖 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() {
   const instance = getCurrentInstance() as ComponentInternalInstance
   const { attrs, props } = instance
-  /** 当前标签 id，由 cache 组件的 dynamic-component 传入 */
+
+  /**
+   * 当前标签 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 */
+
+  /**
+   * 当前页面的缓存 ID（即 cacheName / keep-alive include 中的名称）。
+   * 用于 addScrollTarget 向 useTabPanel 绑定该页面的可滚动容器选择器。
+   */
   const pageId = (attrs.pId ?? props.pId) as string
 
   const route = useRoute()
   const router = useRouter()
   const emitter = useTabEmitter()
-  const { getTab, markCacheForEviction, getComponent, addPageScroller } = useTabPanel()
+  const { getTab, evictPageCache, addPageScroller, active: activateTab } = useTabPanel()
 
-  /** 当前标签的编码信息，用于 push 时保持 __tab */
+  /**
+   * 当前标签的编码信息字符串，存于 URL query.__tab。
+   * 每次 forward 时必须将此值一并带入新页面的 query，
+   * 确保 StackTabs 在 updatePageState 解析路由时能识别该请求归属于哪个标签，
+   * 而不是错误地新建一个陌生标签。
+   */
   const tabInfo = route.query.__tab as string
 
-  /** 注册需记录滚动位置的容器选择器 */
+  /** 注册需记录滚动位置的容器选择器，供 useTabPanel 在 deactivated/activated 时保存/恢复 */
   const addScrollTarget = (...selectors: string[]) => {
     addPageScroller(pageId, ...selectors)
   }
 
-  /** 前进：进栈，跳转到新页面 */
+  let navigationVersion = 0
+
+  /**
+   * 前进：将新路由推入该标签的 pages 栈，并触发前进动画。
+   */
   const forward = (to: RouteLocationPathRaw) => {
+    const tab = getTab(tabId)
+    const targetQuery = (to.query || {}) as LocationQueryRaw
+
+    if (tab) {
+      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)
+      }
+    })
   }
 
   /**
-   * 后退：从该标签的 pages 栈中 pop，并跳转到新栈顶
-   * @param to 数字=退几步，字符串=回退到首个路径匹配的页面
-   * @param backQuery 回退后传给目标页面的 props 数据（目标页通过 props 接收）
+   * 后退：从该标签的 pages 栈中弹出若干层页面，跳转到新栈顶。
+   *
+   * @param to        数字 = 退几步；字符串路径 = 回退到栈中首个路径匹配的页面
+   * @param backQuery 可选，回退后传递给目标页面的额外参数（目标页通过 props 接收）
+   *
+   * ⚠️ 关键时序约束 — 必须先导航再驱逐（详见原注释）
    */
-  const backward = (to: number | string, backQuery?: object) => {
+  const backward = (to: number | string, backQuery?: Record<string, unknown>) => {
     const tab = getTab(tabId)
-    if (!tab) return
+    if (!tab) return false
 
     const stack = tab.pages
     let steps = 0
@@ -68,42 +154,85 @@ export default function useTabRouter() {
       steps = Math.abs(to)
     } else {
       const parsed = parseUrl(to)
-      backQuery = defu(parsed.query, backQuery)
-      const pages = stack.list()
+      const targetQuery = parsed.query || {}
+      const pages = stack.readonlyList()
       let found = false
+
       for (let i = stack.size() - 2; i >= 0; i--) {
         steps++
-        if (pages[i]?.path === parsed.path) {
+        const page = pages[i]
+        if (
+          page?.path === parsed.path &&
+          isSameQueryIgnoringReserved(targetQuery, page?.query || {})
+        ) {
           found = true
           break
         }
       }
-      if (!found) return
+      if (!found) {
+        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
+      }
+    }
+
+    if (steps <= 0) return false
+
+    if (stack.size() <= steps) {
+      steps = stack.size() - 1
     }
 
-    if (steps <= 0 || stack.size() <= steps) return
+    if (steps <= 0) return false
 
+    const originalPages = stack.readonlyList().map((p) => clonePage(p))
+    const recyclingBin: string[] = []
     for (let i = 0; i < steps; i++) {
       const popped = stack.pop()
-      if (popped) markCacheForEviction(popped.id)
+      if (popped) recyclingBin.push(popped.id)
     }
 
     const target = stack.peek()
-    if (!target) return
+    if (!target) {
+      restorePages(stack, originalPages)
+      return false
+    }
 
-    const component = getComponent(target.id)
-    if (component && backQuery) {
-      const comp = component as {
-        components?: { DynamicComponent?: { props?: object } }
-      }
-      const dynamic = comp.components?.DynamicComponent
-      if (dynamic?.props) {
-        dynamic.props = defu(backQuery, dynamic.props)
-      }
+    if (backQuery) {
+      target._backParams = backQuery
     }
 
-    emitter.emit(ROUTER_EVENT_BACKWARD)
-    router.push({ path: target.path, query: target.query })
+    emitter.emit(TabEventType.BACKWARD)
+
+    const targetQueryWithTab = defu({ __tab: tabInfo }, target.query || {})
+    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
   }
 
   return {

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))
   }
 }