vue-stack-tabs 1.3.1 → 1.4.1

package/src/lib/hooks/useTabPanel.tsx

@@ -12,17 +12,7 @@
  * 使用范围：内部 hook，由 StackTabs、useTabActions、useTabRouter、ContextMenu 调用
  */
 import type { ITabBase, ITabData, ITabItem, ITabPage } from '../model/TabModel'
-import {
-  defineComponent,
-  onActivated,
-  onDeactivated,
-  onMounted,
-  onUnmounted,
-  computed,
-  ref,
-  shallowRef,
-  cloneVNode
-} from 'vue'
+import { computed, ref } from 'vue'
 import type { DefineComponent, VNode } from 'vue'
 import { isNavigationFailure, useRouter } from 'vue-router'
 import type { RouteLocationNormalizedLoaded } from 'vue-router'
@@ -38,25 +28,17 @@ import {
   cloneLocationQuery,
   clonePage
 } from '../utils/urlParser'
-import PageLoading from '../components/PageLoading.vue'
 import { TabEventType, useTabEmitter } from './useTabEventBus'
 import { runNavigationTransaction } from './tabPanel/navigationTransaction'
 import { useI18n } from 'vue-i18n-lite'
 
-import { resolveStackTabsRuntimeContext } from './stackTabsContext'
+import { resolveStackTabsRuntimeContext, type StackTabsRuntimeContext } from './stackTabsContext'
 import { createTabPanelEviction } from './tabPanel/evict'
 import { createTabPanelScroll } from './tabPanel/scroll'
 import { createTabPanelSession } from './tabPanel/session'
 import { createTabPanelRefresh } from './tabPanel/refresh'
