vue-stack-tabs 2.2.0 → 2.3.0

package/src/lib/hooks/useScrollShadow.ts

@@ -13,6 +13,8 @@
  *  - 阈值（默认 5px）内视为已贴边（≤ 阈值）→ 隐藏阴影；超过阈值视为可继续滚动 → 显示阴影
  *  - SSR 安全：在 document 不存在时直接返回
  *  - 自动清理：onScopeDispose 移除监听并取消 rAF/disconnect observer
+ *  - 阴影类可以挂到另一个不参与 transform 的元素上：滚动容器的 ::after 一旦
+ *    跟随 transform（例如页面刷新动画），绝对定位的包含块就会变化，阴影会错位/消失
  */
 import { onScopeDispose, type Ref } from 'vue'
 
@@ -22,8 +24,15 @@ const SHADOW_VERTICAL_CLASS = 'stack-tab__shadow-inset-vertical'
 const DEFAULT_EDGE_THRESHOLD = 5
 
 export interface UseScrollShadowOptions {
-  /** 容器元素的 ref，可以是 Ref<HTMLElement | null> 或 getter 函数 */
+  /** 滚动容器：用于监听 scroll / resize 并读取滚动尺寸 */
   target: Ref<HTMLElement | null> | (() => HTMLElement | null)
+  /**
+   * 阴影类挂载目标，默认与 target 相同。
+   * 当 target 参与 transform 动画（如刷新转场）时，应传入不参与动画的祖先
+   * （例如 .stack-tab__keep-alive-panel），否则 ::after 的绝对定位包含块会变化，
+   * 阴影会随动画错位或消失。
+   */
+  classTarget?: Ref<HTMLElement | null> | (() => HTMLElement | null)
   /**
    * 是否监听内容缩放/尺寸变化（默认 true）。
    * 启用后会用 ResizeObserver 监视目标尺寸，容器或子树尺寸变化都会重新计算阴影边界。
@@ -37,8 +46,10 @@ export interface UseScrollShadowOptions {
 }
 
 export interface UseScrollShadowReturn {
-  /** 手动同步一次（用于内容变化/resize 后） */
+  /** 重新解析滚动/阴影目标并同步一次（用于 keep-alive 激活、DOM 重新挂载后） */
   sync: () => void
+  /** 移除阴影类并取消待执行的 rAF（用于 keep-alive 失活） */
+  clear: () => void
 }
 
 const resolveTarget = (
@@ -47,18 +58,36 @@ const resolveTarget = (
 
 export const useScrollShadow = (options: UseScrollShadowOptions): UseScrollShadowReturn => {
   if (typeof document === 'undefined') {
-    return { sync: () => undefined }
+    return { sync: () => undefined, clear: () => undefined }
   }
 
   const watchResize = options.watchResize !== false
   const edgeThreshold = Math.max(0, options.edgeThreshold ?? DEFAULT_EDGE_THRESHOLD)
   let rafId: number | null = null
   let attached: HTMLElement | null = null
+  let classElement: HTMLElement | null = null
   let resizeObserver: ResizeObserver | null = null
 
+  const clearClasses = (element: HTMLElement | null): void => {
+    if (!element) return
+    element.classList.remove(SHADOW_TOP_CLASS, SHADOW_BOTTOM_CLASS, SHADOW_VERTICAL_CLASS)
+  }
+
+  /** 阴影类目标：配置了 classTarget 时必须真实解析到，否则宁可不显示（激活后会 sync 重试） */
+  const resolveClassTarget = (): HTMLElement | null =>
+    options.classTarget ? resolveTarget(options.classTarget) : attached
+
   const recompute = (): void => {
     if (!attached) return
     const target = attached
+    const nextClassTarget = resolveClassTarget()
+    if (classElement && classElement !== nextClassTarget) {
+      clearClasses(classElement)
+      classElement = null
+    }
+    classElement = nextClassTarget
+    if (!classElement) return
+
     const { scrollTop, scrollHeight, clientHeight } = target
     const distanceToTop = scrollTop
     const distanceToBottom = scrollHeight - clientHeight - scrollTop
@@ -69,9 +98,9 @@ export const useScrollShadow = (options: UseScrollShadowOptions): UseScrollShado
     // 注意：-top / -bottom 是两个独立 CSS 规则、作用在同一个 ::after 上，
     // 同时加会互相覆盖（后定义的 -bottom 胜出）。因此这里互斥地只加一个类：
     // 两侧都有内容用 -vertical，只有一侧用 -top / -bottom，贴边时都不加。
-    target.classList.toggle(SHADOW_VERTICAL_CLASS, showTopShadow && showBottomShadow)
-    target.classList.toggle(SHADOW_TOP_CLASS, showTopShadow && !showBottomShadow)
-    target.classList.toggle(SHADOW_BOTTOM_CLASS, !showTopShadow && showBottomShadow)
+    classElement.classList.toggle(SHADOW_VERTICAL_CLASS, showTopShadow && showBottomShadow)
+    classElement.classList.toggle(SHADOW_TOP_CLASS, showTopShadow && !showBottomShadow)
+    classElement.classList.toggle(SHADOW_BOTTOM_CLASS, !showTopShadow && showBottomShadow)
   }
 
   const schedule = (): void => {
@@ -84,11 +113,17 @@ export const useScrollShadow = (options: UseScrollShadowOptions): UseScrollShado
 
   const attach = (): void => {
     const el = resolveTarget(options.target)
-    if (!el || el === attached) return
+    if (!el) return
+    if (el === attached) {
+      schedule()
+      return
+    }
     if (attached) {
       attached.removeEventListener('scroll', schedule)
       resizeObserver?.disconnect()
       resizeObserver = null
+      clearClasses(classElement)
+      classElement = null
     }
     attached = el
     el.addEventListener('scroll', schedule, { passive: true })
@@ -99,18 +134,40 @@ export const useScrollShadow = (options: UseScrollShadowOptions): UseScrollShado
     schedule()
   }
 
-  const detach = (): void => {
-    if (attached) {
-      attached.removeEventListener('scroll', schedule)
-      attached.classList.remove(SHADOW_TOP_CLASS, SHADOW_BOTTOM_CLASS, SHADOW_VERTICAL_CLASS)
-      attached = null
+  const cancelScheduled = (): void => {
+    if (rafId === null) return
+    cancelAnimationFrame(rafId)
+    rafId = null
+  }
+
+  const clear = (): void => {
+    clearClasses(classElement)
+    classElement = null
+    cancelScheduled()
+  }
+
+  /** 重新解析目标：keep-alive 激活或 DOM 重新挂载后由调用方触发 */
+  const sync = (): void => {
+    const el = resolveTarget(options.target)
+    if (!el) {
+      clear()
+      return
+    }
+    if (el !== attached) {
+      attach()
+      return
     }
+    schedule()
+  }
+
+  const detach = (): void => {
+    if (attached) attached.removeEventListener('scroll', schedule)
+    attached = null
     resizeObserver?.disconnect()
     resizeObserver = null
-    if (rafId !== null) {
-      cancelAnimationFrame(rafId)
-      rafId = null
-    }
+    clearClasses(classElement)
+    classElement = null
+    cancelScheduled()
   }
 
   // 初始挂载（target 可能是异步插入的 DOM，使用 microtask 等一帧）
@@ -118,7 +175,5 @@ export const useScrollShadow = (options: UseScrollShadowOptions): UseScrollShado
 
   onScopeDispose(detach)
 
-  return {
-    sync: () => schedule()
-  }
+  return { sync, clear }
 }

package/src/lib/hooks/useTabActions.ts

@@ -1,4 +1,4 @@
-import { isNavigationFailure, useRouter } from 'vue-router'
+import { isNavigationFailure, NavigationFailureType, useRouter } from 'vue-router'
 import type { LocationQueryRaw } from 'vue-router'
 import { defu } from 'defu'
 import useTabPanel from './useTabPanel'
@@ -95,7 +95,7 @@ export default function useTabActions(providedRuntimeContext?: StackTabsRuntimeC
         return
       }
 
-      navigateToTab(tab, tabInfo).then(
+      navigateToTab(tab, tabInfo, isExistingTab && renew).then(
         () => resolve(tabInfo.id),
         (error) => {
           rollbackRenew?.()
@@ -107,7 +107,7 @@ export default function useTabActions(providedRuntimeContext?: StackTabsRuntimeC
   }
 
   /** 执行路由跳转到标签对应页面（普通路由或 iframe 占位路由） */
-  const navigateToTab = (tab: ITabData, tabInfo: ITabData) => {
+  const navigateToTab = (tab: ITabData, tabInfo: ITabData, allowDuplicatedNavigation = false) => {
     const __tab = encodeTabInfo(tabInfo)
     const tabQuery = omitStackTabsReservedQuery(tab.query)
     let query = defu(tabQuery, { __tab }) as LocationQueryRaw
@@ -137,7 +137,13 @@ export default function useTabActions(providedRuntimeContext?: StackTabsRuntimeC
       apply: () => undefined,
       navigate: () => router.push({ path, query, hash }),
       rollback: () => undefined,
-      isFailureResult: isNavigationFailure,
+      // renew 当前标签时地址可能不变：vue-router 会返回 duplicated NavigationFailure，
+      // 这属于预期结果（refreshKey 会触发页面重新解析），不应让 openTab reject。
+      isFailureResult: (result) =>
+        isNavigationFailure(result) &&
+        !(
+          allowDuplicatedNavigation && isNavigationFailure(result, NavigationFailureType.duplicated)
+        ),
       rejectFailureResult: true
     })
   }

package/src/lib/hooks/useTabEventBus.ts

@@ -19,6 +19,8 @@ declare module '@vue/runtime-core' {
 export enum TabEventType {
   PAGE_LOADING = 'PAGE_LOADING',
   TAB_ACTIVE = 'TAB_ACTIVE',
+  /** 请求标签栏将指定标签滚动到可视区域（不改变激活状态） */
+  TAB_SCROLL_TO = 'TAB_SCROLL_TO',
   FORWARD = 'FORWARD',
   BACKWARD = 'BACKWARD',
   REFRESH_IFRAME_POSTMESSAGE = 'REFRESH_IFRAME_POSTMESSAGE'
@@ -27,6 +29,7 @@ export enum TabEventType {
 export interface TabEventPayloadMap extends Record<EventType, unknown> {
   [TabEventType.PAGE_LOADING]: { tId: string; value: boolean }
   [TabEventType.TAB_ACTIVE]: { id: string; isRoute?: boolean }
+  [TabEventType.TAB_SCROLL_TO]: { id: string }
   [TabEventType.FORWARD]: void
   [TabEventType.BACKWARD]: void
   [TabEventType.REFRESH_IFRAME_POSTMESSAGE]: string

package/src/lib/hooks/useTabPanel.tsx

@@ -61,7 +61,7 @@ const createTabPanelApi = (runtimeContext: StackTabsRuntimeContext) => {
   const router = useRouter()
   const emitter = useTabEmitter(runtimeContext)
   const { t } = useI18n()
-  const { tabs, defaultTabs, caches, refreshKey, iframeRefreshKeys, isInitialized } = runtimeContext
+  const { tabs, caches, refreshKey, iframeRefreshKeys, isInitialized } = runtimeContext
   const store = getTabStore(runtimeContext)
   const {
     getTabs,
@@ -126,14 +126,13 @@ const createTabPanelApi = (runtimeContext: StackTabsRuntimeContext) => {
    * @param homeTab - 固定首页；始终位于第一位、不可关闭、不可移动
    */
   const initialize = (staticTabs: ITabData[], homeTab?: ITabData) => {
-    // 重复调用会累加 defaultTabs 并重复注册标签；初始化后直接忽略。
+    // 重复调用会重复注册标签；初始化后直接忽略。
     if (isInitialized.value) {
       if (!import.meta.env.PROD) {
         console.warn('[vue-stack-tabs] initialize() called more than once; ignored.')
       }
       return
     }
-    const newDefaults: ITabItem[] = []
     const newTabs: ITabItem[] = []
     let homeTabId = ''
 
@@ -152,13 +151,27 @@ const createTabPanelApi = (runtimeContext: StackTabsRuntimeContext) => {
       fullItem.id = item.id ?? (options.pinned ? DEFAULT_HOME_TAB_ID : createId())
       if (options.closable !== undefined) fullItem.closable = options.closable
       const tabId = fullItem.id
+      const isIframe = Boolean(fullItem.iframe)
       const uri = parseUrl(fullItem.path)
       const cacheName = createPageId()
+      // iframe 标签的 path 是外部 URL：路由侧用 iframePath + __src 承载，
+      // 与 openTab 的语义保持一致（否则默认 iframe 标签会渲染 about:blank）。
+      const pagePath = isIframe
+        ? normalizePathname(runtimeContext.iframePath.value)
+        : normalizePathname(uri.path)
+      const iframeRefreshMode = isIframe
+        ? (fullItem.iframeRefreshMode ??
+          (isCrossOriginUrl(fullItem.path) ? 'reload' : 'postMessage'))
+        : 'postMessage'
+      // 把生效的刷新模式写回 fullItem，保证 __tab 与会话恢复得到一致的 iframe 刷新语义。
+      fullItem.iframeRefreshMode = iframeRefreshMode
+      const pageQuery = omitStackTabsReservedQuery(isIframe ? fullItem.query : uri.query)
+      if (isIframe) pageQuery.__src = encodeURIComponent(fullItem.path)
       const page: ITabPage = {
         id: cacheName,
         tabId,
-        path: normalizePathname(uri.path),
-        query: defu(omitStackTabsReservedQuery(uri.query), { __tab: encodeTabInfo(fullItem) })
+        path: pagePath,
+        query: defu(pageQuery, { __tab: encodeTabInfo(fullItem) })
       }
       const pages = new Stack<ITabPage>()
       pages.push(page)
@@ -167,11 +180,9 @@ const createTabPanelApi = (runtimeContext: StackTabsRuntimeContext) => {
         title: fullItem.title ?? '',
         closable: fullItem.closable!,
         refreshable: fullItem.refreshable!,
-        iframe: fullItem.iframe!,
-        iframeRefreshMode:
-          (fullItem as { iframeRefreshMode?: string }).iframeRefreshMode === 'reload'
-            ? 'reload'
-            : 'postMessage',
+        iframe: isIframe,
+        iframeRefreshMode,
+        url: isIframe ? toSafeTabUrl(fullItem.path) : undefined,
         active: false,
         pages,
         pinned: options.pinned
@@ -184,7 +195,6 @@ const createTabPanelApi = (runtimeContext: StackTabsRuntimeContext) => {
     if (homeTab) {
       const home = buildTab(homeTab, { pinned: true, closable: false })
       homeTabId = home.id
-      newDefaults.push(home)
       newTabs.push({ ...home })
     }
 
@@ -200,11 +210,9 @@ const createTabPanelApi = (runtimeContext: StackTabsRuntimeContext) => {
         continue
       }
       const tab = buildTab(item)
-      newDefaults.push(tab)
       newTabs.push({ ...tab })
     }
 
-    defaultTabs.value = [...defaultTabs.value, ...newDefaults]
     addTabs(newTabs)
 
     // SSR 环境无 sessionStorage，直接跳过恢复。
@@ -442,10 +450,8 @@ const createTabPanelApi = (runtimeContext: StackTabsRuntimeContext) => {
     let cacheName: string
     let page: ITabPage | null = null
 
-    if (targetTab && getTopPage(targetTab.id)) {
-      const top = getTopPage(targetTab.id)!
-      if (!top) throw new Error('[vue-stack-tabs] Stack is not empty but peek() returned undefined')
-
+    const top = targetTab ? getTopPage(targetTab.id) : null
+    if (targetTab && top) {
       if (isSameLocation(top)) {
         cacheName = top.id
       } else if (top.path === path) {
@@ -525,11 +531,17 @@ const createTabPanelApi = (runtimeContext: StackTabsRuntimeContext) => {
     // 首屏 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
-      })
+      void router
+        .replace({
+          path: route.path,
+          query: { ...cloneLocationQuery(route.query), __tab: encodeTabInfo(tabInfo) },
+          hash: route.hash
+        })
+        .catch((error: unknown) => {
+          if (!import.meta.env.PROD) {
+            console.warn('[vue-stack-tabs] Failed to attach __tab to the current URL:', error)
+          }
+        })
     }
 
     saveActiveTabToSession(targetTab!)
@@ -558,7 +570,8 @@ const createTabPanelApi = (runtimeContext: StackTabsRuntimeContext) => {
       return getEmptyPlaceholderComponent()
     }
 
-    const routeKey = route.fullPath + (route.query.__tab || '')
+    // fullPath 已包含完整 query（含 __tab）与 hash；refreshKey 让 renew 能强制重新解析同一地址。
+    const routeKey = `${route.fullPath}::${refreshKey.value}`
     if (routeKey === lastRouteKey && lastAddPageResult) {
       return lastAddPageResult
     }
@@ -687,7 +700,11 @@ const createTabPanelApi = (runtimeContext: StackTabsRuntimeContext) => {
     emitter.emit(TabEventType.FORWARD)
     const target = getTab(id)
     if (!target) return Promise.resolve()
-    if (target.active) return Promise.resolve()
+    if (target.active) {
+      // 已是激活标签时仍需通知标签栏确保其可见（用户可能已把标签栏滚开）。
+      emitter.emit(TabEventType.TAB_SCROLL_TO, { id })
+      return Promise.resolve()
+    }
 
     const top = getTopPage(id)
     const activateTarget = () => {
@@ -704,15 +721,11 @@ const createTabPanelApi = (runtimeContext: StackTabsRuntimeContext) => {
       return Promise.resolve()
     }
 
-    const __tab = encodeTabInfo({
-      id: target.id,
-      title: target.title,
-      closable: target.closable,
-      refreshable: target.refreshable,
-      iframe: target.iframe
-    })
-    // __tab 是兜底标识，目标栈顶已带 __tab 时优先沿用，否则用我们刚编码的版本。
-    const query = defu(top.query || {}, { __tab })
+    // __tab 是兜底标识：目标栈顶已带 __tab 时直接沿用，避免每次激活都重新编码。
+    const query = cloneLocationQuery(top.query)
+    if (typeof query.__tab !== 'string' || !query.__tab) {
+      query.__tab = encodeTabInfo(toTabBase(target))
+    }
 
     return runNavigationTransaction({
       apply: () => {
@@ -737,7 +750,6 @@ const createTabPanelApi = (runtimeContext: StackTabsRuntimeContext) => {
 
   const destroy = () => {
     resetStore()
-    defaultTabs.value = []
     iframeRefreshKeys.value = {}
     runtimeContext.scrollPositionsByPageId.clear()
     runtimeContext.isInitialized.value = false

package/src/lib/model/TabModel.ts

@@ -17,22 +17,31 @@ export enum TabScrollMode {
   BOTH = 'both'
 }
 
-/** 标签栏滚动条拖拽时的临时状态 */
+/**
+ * @deprecated 标签栏拖拽内部已不再使用该类型；保留仅为兼容 2.x 的公开类型导出，
+ * 将在下一个大版本移除。
+ */
 export interface DragData {
   thumbLeft: number
   startScrollLeft: number
   startThumbLeft: number
   startPageX: number
 }
-/** 滚动条滑块计算所需的数据 */
+
+/**
+ * @deprecated 内部滚轮/滚动事件常量已不再使用该类型；保留仅为兼容 2.x 的公开类型导出，
+ * 将在下一个大版本移除。
+ */
+export type ScrollEvents = {
+  ScrollUpdate: void
+}
+
+/** 滚动条滑块计算所需的数据（滚动过程中保持非响应式） */
 export interface ScrollData {
   clientWidth: number
   scrollWidth: number
   scrollLeft: number
 }
-export type ScrollEvents = {
-  ScrollUpdate: void
-}
 
 /** 打开标签时传入的完整数据（含 path、query） */
 export interface ITabData extends ITabBase {

package/src/lib/nuxt/module.ts

@@ -34,7 +34,9 @@ export default defineNuxtModule<ModuleOptions>({
     addComponent({
       name: 'VueStackTabs',
       export: 'VueStackTabs',
-      filePath: resolve('../index.ts')
+      // 指向发布产物（dist/vue-stack-tabs.es.js）中的命名导出；
+      // 源码入口 ../index.ts 不会被发布，Nuxt 构建时会解析失败。
+      filePath: resolve('../vue-stack-tabs.es.js')
     })
 
     addImports([

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

@@ -4,7 +4,7 @@
 import { defineNuxtPlugin, useRuntimeConfig } from 'nuxt/app'
 import VueStackTabs from 'vue-stack-tabs'
 import { applyStackTabsLocale } from '../../i18n/stackTabsLocale'
-import { useI18n } from 'vue-i18n-lite'
+import { useI18n, type I18n } from 'vue-i18n-lite'
 
 export default defineNuxtPlugin((nuxtApp) => {
   const config = useRuntimeConfig().public.vueStackTabs as {
@@ -17,6 +17,10 @@ export default defineNuxtPlugin((nuxtApp) => {
 
   // 兜底：应用 vue-stack-tabs 内部 i18n 实例的 locale 切换逻辑，
   // 避免某些场景下 plugin options 未能正确初始化时 locale 仍是默认 zh-CN。
-  const { changeLocale } = useI18n()
-  applyStackTabsLocale(changeLocale, locale)
+  //
+  // 必须在 app 的注入上下文中取实例：插件顶层直接 inject() 拿不到 app.provide 的值。
+  nuxtApp.vueApp.runWithContext(() => {
+    const i18n = useI18n() as I18n | undefined
+    if (i18n?.changeLocale) applyStackTabsLocale(i18n.changeLocale, locale)
+  })
 })

package/src/lib/utils/scrollUtils.ts

@@ -71,24 +71,6 @@ export function scrollIntoView({
   }
 }
 
-/** 获取系统滚动条宽度（用于布局计算） */
-export const getScrollbarWidth = (function () {
-  let width: number | null = null
-
-  return function () {
-    if (width !== null) return width
-
-    const div = document.createElement('div')
-
-    div.style.cssText = 'width: 100px; height: 100px;overflow-y: scroll'
-    document.body.appendChild(div)
-    width = div.offsetWidth - div.clientWidth
-    div.parentElement?.removeChild(div)
-
-    return width
-  }
-})()
-
 const Z_INDEX_CEILING = 89999
 
 /**

package/src/lib/utils/tabInfoEncoder.ts

@@ -22,7 +22,7 @@ interface EncodedTabInfoV1 {
 const MAX_DECODED_TAB_INFO_LENGTH = 2048
 const MAX_ENCODED_TAB_INFO_LENGTH = 4096
 /** URL 中 __tab 的 title 上限，避免超长标题把 payload 顶到解码上限导致 id 丢失。 */
-export const MAX_TAB_TITLE_LENGTH = 256
+const MAX_TAB_TITLE_LENGTH = 256
 /** legacy 格式中 id 的合理上限，用于拒绝任意字符串伪装成标签 id。 */
 const MAX_LEGACY_TAB_ID_LENGTH = 128
 
@@ -130,7 +130,7 @@ export const encodeTabInfo = (tabData: ITabBase): string => {
   return encodeBase64Url(JSON.stringify(payload))
 }
 
-export const decodeTabInfo = (encoded: string): ITabBase => {
+const decodeTabInfoUncached = (encoded: string): ITabBase => {
   if (typeof encoded !== 'string' || encoded.length > MAX_ENCODED_TAB_INFO_LENGTH) {
     return { ...DEFAULT_TAB_INFO }
   }
@@ -152,6 +152,25 @@ export const decodeTabInfo = (encoded: string): ITabBase => {
   }
 }
 
+/**
+ * 单条解码缓存：同一 __tab 在一次会话/连续导航中会反复出现，
+ * 缓存最近一次结果可省掉 Base64 + TextDecoder + JSON.parse。
+ * 返回值始终是副本，避免调用方修改缓存对象。
+ */
+let cachedEncodedTabInfo = ''
+let cachedTabInfo: ITabBase | null = null
+
+export const decodeTabInfo = (encoded: string): ITabBase => {
+  if (encoded === cachedEncodedTabInfo && cachedTabInfo) {
+    return { ...cachedTabInfo }
+  }
+
+  const decoded = decodeTabInfoUncached(encoded)
+  cachedEncodedTabInfo = encoded
+  cachedTabInfo = decoded
+  return { ...decoded }
+}
+
 /**
  * 生成运行时 id。
  *

package/src/lib/utils/urlParser.ts

@@ -44,15 +44,6 @@ export function isAllowedTabUrl(url: string): boolean {
   }
 }
 
-/**
- * 判断是否为不允许嵌入 iframe 的 URL
- * @param url - 待检查的 URL 字符串
- * @returns 非 allowlist URL 返回 true
- */
-export function isInvalidIframeUrl(url: string): boolean {
-  return !isAllowedTabUrl(url)
-}
-
 /** 非法 URL 降级为 about:blank，避免进入 iframe/window.open 等 URL sink */
 export function toSafeTabUrl(url: string): string {
   return isAllowedTabUrl(url) ? url : 'about:blank'
@@ -152,39 +143,51 @@ export function clonePage<T extends CloneablePage>(page: T): T {
   }
 }
 
-/** 忽略 __tab/__src/_back 等内部保留 key 后比较两个 query 是否等价 */
+/** 判断 key 是否为 vue-stack-tabs 内部保留参数（含后退参数 _back） */
+const isIgnoredQueryKey = (key: string): boolean =>
+  STACK_TABS_RESERVED_QUERY_KEYS.has(key) || key === '_back'
+
+/** 比较两个 query 值：数组按元素逐个比较，标量按字符串比较，并区分数组与标量 */
+const isSameQueryValue = (a: LocationQueryRaw[string], b: LocationQueryRaw[string]): boolean => {
+  const isArrayA = Array.isArray(a)
+  const isArrayB = Array.isArray(b)
+  if (isArrayA || isArrayB) {
+    if (!isArrayA || !isArrayB || a.length !== b.length) return false
+    for (let index = 0; index < a.length; index++) {
+      const itemA = a[index]
+      const itemB = b[index]
+      if (itemA !== itemB && String(itemA ?? '') !== String(itemB ?? '')) return false
+    }
+    return true
+  }
+  // 绝大多数 query 值是字符串：先做值直比，避免每次都 String() 分配。
+  return a === b || String(a ?? '') === String(b ?? '')
+}
+
+/**
+ * 忽略 __tab/__src/_back 等内部保留 key 后比较两个 query 是否等价。
+ *
+ * 直接按键逐一比较，不构造中间对象；同时要求 key 集合完全一致
+ * （旧实现只比较 key 数量，`{ a: '' }` 与 `{ b: '' }` 会被误判为相等）。
+ */
 export function isSameQueryIgnoringReserved(
   a: LocationQueryRaw = {},
   b: LocationQueryRaw = {}
 ): boolean {
-  const clean = (q: LocationQueryRaw): Record<string, string | string[]> => {
-    const result: Record<string, string | string[]> = {}
-    for (const [key, value] of Object.entries(q)) {
-      if (STACK_TABS_RESERVED_QUERY_KEYS.has(key) || key === '_back') continue
-      result[key] = Array.isArray(value)
-        ? value.map((item) => String(item ?? ''))
-        : String(value ?? '')
-    }
-    return result
+  let countA = 0
+  for (const key of Object.keys(a)) {
+    if (isIgnoredQueryKey(key)) continue
+    countA++
+    if (!Object.prototype.hasOwnProperty.call(b, key)) return false
+    if (!isSameQueryValue(a[key], b[key])) return false
   }
-  const ca = clean(a)
-  const cb = clean(b)
-  const keysA = Object.keys(ca)
-  const keysB = Object.keys(cb)
-  if (keysA.length !== keysB.length) return false
-  return keysA.every((key) => {
-    const aValue = ca[key]
-    const bValue = cb[key]
-    if (Array.isArray(aValue) || Array.isArray(bValue)) {
-      return (
-        Array.isArray(aValue) &&
-        Array.isArray(bValue) &&
-        aValue.length === bValue.length &&
-        aValue.every((value, index) => value === bValue[index])
-      )
-    }
-    return aValue === bValue
-  })
+
+  let countB = 0
+  for (const key of Object.keys(b)) {
+    if (isIgnoredQueryKey(key)) continue
+    countB++
+  }
+  return countA === countB
 }
 
 /** 移除 query 中的 vue-stack-tabs 保留参数（__tab、__src），返回干净的 query */