vue-stack-tabs 1.1.0 → 1.3.1

package/src/lib/hooks/tabPanel/session.ts

@@ -1,33 +1,95 @@
 /**
  * tabPanel/session - Session 持久化
  *
- * 职责：将当前激活标签保存到 sessionStorage，刷新后恢复
+ * 职责：基于当前 StackTabsRuntimeContext 将当前激活标签保存到 sessionStorage，刷新后恢复。
  */
-import type { ITabItem } from '../../model/TabModel'
+import type { ITabItem, ITabPage } from '../../model/TabModel'
 import { Stack } from '../../model/TabModel'
-import type { ITabPage } from '../../model/TabModel'
-import { SESSION_TAB_NAME, sessionPrefix } from './state'
+import { isRecord } from '../../utils/typeGuards'
+import type { StackTabsRuntimeContext } from '../stackTabsContext'
+import { SESSION_TAB_NAME } from './state'
 
-/** 获取 sessionStorage 的 key */
-export const getSessionKey = () => sessionPrefix + SESSION_TAB_NAME
+const isRestoredTab = (value: unknown): value is ITabItem =>
+  isRecord(value) &&
+  typeof value.id === 'string' &&
+  typeof value.title === 'string' &&
+  typeof value.closable === 'boolean' &&
+  typeof value.refreshable === 'boolean' &&
+  typeof value.iframe === 'boolean' &&
+  typeof value.active === 'boolean' &&
+  value.pages instanceof Stack
 