-
-/* eslint-disable vue/one-component-per-file */
-/** 占位组件：当路由组件为空或标签已被标记删除时返回 */
-const EmptyPlaceholderComponent = defineComponent({
-  name: 'StackTabEmptyPlaceholder',
-  setup() {
-    return () => null
-  }
-})
+import { createPageComponentFactory } from './tabPanel/pageComponentFactory'
+import { getEmptyPlaceholderComponent } from '../components/StackKeepAlive/emptyPlaceholder'
 
 const cloneRouteQuery = (route: RouteLocationNormalizedLoaded, tabInfo: ITabBase) => ({
   ...cloneLocationQuery(route.query),
@@ -71,11 +53,11 @@ export const normalizePathForCache = (route: RouteLocationNormalizedLoaded): str
   return matchPath === path ? path : route.path
 }
 
-export default () => {
+export default (providedRuntimeContext?: StackTabsRuntimeContext) => {
   const router = useRouter()
-  const emitter = useTabEmitter()
+  const runtimeContext = providedRuntimeContext ?? resolveStackTabsRuntimeContext()
+  const emitter = useTabEmitter(runtimeContext)
   const { t } = useI18n()
-  const runtimeContext = resolveStackTabsRuntimeContext()
   const {
     tabs,
     defaultTabs,
@@ -118,14 +100,15 @@ export default () => {
     const newTabs: ITabItem[] = []
 
     for (const item of staticTabs) {
+      // 先用默认值填充非空缺字段，避免在循环里提前求值生成用不到的 UUID。
       const fullItem = defu(item, {
-        id: crypto.randomUUID(),
         refreshable: true,
         closable: true,
         iframe: false
       })
-      const tabId = fullItem.id ?? crypto.randomUUID()
-      fullItem.id = tabId
+      // id 单独兜底，避免每次循环都无意义地调用 crypto.randomUUID。
+      fullItem.id = item.id ?? crypto.randomUUID()
+      const tabId = fullItem.id
       const uri = parseUrl(fullItem.path)
       const cacheName = createPageId()
       const page: ITabPage = {
@@ -158,7 +141,9 @@ export default () => {
     defaultTabs.value = [...defaultTabs.value, ...newDefaults]
     tabs.value = [...tabs.value, ...newTabs]
 
-    const storedTabJson = sessionStorage.getItem(getSessionKey())
+    // SSR 环境无 sessionStorage，直接跳过恢复。
+    const storedTabJson =
+      typeof window !== 'undefined' ? sessionStorage.getItem(getSessionKey()) : null
     const restoredTab = restoreTabFromSession(storedTabJson)
     if (restoredTab && !tabs.value.some((t) => t.id === restoredTab.id)) {
       if (restoredTab.url) restoredTab.url = toSafeTabUrl(restoredTab.url)
@@ -189,6 +174,31 @@ export default () => {
 
   const getTab = (id: string) => tabs.value.find((t) => t.id === id) ?? null
 
+  /**
+   * 唯一的标签激活状态写入口。即使标签对象保持不变，也替换列表引用，
+   * 让 TabHeader 与 iframe 视图在同一个响应式提交中观察到一致状态。
+   */
+  const setActiveTab = (id: string): ITabItem | null => {
+    let activeTab: ITabItem | null = null
+    tabs.value = tabs.value.map((tab) => {
+      tab.active = tab.id === id
+      if (tab.active) activeTab = tab
+      return tab
+    })
+    return activeTab
+  }
+
+  const { resolvePageComponent } = createPageComponentFactory({
+    runtimeContext,
+    getTab,
+    addCache,
+    evictMarkedCaches,
+    addPageScroller,
+    saveScroller,
+    restoreScroller,
+    removeScroller
+  })
+
   /**
    * 将指定标签移动到目标索引。标签对象本身不变，因此其页面栈和缓存关联保持不受影响。
    * @returns 是否实际调整了顺序
@@ -212,7 +222,22 @@ export default () => {
     return true
   }
 
-  /** 从路由解析 tabInfo，若无则创建默认信息，调用方负责把编码信息写入内部 page.query */
+  /** 把已有标签的对外字段提取为 ITabBase（用于让路由归属回该标签） */
+  const toTabBase = (tab: ITabItem): ITabBase => ({
+    id: tab.id,
+    title: tab.title,
+    closable: tab.closable,
+    refreshable: tab.refreshable,
+    iframe: tab.iframe,
+    iframeRefreshMode: tab.iframeRefreshMode
+  })
+
+  /**
+   * 从路由解析 tabInfo，若无则创建默认信息，调用方负责把编码信息写入内部 page.query。
+   *
+   * 首次进入应用时 URL 上通常还没有 __tab：此时优先接管 path 匹配的默认标签（defaultTabs），
+   * 由调用方把 __tab 写回地址，保证「URL 指向默认标签」；确实找不到归属时才新建兜底标签。
+   */
   const parseTabInfoFromRoute = (route: RouteLocationNormalizedLoaded): ITabBase => {
     if (typeof route.query.__tab === 'string') {
       const tabInfo = decodeTabInfo(route.query.__tab)
@@ -223,16 +248,15 @@ export default () => {
     const activeTab = tabs.value.find((tab) => tab.active)
     const activePage = activeTab?.pages.peek()
     if (activeTab && activePage?.path === path) {
-      return {
-        id: activeTab.id,
-        title: activeTab.title,
-        closable: activeTab.closable,
-        refreshable: activeTab.refreshable,
-        iframe: activeTab.iframe,
-        iframeRefreshMode: activeTab.iframeRefreshMode
-      }
+      return toTabBase(activeTab)
     }
 
+    // 当前激活标签与路由不一致：首屏 URL 无 __tab，或 session 恢复了上次激活的其它标签
+    //（演示应用在 iframe 中重载后 hash 为空即属此类）。此时接管栈顶 path 与当前路由一致的
+    // 标签（默认标签或已有标签），避免同一个页面既留下已有标签、又生成一个「未命名」的兜底标签。
+    const pathMatchedTab = tabs.value.find((tab) => tab.pages.peek()?.path === path)
+    if (pathMatchedTab) return toTabBase(pathMatchedTab)
+
     return {
       id: crypto.randomUUID(),
       title: t('VueStackTab.undefined'),
@@ -251,11 +275,7 @@ export default () => {
     cacheName: string,
     page: ITabPage
   ): ITabItem => {
-    let targetTab: ITabItem | null = null
-    for (const tab of tabs.value) {
-      tab.active = false
-      if (tab.id === tabInfo.id) targetTab = tab as ITabItem
-    }
+    let targetTab = tabInfo.id ? getTab(tabInfo.id) : null
 
     if (targetTab === null) {
       const pages = new Stack<ITabPage>()
@@ -272,10 +292,11 @@ export default () => {
         active: true,
         pages
       } as unknown as ITabItem
+      setActiveTab('')
       addTab(targetTab)
       emitter.emit(TabEventType.TAB_ACTIVE, { id: tabInfo.id!, isRoute: false })
     } else {
-      targetTab.active = true
+      setActiveTab(targetTab.id)
       if (targetTab.pages.isEmpty() || targetTab.pages.peek()!.id !== page.id) {
         targetTab.pages.push(page)
       }
@@ -331,7 +352,9 @@ export default () => {
           const stepsToPop = pagesList.length - 1 - foundIndex
           for (let i = 0; i < stepsToPop; i++) {
             const popped = targetTab.pages.pop()
-            if (popped) evictPageCache(popped.id)
+            // 仅标记待驱逐，由 onActivated 或下一拍 evictMarkedCaches 统一清理，
+            // 避免 watcher 同步执行与守卫拒绝路由之间产生不一致。
+            if (popped) markCacheForEviction(popped.id)
           }
           const newTop = targetTab.pages.peek()
           cacheName = newTop ? newTop.id : createPageId()
@@ -373,111 +396,21 @@ export default () => {
     if (page) {
       targetTab = findOrCreateTargetTab(tabInfo, route, cacheName, page)
     } else {
-      for (const t of tabs.value) t.active = false
-      targetTab!.active = true
+      setActiveTab(targetTab!.id)
     }
 
-    saveActiveTabToSession(targetTab!)
-    return { cacheName, tabInfo, targetTab: targetTab! }
-  }
-
-  /**
-   * 获取或创建与 cacheName 对应的 cacheComponent（keep-alive 包装组件）。
-   */
-  const resolvePageComponent = (ctx: {
-    cacheName: string
-    tabInfo: ITabBase
-    targetTab: ITabItem
-  }): DefineComponent => {
-    const { cacheName, tabInfo } = ctx
-
-    if (components.has(cacheName)) {
-      addCache(cacheName)
-      return components.get(cacheName)!
+    // 首屏 URL 往往没有 __tab（用户直接打开默认路由）：把解析出的标签编码写回地址，
+    // 保证 URL 始终指向当前标签；之后的导航各自会带上自己的 __tab。
+    if (typeof route.query.__tab !== 'string') {
+      void router.replace({
+        path: route.path,
+        query: { ...cloneLocationQuery(route.query), __tab: encodeTabInfo(tabInfo) },
+        hash: route.hash
+      })
     }
 
-    const cacheComponent = defineComponent({
-      name: cacheName,
-      props: {
-        vnode: {
-          type: Object as () => VNode,
-          required: false,
-          default: undefined
-        }
-      },
-      emits: ['onLoaded'],
-      setup(props, context) {
-        const localBackParams = ref<Record<string, unknown> | null>(null)
-        const lastVnode = shallowRef<VNode | null>(null)
-        const lastCloned = shallowRef<VNode | null>(null)
-        const lastBackParams = shallowRef<Record<string, unknown> | null>(null)
-
-        const checkAndConsumeBackParams = () => {
-          try {
-            const tab = getTab(tabInfo.id!)
-            const top = tab?.pages.peek()
-            if (top && top.id === cacheName && top._backParams) {
-              localBackParams.value = { ...top._backParams }
-              delete top._backParams
-            } else {
-              localBackParams.value = null
-            }
-          } catch {
-            localBackParams.value = null
-          }
-        }
-
-        onMounted(() => {
-          context.emit('onLoaded')
-          addPageScroller(cacheName, `#W-${cacheName}`)
-          checkAndConsumeBackParams()
-        })
-
-        onDeactivated(() => saveScroller(cacheName))
-
-        onActivated(() => {
-          context.emit('onLoaded')
-          restoreScroller(cacheName)
-          evictMarkedCaches()
-          tabIdsToEvict.clear()
-          checkAndConsumeBackParams()
-        })
-
-        onUnmounted(() => removeScroller(cacheName))
-
-        return () => {
-          // eslint-disable-next-line @typescript-eslint/no-explicit-any
-          const Node = (props as any).vnode as VNode
-          const backParams = localBackParams.value
-
-          if (Node !== lastVnode.value || backParams !== lastBackParams.value) {
-            const dynamicBackProps = backParams ? { _back: backParams } : {}
-            lastCloned.value = Node
-              ? cloneVNode(Node, { tId: tabInfo.id, pId: cacheName, ...dynamicBackProps })
-              : null
-            lastVnode.value = Node
-            lastBackParams.value = backParams
-          }
-
-          return (
-            <div
-              class="cache-page-wrapper"
-              id={`W-${cacheName}`}
-              style={[
-                runtimeContext.useGlobalScroll.value ? 'overflow:auto' : 'overflow:hidden',
-                'height: 100%'
-              ]}
-            >
-              {lastCloned.value}
-              <PageLoading tabId={tabInfo.id!} />
-            </div>
-          )
-        }
-      }
-    }) as DefineComponent
-    components.set(cacheName, cacheComponent)
-    addCache(cacheName)
-    return cacheComponent
+    saveActiveTabToSession(targetTab!)
+    return { cacheName, tabInfo, targetTab: targetTab! }
   }
 
   /** 当前正在渲染的页面的缓存 Key（ULID），供 StackTabs.vue 的 :key 绑定使用 */
@@ -495,7 +428,7 @@ export default () => {
     route: RouteLocationNormalizedLoaded,
     component?: VNode | null
   ): DefineComponent => {
-    if (!component) return EmptyPlaceholderComponent as DefineComponent
+    if (!component) return getEmptyPlaceholderComponent()
 
     const routeKey = route.fullPath + (route.query.__tab || '')
     if (routeKey === lastRouteKey && lastAddPageResult) {
@@ -503,7 +436,7 @@ export default () => {
     }
 
     const state = updatePageState(route)
-    if ('empty' in state) return EmptyPlaceholderComponent as DefineComponent
+    if ('empty' in state) return getEmptyPlaceholderComponent()
     if ('recovered' in state) {
       addCache(state.cacheName)
       activeCacheKey.value = state.cacheName
@@ -554,7 +487,7 @@ export default () => {
     if (tabList.length > 1 && tab.active) {
       activeTabId = (i === 0 ? tabList[1] : tabList[i - 1])?.id ?? ''
     }
-    tabList.splice(i, 1)
+    tabs.value = [...tabList.slice(0, i), ...tabList.slice(i + 1)]
 
     if (activeTabId) {
       emitter.emit(TabEventType.TAB_ACTIVE, { id: activeTabId })
@@ -569,32 +502,32 @@ export default () => {
 
   /** 批量关闭满足条件的可关闭标签，并统一标记其页面缓存待驱逐。 */
   const removeTabs = (shouldRemove: (tab: ITabItem, index: number) => boolean) => {
-    const tabList = tabs.value
-    for (let index = tabList.length - 1; index >= 0; index--) {
-      const tab = tabList[index]
-      if (!tab || !tab.closable || !shouldRemove(tab, index)) continue
+    const removed: ITabItem[] = []
+    const remaining = tabs.value.filter((tab, index) => {
+      if (!tab.closable || !shouldRemove(tab, index)) return true
       markTabPagesForEviction(tab)
       tab.pages.clear()
-      tabList.splice(index, 1)
-    }
+      removed.push(tab)
+      return false
+    })
+    tabs.value = remaining
+    return removed
   }
 
   const removeAllTabs = () => {
-    const tabList = tabs.value
     removeTabs(() => true)
-    const hasActive = tabList.some((t) => t.active)
+    const hasActive = tabs.value.some((t) => t.active)
     if (hasActive) {
       evictMarkedCaches()
       tabIdsToEvict.clear()
       return
     }
-    const last = tabList[tabList.length - 1]
+    const last = tabs.value.at(-1)
     if (last) emitter.emit(TabEventType.TAB_ACTIVE, { id: last.id })
   }
 
   const removeOtherTabs = (id: string) => {
-    const tabList = tabs.value
-    const activeTab = tabList.find((tab) => tab.id === id)
+    const activeTab = getTab(id)
     removeTabs((tab) => tab.id !== id)
     if (activeTab && !activeTab.active) {
       emitter.emit(TabEventType.TAB_ACTIVE, { id })
@@ -605,32 +538,30 @@ export default () => {
   }
 
   const removeLeftTabs = (id: string) => {
-    const tabList = tabs.value
-    const pivot = tabList.findIndex((t) => t?.id === id)
+    const pivot = tabs.value.findIndex((t) => t?.id === id)
     if (pivot <= 0) return
 
     removeTabs((_, index) => index < pivot)
-    if (tabList.some((t) => t.active)) {
+    if (tabs.value.some((t) => t.active)) {
       evictMarkedCaches()
       tabIdsToEvict.clear()
       return
     }
-    const first = tabList[0]
+    const first = tabs.value[0]
     if (first) emitter.emit(TabEventType.TAB_ACTIVE, { id: first.id })
   }
 
   const removeRightTabs = (id: string) => {
-    const tabList = tabs.value
-    const pivot = tabList.findIndex((t) => t?.id === id)
-    if (pivot < 0 || pivot >= tabList.length - 1) return
+    const pivot = tabs.value.findIndex((t) => t?.id === id)
+    if (pivot < 0 || pivot >= tabs.value.length - 1) return
 
     removeTabs((_, index) => index > pivot)
-    if (tabList.some((t) => t.active)) {
+    if (tabs.value.some((t) => t.active)) {
       evictMarkedCaches()
       tabIdsToEvict.clear()
       return
     }
-    const last = tabList[tabList.length - 1]
+    const last = tabs.value.at(-1)
     if (last) emitter.emit(TabEventType.TAB_ACTIVE, { id: last.id })
   }
 
@@ -660,11 +591,8 @@ export default () => {
 
     const top = target.pages.peek()
     const activateTarget = () => {
-      for (const tab of tabs.value) {
-        tab.active = tab.id === id
-      }
-      saveActiveTabToSession(target as ITabItem)
-      tabs.value = tabs.value.slice()
+      const activeTab = setActiveTab(id)
+      if (activeTab) saveActiveTabToSession(activeTab)
     }
 
     if (!route) {
@@ -683,21 +611,21 @@ export default () => {
       refreshable: target.refreshable,
       iframe: target.iframe
     })
-    const query = defu({ __tab }, top.query || {})
+    // __tab 是兜底标识，目标栈顶已带 __tab 时优先沿用，否则用我们刚编码的版本。
+    const query = defu(top.query || {}, { __tab })
 
     return runNavigationTransaction({
       apply: () => {
         const prevActiveId = tabs.value.find((tab) => tab.active)?.id
-        const sessionSnapshot = window.sessionStorage.getItem(getSessionKey())
+        // SSR 环境无 sessionStorage；快照为 null 时 rollback 视为「无变化」。
+        const sessionSnapshot =
+          typeof window !== 'undefined' ? window.sessionStorage.getItem(getSessionKey()) : null
         activateTarget()
         return { prevActiveId, sessionSnapshot }
       },
       navigate: () => router.push({ path: top.path, query }),
       rollback: (snapshot) => {
-        for (const tab of tabs.value) {
-          tab.active = tab.id === snapshot.prevActiveId
-        }
-        tabs.value = tabs.value.slice()
+        setActiveTab(snapshot.prevActiveId ?? '')
         restoreActiveTabSession(snapshot.sessionSnapshot)
       },
       isFailureResult: isNavigationFailure,

package/src/lib/hooks/useTabRouter.ts

@@ -98,7 +98,9 @@ export default function useTabRouter() {
       }
     }
 
-    const query = defu({ __tab: tabInfo }, to.query)
+    // __tab 是 StackTabs 解析路由归属标签的关键，优先沿用目标 query 已有的值，
+    // 避免被 to.query 中非字符串的同名 key 或缺失值覆盖。
+    const query = defu(to.query, { __tab: tabInfo })
     const transactionVersion = ++navigationVersion
     emitter.emit(TabEventType.FORWARD)
 
@@ -183,6 +185,12 @@ export default function useTabRouter() {
     if (steps <= 0) return false
 
     if (stack.size() <= steps) {
+      // 请求退栈步数大于当前可用层数时，仅退到栈底（首页）；开发模式下提示维护者。
+      if (!import.meta.env.PROD) {
+        console.warn(
+          `[vue-stack-tabs] backward requested ${steps} steps but stack only has ${stack.size() - 1} available.`
+        )
+      }
       steps = stack.size() - 1
     }
 
@@ -207,7 +215,8 @@ export default function useTabRouter() {
 
     emitter.emit(TabEventType.BACKWARD)
 
-    const targetQueryWithTab = defu({ __tab: tabInfo }, target.query || {})
+    // 栈顶 query 已带 __tab 时优先沿用，避免被默认 tabInfo 覆盖导致解析时识别错乱。
+    const targetQueryWithTab = defu(target.query || {}, { __tab: tabInfo })
     const transactionVersion = ++navigationVersion
 
     runNavigationTransaction({

package/src/lib/i18n/index.ts

@@ -49,8 +49,8 @@ export const mergeLocaleMessages = (
 }
 
 export default () => {
-  // 引入lang目录下文件
-  // 此处使用了 VITE 的 import.meta.globEager。非 VITE 的 可以使用 require.context
+  // 引入 lang 目录下文件
+  // 非 Vite 构建环境可改用 require.context 替换；当前使用 Vite 原生 glob 即可。
   const modules = import.meta.glob('./lang/*', { eager: true })
 
   /** 从 glob 导入结果中提取语言文件并合并到 msg 对象 */
@@ -58,7 +58,7 @@ export default () => {
     mList: Record<string, { default?: Record<string, unknown> }>,
     msg: Record<string, Record<string, unknown>>
   ) {
-    for (const path in mList) {
+    for (const path of Object.keys(mList)) {
       const mod = mList[path] as { default?: Record<string, unknown> }
       if (mod?.default) {
         const pathName = path.substring(path.lastIndexOf('/') + 1, path.lastIndexOf('.'))

package/src/lib/model/TabModel.ts

@@ -126,7 +126,46 @@ export class Stack<T> {
   }
 
   readonlyList(): readonly T[] {
-    return this.items
+    // 返回浅拷贝避免外部修改内部 items 引用，同时类型为 readonly T[] 提示调用方只读。
+    return [...this.items]
+  }
+
+  /**
+   * 查找首个匹配的元素。
+   * @returns 匹配的元素，未找到返回 undefined。
+   */
+  find(predicate: (element: T, index: number) => boolean): T | undefined {
+    return this.items.find(predicate)
+  }
+
+  /**
+   * 查找首个匹配元素的索引，未找到返回 -1。
+   */
+  findIndex(predicate: (element: T, index: number) => boolean): number {
+    return this.items.findIndex(predicate)
+  }
+
+  /**
+   * 返回所有匹配元素组成的浅拷贝数组。
+   */
+  filter(predicate: (element: T, index: number) => boolean): T[] {
+    return this.items.filter(predicate)
+  }
+
+  /**
+   * 是否存在任意匹配元素。
+   */
+  some(predicate: (element: T, index: number) => boolean): boolean {
+    return this.items.some(predicate)
+  }
+
+  /**
+   * 从顶到底反向遍历每个元素，便于实现「从栈顶开始找」等场景。
+   */
+  forEachTopDown(visit: (element: T, index: number) => void): void {
+    for (let i = this.items.length - 1; i >= 0; i--) {
+      visit(this.items[i] as T, i)
+    }
   }
 
   toJSON(): T[] {

package/src/lib/nuxt/module.ts

@@ -1,10 +1,10 @@
 /**
  * vue-stack-tabs Nuxt 模块。
  *
- * 自动注册客户端插件、注入 composables（useTabActions 等），
- * 并通过 runtimeConfig 传递 locale 配置。
+ * 自动注册客户端插件、注入 composables（useTabActions 等）、
+ * 注册全局组件 <VueStackTabs>，并通过 runtimeConfig 传递 locale 配置。
  */
-import { addPlugin, addImports, createResolver, defineNuxtModule } from 'nuxt/kit'
+import { addComponent, addImports, addPlugin, createResolver, defineNuxtModule } from 'nuxt/kit'
 
 export interface ModuleOptions {
   /** 默认语言 */
@@ -30,6 +30,13 @@ export default defineNuxtModule<ModuleOptions>({
       src: resolve('./runtime/plugin')
     })
 
+    // 自动注册全局组件 <VueStackTabs>，使用方无需在每个页面再 import。
+    addComponent({
+      name: 'VueStackTabs',
+      export: 'VueStackTabs',
+      filePath: resolve('../index.ts')
+    })
+
     addImports([
       { name: 'useTabActions', from: 'vue-stack-tabs' },
       { name: 'useTabRouter', from: 'vue-stack-tabs' },

package/src/lib/nuxt/runtime/plugin.ts

@@ -1,11 +1,22 @@
-/** Nuxt 客户端插件：自动注册 VueStackTabs 并应用 runtimeConfig 中的 locale 配置 */
+/**
+ * Nuxt 客户端插件：自动注册 VueStackTabs 并应用 runtimeConfig 中的 locale 配置。
+ */
 import { defineNuxtPlugin, useRuntimeConfig } from 'nuxt/app'
 import VueStackTabs from 'vue-stack-tabs'
+import { applyStackTabsLocale } from '../../i18n/stackTabsLocale'
+import { useI18n } from 'vue-i18n-lite'
 
 export default defineNuxtPlugin((nuxtApp) => {
   const config = useRuntimeConfig().public.vueStackTabs as {
     locale?: string
   }
+  const locale = config?.locale ?? 'zh-CN'
 
-  nuxtApp.vueApp.use(VueStackTabs, [{ locale: config?.locale ?? 'zh-CN' }])
+  // Vue.use 时把 locale 作为 plugin options 传入，让 i18n 实例按指定 locale 初始化。
+  nuxtApp.vueApp.use(VueStackTabs, [{ locale }])
+
+  // 兜底：应用 vue-stack-tabs 内部 i18n 实例的 locale 切换逻辑，
+  // 避免某些场景下 plugin options 未能正确初始化时 locale 仍是默认 zh-CN。
+  const { changeLocale } = useI18n()
+  applyStackTabsLocale(changeLocale, locale)
 })

package/src/lib/utils/iframeBridge.ts

@@ -53,8 +53,14 @@ export function postOpenTab(
 }
 
 /**
- * 在 iframe 内调用：注册刷新监听，收到父窗口刷新指令时执行 callback
+ * 在 iframe 内调用：注册刷新监听，收到父窗口刷新指令时执行 callback。
+ *
+ * **安全提示**：`options.allowedOrigins` 为空数组（默认值）时**不校验 origin**，
+ * 等同 `targetOrigin: '*'`，任何嵌入此 iframe 的父页面都能触发回调。
+ * 生产环境务必显式传入可信 origin 列表，例如 `['https://app.example.com']`。
+ *
  * @param callback 默认 location.reload()，可自定义
+ * @param options  可选配置，`allowedOrigins` 强烈建议显式传入
  * @returns 取消监听的函数
  */
 export function onRefreshRequest(
@@ -66,6 +72,8 @@ export function onRefreshRequest(
   const allowedOrigins = options.allowedOrigins ?? []
   const handler = (ev: MessageEvent) => {
     if (ev.source !== window.parent) return
+    // allowedOrigins 为空时跳过 origin 校验：刻意保留以便本地调试，
+    // 但必须在文档中向用户强调风险（见上方 JSDoc）。
     if (allowedOrigins.length > 0 && !allowedOrigins.includes(ev.origin)) return
     if (ev.data?.type === MSG_REFRESH) {
       callback()