vue-stack-tabs 1.0.1 → 1.3.0

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,
@@ -58,56 +59,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 +150,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')
     }
   }

package/src/lib/hooks/useTabEventBus.ts

@@ -1,31 +1,41 @@
+/**
+ * 标签事件总线。
+ *
+ * 基于 mitt 实现组件间事件通信，用于 tab 激活、页面 loading、
+ * 栈内导航（forward/backward）、iframe 刷新等事件的发布/订阅。
+ */
+import type { InjectionKey } from 'vue'
+import { hasInjectionContext, inject } from 'vue'
 import type { Emitter, EventType } from 'mitt'
-import mitt from 'mitt'
-import { type App, inject } from 'vue'
+import { resolveStackTabsRuntimeContext } from './stackTabsContext'
 
 declare module '@vue/runtime-core' {
   export interface ComponentCustomProperties {
-    $layerEmitter: Emitter<Record<EventType, unknown>>
+    $layerEmitter: Emitter<TabEventPayloadMap>
   }
 }
 
-/** 全局标签事件总线，用于跨组件通信（激活、加载等） */
-const eventBus = mitt<Record<EventType, unknown>>()
-
-const plugin = {
-  install(app: App) {
-    app.provide('tabEmitter', eventBus)
-  }
-}
-
-/** 获取标签事件总线，用于组件间通信 */
-export const useTabEmitter = <T extends Record<EventType, unknown>>(): Emitter<T> => {
-  return inject('tabEmitter')!
-}
-
 /** 标签相关事件类型 */
 export enum TabEventType {
   PAGE_LOADING = 'PAGE_LOADING',
-  TAB_ACTIVE = 'TAB_ACTIVE'
+  TAB_ACTIVE = 'TAB_ACTIVE',
+  FORWARD = 'FORWARD',
+  BACKWARD = 'BACKWARD',
+  REFRESH_IFRAME_POSTMESSAGE = 'REFRESH_IFRAME_POSTMESSAGE'
+}
+
+export interface TabEventPayloadMap extends Record<EventType, unknown> {
+  [TabEventType.PAGE_LOADING]: { tId: string; value: boolean }
+  [TabEventType.TAB_ACTIVE]: { id: string; isRoute?: boolean }
+  [TabEventType.FORWARD]: void
+  [TabEventType.BACKWARD]: void
+  [TabEventType.REFRESH_IFRAME_POSTMESSAGE]: string
 }
 
-export default plugin
+export const tabEmitterKey: InjectionKey<Emitter<TabEventPayloadMap>> = Symbol('tabEmitter')
+
+/** 获取标签事件总线，用于组件间通信 */
+export const useTabEmitter = (): Emitter<TabEventPayloadMap> => {
+  const injected = hasInjectionContext() ? inject(tabEmitterKey, null) : null
+  return injected ?? resolveStackTabsRuntimeContext().eventBus
+}

package/src/lib/hooks/useTabLoading.ts

@@ -10,17 +10,18 @@ import { TabEventType, useTabEmitter } from '../hooks/useTabEventBus'
 export default () => {
   const emitter = useTabEmitter()
   const { attrs } = getCurrentInstance() as ComponentInternalInstance
+  const getTabId = () => String(attrs.tId ?? '')
   onUnmounted(() => {
     closeTabLoading()
   })
   /** 显示加载遮罩 */
   const openTabLoading = () => {
-    emitter.emit(TabEventType.PAGE_LOADING, { tId: attrs.tId, value: true })
+    emitter.emit(TabEventType.PAGE_LOADING, { tId: getTabId(), value: true })
   }
 
   /** 隐藏加载遮罩 */
   const closeTabLoading = () => {
-    emitter.emit(TabEventType.PAGE_LOADING, { tId: attrs.tId, value: false })
+    emitter.emit(TabEventType.PAGE_LOADING, { tId: getTabId(), value: false })
   }
   return { openTabLoading, closeTabLoading }
 }