-/** 将当前激活的标签保存到 sessionStorage */
-export const saveActiveTabToSession = (tab: ITabItem) => {
-  if (!tab.id) return
-  window.sessionStorage.setItem(getSessionKey(), JSON.stringify(tab))
+export interface TabPanelSessionApi {
+  getSessionKey: () => string
+  saveActiveTabToSession: (tab: ITabItem) => void
+  clearSession: () => void
+  restoreActiveTabSession: (storedJson: string | null) => void
+  restoreTabFromSession: (storedJson: string | null) => ITabItem | null
 }
 
-/** 清除 sessionStorage 中的激活标签 */
-export const clearSession = () => {
-  window.sessionStorage.removeItem(getSessionKey())
-}
+export const createTabPanelSession = (context: StackTabsRuntimeContext): TabPanelSessionApi => {
+  const getSessionKey = (): string => context.sessionPrefix.value + SESSION_TAB_NAME
+  let pendingWrite: { tab: ITabItem; version: number } | null = null
+  let writeVersion = 0
+  let writeScheduled = false
+
+  const flushPendingWrite = () => {
+    writeScheduled = false
+    const write = pendingWrite
+    pendingWrite = null
+    if (!write || write.version !== writeVersion) return
+    window.sessionStorage.setItem(getSessionKey(), JSON.stringify(write.tab))
+  }
+
+  const invalidatePendingWrite = () => {
+    writeVersion++
+    pendingWrite = null
+  }
+
+  const saveActiveTabToSession = (tab: ITabItem): void => {
+    if (!tab.id) return
+    pendingWrite = { tab, version: ++writeVersion }
+    if (writeScheduled) return
+    writeScheduled = true
+    queueMicrotask(flushPendingWrite)
+  }
+
+  const clearSession = (): void => {
+    invalidatePendingWrite()
+    window.sessionStorage.removeItem(getSessionKey())
+  }
+
+  const restoreActiveTabSession = (storedJson: string | null): void => {
+    if (storedJson === null) {
+      clearSession()
+      return
+    }
+    invalidatePendingWrite()
+    window.sessionStorage.setItem(getSessionKey(), storedJson)
+  }
+
+  const restoreTabFromSession = (storedJson: string | null): ITabItem | null => {
+    if (storedJson == null) return null
+    try {
+      const restored = JSON.parse(storedJson, (key, value) =>
+        key === 'pages' && Array.isArray(value) ? new Stack<ITabPage>(value) : value
+      )
+      if (!isRestoredTab(restored)) {
+        clearSession()
+        return null
+      }
+      return restored as ITabItem
+    } catch {
+      clearSession()
+      return null
+    }
+  }
 
-/** 从 sessionStorage 解析恢复的标签（含 Stack 反序列化） */
-export const restoreTabFromSession = (
-  storedJson: string | null
-): ITabItem | null => {
-  if (storedJson == null) return null
-  return JSON.parse(storedJson, (k, v) =>
-    k === 'pages' ? new Stack<ITabPage>(v) : v
-  ) as ITabItem
+  return {
+    getSessionKey,
+    saveActiveTabToSession,
+    clearSession,
+    restoreActiveTabSession,
+    restoreTabFromSession
+  }
 }

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

@@ -1,52 +1,49 @@
 /**
- * tabPanel/state - 标签页核心共享状态
+ * tabPanel/state - 标签页运行时状态 factory
  *
- * 职责：集中管理 tabs、caches、components、驱逐集合、滚动位置等
- * 被 useTabPanel、evict、scroll、session 导入使用
+ * 职责：创建 tabs、caches、components、驱逐集合、滚动位置等运行时状态。
+ * 注意：本文件不导出模块级可变状态；每个 Vue app 只有一个 StackTabsRuntimeContext 持有这些状态。
  */
+import type { DefineComponent, Ref, ShallowRef } from 'vue'
+import { ref, shallowRef } from 'vue'
 import type { ITabItem } from '../../model/TabModel'
-import { ref } from 'vue'
 
-/** 当前打开的标签列表（含每个标签的页面栈） */
-export const tabs = ref<ITabItem[]>([])
-/** 初始化时传入的默认标签（用于对比 session 恢复） */
-export const defaultTabs: ITabItem[] = []
-/** keep-alive include 数组，与 Vue 的 keep-alive :include 绑定 */
-export const caches = ref<string[]>([])
-/** 页面缓存 ID -> 包装后的 DefineComponent */
-export const components = new Map<string, import('vue').DefineComponent>()
-/** 待驱逐的页面缓存 ID 集合 */
-export const cacheIdsToEvict = new Set<string>()
-/** 待驱逐的标签 ID 集合 */
-export const tabIdsToEvict = new Set<string>()
-/** 刷新计数器，变更时触发 component :key 变化 */
-export const refreshKey = ref<number>(0)
-/** 刷新时临时加入 keep-alive exclude 的缓存 ID */
-// 改用 ULID 的新架构，无需黑名单隔离机制
-/** pageCacheId -> Map<selector, { top, left }> 滚动位置存储 */
-export const scrollPositionsByPageId = new Map<string, Map<string, { top: number; left: number }>>()
-/** 是否已完成初始化 */
-export const isInitialized = ref<boolean>(false)
-
-/** sessionStorage 中存储当前激活标签的 key 前缀 */
-export const SESSION_TAB_NAME = 'stacktab-active-tab'
+export interface ScrollPosition {
+  top: number
+  left: number
+}
 
-/** iframe 标签 tabId -> 刷新序号，变更时触发 iframe 重载 */
-export const iframeRefreshKeys = ref<Record<string, number>>({})
+export interface TabPanelRuntimeState {
+  tabs: Ref<ITabItem[]>
+  defaultTabs: Ref<ITabItem[]>
+  caches: ShallowRef<string[]>
+  components: Map<string, DefineComponent>
+  cacheIdsToEvict: Set<string>
+  tabIdsToEvict: Set<string>
+  refreshKey: Ref<number>
+  scrollPositionsByPageId: Map<string, Map<string, ScrollPosition>>
+  isInitialized: Ref<boolean>
+  iframeRefreshKeys: Ref<Record<string, number>>
+  maxTabCount: Ref<number>
+  useGlobalScroll: Ref<boolean>
+  sessionPrefix: Ref<string>
+}
 
-/** 最大标签数量，0 表示不限制 */
-export let maxTabCount = 0
-/** 是否使用页面级滚动 */
-export let useGlobalScroll = false
-/** sessionStorage key 前缀 */
-export let sessionPrefix = ''
+/** sessionStorage 中存储当前激活标签的 key 后缀 */
+export const SESSION_TAB_NAME = 'stacktab-active-tab'
 
-export const setMaxTabCount = (n: number) => {
-  maxTabCount = n
-}
-export const setUseGlobalScroll = (v: boolean) => {
-  useGlobalScroll = v
-}
-export const setSessionPrefix = (p: string) => {
-  sessionPrefix = p
-}
+export const createTabPanelRuntimeState = (): TabPanelRuntimeState => ({
+  tabs: ref<ITabItem[]>([]) as Ref<ITabItem[]>,
+  defaultTabs: ref<ITabItem[]>([]) as Ref<ITabItem[]>,
+  caches: shallowRef<string[]>([]),
+  components: new Map<string, DefineComponent>(),
+  cacheIdsToEvict: new Set<string>(),
+  tabIdsToEvict: new Set<string>(),
+  refreshKey: ref<number>(0),
+  scrollPositionsByPageId: new Map<string, Map<string, ScrollPosition>>(),
+  isInitialized: ref<boolean>(false),
+  iframeRefreshKeys: ref<Record<string, number>>({}),
+  maxTabCount: ref<number>(0),
+  useGlobalScroll: ref<boolean>(false),
+  sessionPrefix: ref<string>('')
+})

package/src/lib/hooks/useIframeManager.ts

@@ -0,0 +1,253 @@
+/**
+ * iframe 标签页生命周期管理。
+ *
+ * 统一管理所有 iframe 标签的 src 计算、加载状态追踪、超时检测、
+ * 刷新控制、DOM ref 收集，以及 postMessage 通信。
+ */
+import { computed, onBeforeUnmount, reactive, watch, type Ref } from 'vue'
+import type { ITabData, ITabItem } from '../model/TabModel'
+import { toSafeTabUrl } from '../utils/urlParser'
+import { getPostMessageTargetOrigin, isStackTabsOpenTabMessage } from '../utils/stackTabsMessage'
+
+type IframeLoadStatus = 'idle' | 'loading' | 'loaded' | 'timeout'
+
+interface IframeLoadState {
+  status: IframeLoadStatus
+  message?: string
+}
+
+export interface UseIframeManagerOptions {
+  tabs: Ref<ITabItem[]>
+  iframeRefreshKeys: Ref<Record<string, number>>
+  iframeLoadTimeout: number
+  t: (key: string) => string
+}
+
+export function useIframeManager(options: UseIframeManagerOptions) {
+  const { tabs, iframeRefreshKeys, iframeLoadTimeout, t } = options
+
+  const iframeTabs = computed(() => tabs.value.filter((item) => item.iframe))
+  const activeNonIframeTab = computed(() => tabs.value.find((item) => item.active && !item.iframe))
+  const hasActiveNonIframeTab = computed(() => Boolean(activeNonIframeTab.value))
+
+  // iframe 首次激活时才加载真实 URL，未激活前使用 about:blank 避免不必要的请求
+  const iframeEverActivated = reactive<Record<string, boolean>>({})
+
+  const appendIframeRefreshKey = (src: string, refreshKey: number): string => {
+    if (refreshKey <= 0 || src === 'about:blank') return src
+
+    const hashIndex = src.indexOf('#')
+    const baseWithSearch = hashIndex >= 0 ? src.slice(0, hashIndex) : src
+    const hash = hashIndex >= 0 ? src.slice(hashIndex) : ''
+    const searchIndex = baseWithSearch.indexOf('?')
+    const path = searchIndex >= 0 ? baseWithSearch.slice(0, searchIndex) : baseWithSearch
+    const search = searchIndex >= 0 ? baseWithSearch.slice(searchIndex + 1) : ''
+    const searchParams = new URLSearchParams(search)
+    searchParams.set('__stack_tabs_refresh', String(refreshKey))
+
+    return `${path}?${searchParams.toString()}${hash}`
+  }
+
+  const getIframeRefreshKey = (frameId: string): number => iframeRefreshKeys.value[frameId] ?? 0
+  const getIframeSrc = (
+    frame: { id: string; url?: string },
+    refreshKey = getIframeRefreshKey(frame.id)
+  ) => {
+    const safeUrl = toSafeTabUrl(frame.url ?? '')
+    const src = iframeEverActivated[frame.id] ? safeUrl : 'about:blank'
+    return appendIframeRefreshKey(src, refreshKey)
+  }
+
+  const getIframeKey = (frame: { id: string }) => `${frame.id}-${getIframeRefreshKey(frame.id)}`
+
+  const iframeSrcMap = computed<Record<string, string>>(() => {
+    const map: Record<string, string> = {}
+    for (const frame of iframeTabs.value) {
+      const refreshKey = getIframeRefreshKey(frame.id)
+      map[frame.id] = getIframeSrc(frame, refreshKey)
+    }
+    return map
+  })
+
+  const iframeLoadStates = reactive<Record<string, IframeLoadState>>({})
+  const getIframeLoadState = (frameId: string): IframeLoadState =>
+    iframeLoadStates[frameId] ?? { status: 'idle' }
+
+  const loadTimeoutIds = new Map<string, ReturnType<typeof setTimeout>>()
+
+  const clearIframeLoadTimeout = (frameId: string) => {
+    const timeoutId = loadTimeoutIds.get(frameId)
+    if (!timeoutId) return
+    clearTimeout(timeoutId)
+    loadTimeoutIds.delete(frameId)
+  }
+
+  const setIframeLoaded = (frameId: string) => {
+    clearIframeLoadTimeout(frameId)
+    iframeLoadStates[frameId] = { status: 'loaded' }
+  }
+
+  const setIframeLoading = (frameId: string, opts: { force?: boolean } = {}) => {
+    const current = getIframeLoadState(frameId)
+    if (current.status === 'loaded' && !opts.force) return
+
+    clearIframeLoadTimeout(frameId)
+    iframeLoadStates[frameId] = { status: 'loading' }
+    loadTimeoutIds.set(
+      frameId,
+      setTimeout(() => {
+        loadTimeoutIds.delete(frameId)
+        if (getIframeLoadState(frameId).status === 'loading') {
+          iframeLoadStates[frameId] = {
+            status: 'timeout',
+            message: t('VueStackTab.iframeLoadTimeout')
+          }
+        }
+      }, iframeLoadTimeout)
+    )
+  }
+
+  const retryIframe = (frameId: string) => {
+    iframeLoadStates[frameId] = { status: 'idle' }
+    iframeRefreshKeys.value = {
+      ...iframeRefreshKeys.value,
+      [frameId]: (iframeRefreshKeys.value[frameId] ?? 0) + 1
+    }
+    setIframeLoading(frameId, { force: true })
+  }
+
+  const shouldShowIframeLoading = (frameId: string) =>
+    getIframeLoadState(frameId).status === 'loading'
+  const shouldShowIframeError = (frameId: string) =>
+    getIframeLoadState(frameId).status === 'timeout'
+
+  const iframeElRefs = reactive<Record<string, HTMLIFrameElement | null>>({})
+  const setIframeRef = (id: string, el: HTMLIFrameElement | null) => {
+    if (el) {
+      iframeElRefs[id] = el
+    } else {
+      delete iframeElRefs[id]
+    }
+  }
+
+  /** 同步 iframe 激活和移除状态，避免用多个 watcher 重复遍历 iframe 列表。 */
+  watch(
+    () => iframeTabs.value.map((frame) => ({ id: frame.id, active: frame.active })),
+    (frames) => {
+      for (const f of frames) {
+        if (!f.active) continue
+        iframeEverActivated[f.id] = true
+        setIframeLoading(f.id)
+      }
+      const activeIds = new Set(frames.map((frame) => frame.id))
+      for (const id of Object.keys(iframeLoadStates)) {
+        if (!activeIds.has(id)) {
+          clearIframeLoadTimeout(id)
+          delete iframeLoadStates[id]
+          delete iframeEverActivated[id]
+          delete iframeElRefs[id]
+        }
+      }
+    },
+    { immediate: true }
+  )
+
+  // refreshKey 变化时重新触发对应 iframe 的加载状态
+  watch(
+    iframeRefreshKeys,
+    (keys, previousKeys = {}) => {
+      for (const frame of iframeTabs.value) {
+        if (!frame.active) continue
+        const nextKey = keys[frame.id] ?? 0
+        const previousKey = previousKeys[frame.id] ?? 0
+        if (nextKey !== previousKey) {
+          setIframeLoading(frame.id, { force: true })
+        }
+      }
+    },
+    { deep: true }
+  )
+
+  const handleIframeLoad = (frame: { id: string; url?: string }, event: Event) => {
+    const iframe = event.currentTarget as HTMLIFrameElement | null
+    const refreshKey = Number(iframe?.dataset.refreshKey ?? 0)
+    if (!iframeEverActivated[frame.id]) return
+    if (getIframeSrc(frame, refreshKey) === 'about:blank') return
+    if (refreshKey !== getIframeRefreshKey(frame.id)) return
+    if (iframe !== iframeElRefs[frame.id]) return
+    setIframeLoaded(frame.id)
+  }
+
+  const handleRefreshIframePostMessage = (tabId: string) => {
+    const iframe = iframeElRefs[tabId]
+    const tab = tabs.value.find((item) => item.id === tabId)
+    if (iframe?.contentWindow) {
+      try {
+        const targetOrigin = getPostMessageTargetOrigin(tab?.url ?? '')
+        if (!targetOrigin) {
+          if (!import.meta.env.PROD) {
+            console.warn(
+              `[vue-stack-tabs] Skip refresh postMessage because iframe URL is invalid: ${tabId}`
+            )
+          }
+          return
+        }
+        iframe.contentWindow.postMessage({ type: 'vue-stack-tabs:refresh' }, targetOrigin)
+      } catch (e) {
+        if (!import.meta.env.PROD) {
+          console.warn(`[vue-stack-tabs] Failed to send refresh postMessage to iframe: ${tabId}`, e)
+        }
+      }
+    } else {
+      if (!import.meta.env.PROD) {
+        console.warn(
+          `[vue-stack-tabs] IFrame element not found for tabId: ${tabId} when trying to refresh.`
+        )
+      }
+    }
+  }
+
+  const createMessageHandler = (
+    allowedOrigins: Ref<string[]>,
+    openTab: (tab: ITabData) => Promise<string | undefined>
+  ) => {
+    const isManagedIframeSource = (
+      source: Parameters<typeof isStackTabsOpenTabMessage>[0]['source']
+    ) => Object.values(iframeElRefs).some((el) => el?.contentWindow === source)
+
+    return (ev: MessageEvent) => {
+      if (!allowedOrigins.value.includes(ev.origin)) return
+
+      const payload = isStackTabsOpenTabMessage(ev, isManagedIframeSource)
+      if (!payload) return
+
+      openTab(payload).catch((error: unknown) => {
+        if (!import.meta.env.PROD) {
+          console.warn('[vue-stack-tabs] Failed to open tab from iframe message:', error)
+        }
+      })
+    }
+  }
+
+  onBeforeUnmount(() => {
+    for (const timeoutId of loadTimeoutIds.values()) clearTimeout(timeoutId)
+    loadTimeoutIds.clear()
+  })
+
+  return {
+    iframeTabs,
+    activeNonIframeTab,
+    hasActiveNonIframeTab,
+    iframeSrcMap,
+    getIframeRefreshKey,
+    getIframeKey,
+    getIframeLoadState,
+    shouldShowIframeLoading,
+    shouldShowIframeError,
+    retryIframe,
+    setIframeRef,
+    handleIframeLoad,
+    handleRefreshIframePostMessage,
+    createMessageHandler
+  }
+}

package/src/lib/hooks/useTabActions.ts

@@ -1,16 +1,17 @@
-import { useRouter } from 'vue-router'
-import { throttle } from 'throttle-debounce'
+import { isNavigationFailure, useRouter } from 'vue-router'
+import type { LocationQueryRaw } from 'vue-router'
 import { defu } from 'defu'
-import { ulid } from 'ulid'
-
 import useTabPanel from './useTabPanel'
 import { encodeTabInfo } from '../utils/tabInfoEncoder'
-import { parseUrl, isCrossOriginUrl } from '../utils/urlParser'
+import {
+  parseUrl,
+  isCrossOriginUrl,
+  isAllowedTabUrl,
+  omitStackTabsReservedQuery
+} from '../utils/urlParser'
 import type { ITabData, IframeRefreshMode } from '../model/TabModel'
-import { TabEventType, useTabEmitter } from './useTabEventBus'
-
-/** iframe 占位路由的 path，由 StackTabs 通过 setIFramePath 注入 */
-let iframePath: string
+import { runNavigationTransaction } from './tabPanel/navigationTransaction'
+import { resolveStackTabsRuntimeContext } from './stackTabsContext'
 
 /**
  * useTabActions - 标签操作对外 Hook
@@ -27,7 +28,7 @@ let iframePath: string
  */
 export default function useTabActions() {
   const router = useRouter()
-  const emitter = useTabEmitter()
+  const runtimeContext = resolveStackTabsRuntimeContext()
   const {
     active,
     hasTab,
@@ -37,6 +38,7 @@ export default function useTabActions() {
     renewTab,
     getTab,
     tabs,
+    moveTab,
     removeTab,
     removeAllTabs,
     refreshTab,
@@ -58,56 +60,87 @@ export default function useTabActions() {
       defaults.iframeRefreshMode = (tab.iframeRefreshMode ?? 'postMessage') as IframeRefreshMode
     }
     const info = defu(tab, defaults)
-    if (!info.id) info.id = ulid()
+    if (!info.id) info.id = crypto.randomUUID()
     return info
   }
 
-  /** 打开新标签；renew=true 时若已存在则清空该标签的页面栈后重新打开；500ms 节流 */
-  const openTab = throttle(500, (tab: ITabData, renew = false) => {
+  /** 打开新标签；renew=true 时若已存在则清空该标签的页面栈后重新打开 */
+  const openTab = (tab: ITabData, renew = false): Promise<string | undefined> => {
     return new Promise<string | undefined>((resolve, reject) => {
       const tabInfo = prepareTabInfo(tab)
 
-      if (hasTab(tabInfo.id!) && !renew) {
-        emitter.emit(TabEventType.TAB_ACTIVE, { id: tabInfo.id! })
-        resolve(tabInfo.id)
+      const isExistingTab = Boolean(tabInfo.id && hasTab(tabInfo.id))
+
+      if (isExistingTab && !renew) {
+        Promise.resolve(active(tabInfo.id!)).then(() => resolve(tabInfo.id), reject)
         return
       }
 
-      if (tabInfo.id && renew && hasTab(tabInfo.id)) {
-        renewTab(tab)
+      let rollbackRenew: (() => void) | undefined
+      let refreshKeySnapshot: number | undefined
+
+      if (tabInfo.id && renew && isExistingTab) {
         const currentTab = getTab(tab.id!)
-        if (currentTab?.active) refreshKey.value++
+        rollbackRenew = renewTab(tab)
+        if (currentTab?.active) {
+          refreshKeySnapshot = refreshKey.value
+          refreshKey.value++
+        }
       }
 
-      if (!canAddTab()) {
+      if (!isExistingTab && !canAddTab()) {
         reject(new Error('Max Size'))
         return
       }
 
-      navigateToTab(tab, tabInfo)
-      resolve(tabInfo.id)
+      navigateToTab(tab, tabInfo).then(
+        () => resolve(tabInfo.id),
+        (error) => {
+          rollbackRenew?.()
+          if (refreshKeySnapshot !== undefined) refreshKey.value = refreshKeySnapshot
+          reject(error)
+        }
+      )
     })
-  })
+  }
 
   /** 执行路由跳转到标签对应页面（普通路由或 iframe 占位路由） */
   const navigateToTab = (tab: ITabData, tabInfo: ITabData) => {
     const __tab = encodeTabInfo(tabInfo)
-    let query = defu({ __tab }, tab.query) as Record<string, string>
+    const tabQuery = omitStackTabsReservedQuery(tab.query)
+    let query = defu(tabQuery, { __tab }) as LocationQueryRaw
     let path: string
+
     if (!tab.iframe) {
       const url = parseUrl(tab.path)
       path = url.path
-      query = defu(url.query, query)
+      query = defu(omitStackTabsReservedQuery(url.query), query, { __tab }) as LocationQueryRaw
+      query = {
+        ...query,
+        __tab
+      }
     } else {
-      query['__src'] = encodeURIComponent(tab.path as string)
-      path = iframePath
+      query = {
+        ...query,
+        __src: encodeURIComponent(tab.path as string),
+        __tab
+      }
+      path = runtimeContext.iframePath.value
     }
-    router.push({ path, query })
+
+    if (!isAllowedTabUrl(tab.path)) return Promise.reject(new Error('Invalid tab URL'))
+    return runNavigationTransaction({
+      apply: () => undefined,
+      navigate: () => router.push({ path, query }),
+      rollback: () => undefined,
+      isFailureResult: isNavigationFailure,
+      rejectFailureResult: true
+    })
   }
 
   /** 设置 iframe 占位路由的 path，由 StackTabs 在挂载时调用 */
   const setIFramePath = (path: string) => {
-    iframePath = path
+    runtimeContext.iframePath.value = path
   }
 
   /** 获取当前页面的缓存容器 DOM（用于某些需要直接操作 DOM 的场景） */
@@ -118,7 +151,7 @@ export default function useTabActions() {
   /** iframe 标签在新窗口打开（无法嵌入时降级） */
   const openInNewWindow = (id: string) => {
     const tab = getTab(id)
-    if (tab?.iframe && tab.url) {
+    if (tab?.iframe && tab.url && isAllowedTabUrl(tab.url)) {
       window.open(tab.url, '_blank', 'noopener,noreferrer')
     }
   }
@@ -137,6 +170,7 @@ export default function useTabActions() {
 
     // 激活与重置
     activeTab: active,
+    moveTab,
     reset,
 
     // 数据与配置