vue-stack-tabs 1.0.1 → 1.3.0

package/src/lib/model/TabModel.ts

@@ -1,3 +1,5 @@
+import type { LocationQueryRaw } from 'vue-router'
+
 /**
  * TabModel - 标签页数据模型
  *
@@ -15,17 +17,6 @@ export enum TabScrollMode {
   BOTH = 'both'
 }
 
-// export enum EventType {
-//   I18N_LOCALES = 'I18N_LOCALES',
-//   PANEL_MAXIMUM = 'PANEL_MAXIMUM',
-//   TAB_ACTIVE = 'TAB_ACTIVE',
-//   TAB_CLOSE = 'TAB_CLOSE',
-//   TAB_CLOSE_ALL = 'TAB_CLOSE_ALL',
-//   TAB_CLOSE_RIGHT = 'TAB_CLOSE_RIGHT',
-//   TAB_CLOSE_LEFT = 'TAB_CLOSE_LEFT',
-//   TAB_REFRESH = 'TAB_REFRESH',
-//   TAB_REFRESH_ALL = 'TAB_REFRESH_ALL'
-// }
 /** 标签栏滚动条拖拽时的临时状态 */
 export interface DragData {
   thumbLeft: number
@@ -48,7 +39,7 @@ export interface ITabData extends ITabBase {
   // tab name
   title: string
   path: string
-  query?: Record<string, string>
+  query?: LocationQueryRaw
 }
 /** iframe 刷新方式：postMessage 由 iframe 内页自行刷新（不重建 DOM，动画正常）；reload 强制重载 iframe */
 export type IframeRefreshMode = 'postMessage' | 'reload'
@@ -80,112 +71,69 @@ export interface ITabPage {
   id: string
   tabId: string
   path: string
-  query?: Record<string, string>
+  query?: LocationQueryRaw
+  /** 页面级刷新版本；仅影响当前页面的 keep-alive 缓存 key */
+  refreshVersion?: number
+  /** 该页面从别的页面被后退唤醒时附带的临时闭包参数，不污染 URL */
+  _backParams?: Record<string, unknown>
 }
-/** 右键菜单项：图标、标题、回调、禁用条件 */
+/** 右键菜单项：重复或动态菜单应提供稳定 key，避免 fallback 标题/图标重复 */
 export interface IContextMenu {
+  key?: string
   icon?: string
   title: string
   callback(id: string): void
   disabled: (tabData: ITabBase) => boolean
 }
-// export interface TabRouteLocationRaw {
-//   path: string
-//   query?: any
-// }
-// export interface PageRouteLocationRaw {
-//   pId: string
-//   path: string
-//   query: any
-// }
-/** 使用 Map 实现的栈结构，用于标签内的 pages 页面栈 */
+/** 数组实现的栈结构，用于标签内的 pages 页面栈 */
 export class Stack<T> {
-  private items: Map<number, T>
+  protected items: T[]
 
   constructor(items?: T[]) {
-    this.items = new Map()
-    if (items) {
-      for (const item of items) {
-        this.push(item)
-      }
-    }
+    this.items = items ? [...items] : []
   }
 
-  /**
-   * @description: 入栈
-   * @param {T} element 要入栈的元素
-   */
   push(element: T) {
-    this.items.set(this.items.size, element)
+    this.items.push(element)
   }
 
-  /**
-   * @description: 出栈
-   * @return {T} 返回出栈的元素
-   */
   pop(): T | undefined {
-    if (this.isEmpty()) {
-      return undefined
-    }
-    const result = this.items.get(this.items.size - 1)
-    this.items.delete(this.items.size - 1)
-    return result
+    return this.items.pop()
   }
 
-  /**
-   * @description: 返回栈顶的元素
-   * @return {T}
-   */
   peek(): T | undefined {
-    if (this.isEmpty()) {
-      return undefined
-    }
-    return this.items.get(this.items.size - 1)
+    return this.items.length > 0 ? this.items[this.items.length - 1] : undefined
+  }
+
+  at(index: number): T | undefined {
+    return this.items[index]
   }
 
-  /**
-   * @description: 返回栈是否为空
-   * @return {Boolean}
-   */
   isEmpty(): boolean {
-    return this.items.size === 0
+    return this.items.length === 0
   }
 
-  /**
-   * @description: 返回栈里的元素个数
-   * @return {Number}
-   */
   size(): number {
-    return this.items.size
+    return this.items.length
   }
 
-  /**
-   * @description: 清空栈
-   */
   clear() {
-    this.items.clear()
+    this.items.length = 0
   }
 
-  list() {
-    return Array.from(this.items.values())
+  list(): T[] {
+    return [...this.items]
   }
 
-  /**
-   * @description: 覆盖Object默认的toString
-   * @return {String}
-   */
-  toString(): string {
-    if (this.isEmpty()) {
-      return ''
-    }
-    let result: string = ''
-    this.items.forEach((value, key) => {
-      result = `${result}${key === 0 ? '' : ', '}${value}`
-    })
-    return result
+  readonlyList(): readonly T[] {
+    return this.items
   }
-  toJSON() {
-    // return Object.fromEntries(this.items)
-    return Array.from(this.items.values())
+
+  toJSON(): T[] {
+    return this.list()
+  }
+
+  toString(): string {
+    return this.items.toString()
   }
 }

package/src/lib/nuxt/module.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Nuxt 模块类型声明。
+ * 扩展 PublicRuntimeConfig 以支持 vueStackTabs 配置的类型推导。
+ */
 import type { ModuleOptions } from './module'
 
 declare module 'nuxt/schema' {

package/src/lib/nuxt/module.ts

@@ -1,4 +1,10 @@
-import { addPlugin, addImports, createResolver, defineNuxtModule } from '@nuxt/kit'
+/**
+ * vue-stack-tabs Nuxt 模块。
+ *
+ * 自动注册客户端插件、注入 composables（useTabActions 等），
+ * 并通过 runtimeConfig 传递 locale 配置。
+ */
+import { addPlugin, addImports, createResolver, defineNuxtModule } from 'nuxt/kit'
 
 export interface ModuleOptions {
   /** 默认语言 */
@@ -21,8 +27,7 @@ export default defineNuxtModule<ModuleOptions>({
     }
 
     addPlugin({
-      src: resolve('./runtime/plugin.client'),
-      mode: 'client'
+      src: resolve('./runtime/plugin')
     })
 
     addImports([

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

@@ -1,3 +1,4 @@
+import { defineNuxtPlugin, useRuntimeConfig } from 'nuxt/app'
 import VueStackTabs from 'vue-stack-tabs'
 
 export default defineNuxtPlugin((nuxtApp) => {
@@ -5,7 +6,5 @@ export default defineNuxtPlugin((nuxtApp) => {
     locale?: string
   }
 
-  nuxtApp.vueApp.use(VueStackTabs, {
-    locale: config?.locale ?? 'zh-CN'
-  })
+  nuxtApp.vueApp.use(VueStackTabs, [{ locale: config?.locale ?? 'zh-CN' }])
 })

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

@@ -0,0 +1,11 @@
+/** Nuxt 客户端插件：自动注册 VueStackTabs 并应用 runtimeConfig 中的 locale 配置 */
+import { defineNuxtPlugin, useRuntimeConfig } from 'nuxt/app'
+import VueStackTabs from 'vue-stack-tabs'
+
+export default defineNuxtPlugin((nuxtApp) => {
+  const config = useRuntimeConfig().public.vueStackTabs as {
+    locale?: string
+  }
+
+  nuxtApp.vueApp.use(VueStackTabs, [{ locale: config?.locale ?? 'zh-CN' }])
+})

package/src/lib/utils/iframeBridge.ts

@@ -1,3 +1,5 @@
+import type { LocationQueryRaw } from 'vue-router'
+
 /**
  * iframe 与父窗口的 postMessage 桥接
  *
@@ -12,25 +14,41 @@ export const MSG_REFRESH = 'vue-stack-tabs:refresh'
 /** 打开标签消息：iframe -> 父，payload 为 ITabData */
 export const MSG_OPEN_TAB = 'vue-stack-tabs:openTab'
 
+export interface IframeBridgeOptions {
+  targetOrigin?: string
+}
+
+function getDefaultTargetOrigin(): string {
+  return window.location.origin
+}
+
+export interface RefreshRequestOptions {
+  allowedOrigins?: string[]
+}
+
 export interface IframeOpenTabPayload {
   id?: string
   title: string
   path: string
-  query?: Record<string, string>
+  query?: LocationQueryRaw
   closable?: boolean
   refreshable?: boolean
   iframe?: boolean
+  iframeRefreshMode?: 'postMessage' | 'reload'
 }
 
 /**
  * 在 iframe 内调用：向父窗口请求打开新标签
  * @param payload 标签数据，至少需 title、path
  */
-export function postOpenTab(payload: IframeOpenTabPayload) {
+export function postOpenTab(
+  payload: IframeOpenTabPayload,
+  options: IframeBridgeOptions = {}
+): void {
   if (typeof window === 'undefined' || !window.parent) return
   window.parent.postMessage(
     { type: MSG_OPEN_TAB, payload },
-    '*' // 父窗口可校验 origin，此处用 * 便于跨子域
+    options.targetOrigin ?? getDefaultTargetOrigin()
   )
 }
 
@@ -39,10 +57,16 @@ export function postOpenTab(payload: IframeOpenTabPayload) {
  * @param callback 默认 location.reload()，可自定义
  * @returns 取消监听的函数
  */
-export function onRefreshRequest(callback: () => void = () => window.location.reload()) {
-  if (typeof window === 'undefined') return () => {}
+export function onRefreshRequest(
+  callback: () => void = () => window.location.reload(),
+  options: RefreshRequestOptions = {}
+): () => void {
+  if (typeof window === 'undefined') return () => undefined
 
+  const allowedOrigins = options.allowedOrigins ?? []
   const handler = (ev: MessageEvent) => {
+    if (ev.source !== window.parent) return
+    if (allowedOrigins.length > 0 && !allowedOrigins.includes(ev.origin)) return
     if (ev.data?.type === MSG_REFRESH) {
       callback()
     }

package/src/lib/utils/scrollUtils.ts

@@ -89,10 +89,15 @@ export const getScrollbarWidth = (function () {
   }
 })()
 
+const Z_INDEX_CEILING = 89999
+
 /** 获取指定选择器下元素的最大 z-index + 1，用于最大化时置顶 */
 export const getMaxZIndex = (key = '.stack-tab__container *'): number => {
-  const allZIndex = Array.from(document.querySelectorAll(key)).map(
-    (e) => +window.getComputedStyle(e).zIndex || 0
-  )
-  return allZIndex.length ? Math.max(...allZIndex.filter((item) => item < 90000)) + 1 : 1
+  const elements = document.querySelectorAll(key)
+  let max = 0
+  for (let i = 0; i < elements.length; i++) {
+    const z = +window.getComputedStyle(elements[i]!).zIndex || 0
+    if (z < Z_INDEX_CEILING && z > max) max = z
+  }
+  return max + 1
 }

package/src/lib/utils/stackTabsA11y.ts

@@ -0,0 +1,12 @@
+/**
+ * WAI-ARIA 无障碍 ID 生成工具。
+ * 为 tab/panel 元素生成符合 ARIA tablist 模式的关联 ID。
+ */
+
+/** 生成 tab 触发器的 DOM id，用于 aria-controls 关联 */
+export const getStackTabTabId = (tabId: string): string =>
+  `stack-tab-tab-${encodeURIComponent(tabId)}`
+
+/** 生成 tab 面板的 DOM id，用于 aria-labelledby 关联 */
+export const getStackTabPanelId = (tabId: string): string =>
+  `stack-tab-panel-${encodeURIComponent(tabId)}`

package/src/lib/utils/stackTabsMessage.ts

@@ -0,0 +1,99 @@
+import type { LocationQueryRaw, LocationQueryValueRaw } from 'vue-router'
+import type { ITabData, IframeRefreshMode } from '../model/TabModel'
+import { isAllowedTabUrl } from './urlParser'
+
+type ManagedSourceChecker = (source: MessageEventSource | null) => boolean
+
+interface StackTabsMessageEnvelope {
+  type?: unknown
+  payload?: unknown
+}
+
+const OPEN_TAB_MESSAGE_TYPES = new Set(['vue-stack-tabs:openTab', 'openTab'])
+
+import { isRecord } from './typeGuards'
+
+const isLocationQueryValueRaw = (value: unknown): value is LocationQueryValueRaw =>
+  typeof value === 'string' || typeof value === 'number' || value === null || value === undefined
+
+const pickLocationQueryRaw = (value: unknown): LocationQueryRaw | undefined => {
+  if (!isRecord(value)) return undefined
+
+  const query: LocationQueryRaw = {}
+  for (const [key, item] of Object.entries(value)) {
+    if (isLocationQueryValueRaw(item)) {
+      query[key] = item
+      continue
+    }
+    if (Array.isArray(item) && item.every(isLocationQueryValueRaw)) {
+      query[key] = item
+    }
+  }
+
+  return Object.keys(query).length > 0 ? query : undefined
+}
+
+const pickBoolean = (value: unknown): boolean | undefined =>
+  typeof value === 'boolean' ? value : undefined
+
+const pickRefreshMode = (value: unknown): IframeRefreshMode | undefined => {
+  if (value === 'reload' || value === 'postMessage') return value
+  return undefined
+}
+
+const normalizeOpenTabPayload = (payload: unknown): ITabData | null => {
+  if (!isRecord(payload)) return null
+
+  const { id, title, path, query, iframe, closable, refreshable, iframeRefreshMode } = payload
+  if (typeof title !== 'string' || title.trim() === '') return null
+  if (typeof path !== 'string' || path.trim() === '' || !isAllowedTabUrl(path)) return null
+
+  const normalizedQuery = pickLocationQueryRaw(query)
+  const normalizedIframe = pickBoolean(iframe)
+  const normalizedClosable = pickBoolean(closable)
+  const normalizedRefreshable = pickBoolean(refreshable)
+  const normalizedRefreshMode = pickRefreshMode(iframeRefreshMode)
+
+  return {
+    ...(typeof id === 'string' && id ? { id } : {}),
+    title,
+    path,
+    ...(normalizedQuery ? { query: normalizedQuery } : {}),
+    ...(normalizedIframe !== undefined ? { iframe: normalizedIframe } : {}),
+    ...(normalizedClosable !== undefined ? { closable: normalizedClosable } : {}),
+    ...(normalizedRefreshable !== undefined ? { refreshable: normalizedRefreshable } : {}),
+    ...(normalizedRefreshMode ? { iframeRefreshMode: normalizedRefreshMode } : {})
+  }
+}
+
+/** 校验 MessageEvent 是否为合法的 openTab 请求，返回解析后的 ITabData 或 null */
+export const isStackTabsOpenTabMessage = (
+  event: MessageEvent,
+  isManagedSource: ManagedSourceChecker
+): ITabData | null => {
+  if (!isManagedSource(event.source)) return null
+  if (!isRecord(event.data)) return null
+
+  const envelope = event.data as StackTabsMessageEnvelope
+  if (typeof envelope.type !== 'string' || !OPEN_TAB_MESSAGE_TYPES.has(envelope.type)) return null
+
+  return normalizeOpenTabPayload(envelope.payload)
+}
+
+/** 根据 iframe URL 计算安全的 postMessage targetOrigin，非法 URL 返回 null */
+export const getPostMessageTargetOrigin = (url: string, fallbackOrigin?: string): string | null => {
+  if (!url || !isAllowedTabUrl(url)) return null
+
+  try {
+    const base =
+      fallbackOrigin ?? (typeof window !== 'undefined' ? window.location.origin : undefined)
+    if (!base && !/^https?:\/\//i.test(url)) return null
+
+    const parsed = new URL(url, base)
+    if (parsed.protocol === 'http:' || parsed.protocol === 'https:') return parsed.origin
+  } catch {
+    return null
+  }
+
+  return null
+}

package/src/lib/utils/tabInfoEncoder.ts

@@ -1,28 +1,55 @@
 import type { ITabBase } from '../model/TabModel'
-import { compressToEncodedURIComponent, decompressFromEncodedURIComponent } from 'lz-string'
-import Hex from 'hex-encoding'
-import { blake3 } from '@noble/hashes/blake3.js'
+
+interface EncodedTabInfoV1 {
+  version: 1
+  id?: string
+  title: string
+  iframe?: boolean
+  closable?: boolean
+  refreshable?: boolean
+  iframeRefreshMode?: 'postMessage' | 'reload'
+}
 
 /**
  * 标签信息编解码器
  *
- * 职责：将标签元数据压缩为 URL query 可用的短字符串，用于 __tab 参数
- * 格式: id|title|iframe|closable|refreshable，压缩后写入 query.__tab
+ * 职责：将标签元数据编码为 URL query 可用的短字符串，用于 __tab 参数。
+ * 当前格式为 JSON + Base64，兼容旧版 id|title|iframe|closable|refreshable|mode 编码。
  */
 
-/**
- * 编码标签基础信息为压缩字符串（用于 query.__tab）
- * @param tabData 标签基础数据
- */
-export const encodeTabInfo = (tabData: ITabBase): string => {
-  const mode = (tabData as { iframeRefreshMode?: string }).iframeRefreshMode === 'reload' ? 'R' : 'P'
-  const info = `${tabData.id}|${tabData.title}|${tabData.iframe ? 'Y' : 'N'}|${tabData.closable ? 'Y' : 'N'}|${tabData.refreshable ? 'Y' : 'N'}|${mode}`
-  return compressToEncodedURIComponent(info)
+const MAX_DECODED_TAB_INFO_LENGTH = 2048
+const MAX_ENCODED_TAB_INFO_LENGTH = 4096
+
+const encodeBase64 = (value: string): string => encodeURIComponent(btoa(encodeURIComponent(value)))
+const decodeBase64 = (encoded: string): string =>
+  decodeURIComponent(atob(decodeURIComponent(encoded)))
+
+const DEFAULT_TAB_INFO: ITabBase = {
+  id: '',
+  title: '',
+  iframe: false,
+  closable: true,
+  refreshable: true,
+  iframeRefreshMode: 'postMessage'
 }
 
-/** 从 query.__tab 解压并解析为 ITabBase */
-export const decodeTabInfo = (encoded: string): ITabBase => {
-  const tabString = decompressFromEncodedURIComponent(encoded)
+import { isRecord } from './typeGuards'
+
+const toTabInfo = (payload: unknown): ITabBase => {
+  if (!isRecord(payload)) return { ...DEFAULT_TAB_INFO }
+
+  return {
+    id: typeof payload.id === 'string' ? payload.id : DEFAULT_TAB_INFO.id,
+    title: typeof payload.title === 'string' ? payload.title : DEFAULT_TAB_INFO.title,
+    iframe: typeof payload.iframe === 'boolean' ? payload.iframe : DEFAULT_TAB_INFO.iframe,
+    closable: typeof payload.closable === 'boolean' ? payload.closable : DEFAULT_TAB_INFO.closable,
+    refreshable:
+      typeof payload.refreshable === 'boolean' ? payload.refreshable : DEFAULT_TAB_INFO.refreshable,
+    iframeRefreshMode: payload.iframeRefreshMode === 'reload' ? 'reload' : 'postMessage'
+  }
+}
+
+const decodeLegacyTabInfo = (tabString: string): ITabBase => {
   const tabValues: string[] = tabString.split('|')
   const refreshMode = tabValues[5] === 'R' ? ('reload' as const) : ('postMessage' as const)
   return {
@@ -35,31 +62,31 @@ export const decodeTabInfo = (encoded: string): ITabBase => {
   }
 }
 
-/**
- * 根据 tabId + path + query 生成页面缓存 ID
- * 用于 keep-alive 的 include 和 exclude，需稳定且唯一
- */
-export const createPageId = (tabId: string, path: string, query: object): string => {
-  const queryEntries: { key: string; value: string }[] = []
-  type ObjectKey = keyof typeof query
-  for (const key in query) {
-    if (!key.startsWith('__')) {
-      queryEntries.push({
-        key,
-        value: query[key as ObjectKey]
-      })
-    }
+export const encodeTabInfo = (tabData: ITabBase): string => {
+  const payload: EncodedTabInfoV1 = {
+    version: 1,
+    id: tabData.id,
+    title: tabData.title,
+    iframe: tabData.iframe,
+    closable: tabData.closable,
+    refreshable: tabData.refreshable,
+    iframeRefreshMode: tabData.iframeRefreshMode === 'reload' ? 'reload' : 'postMessage'
+  }
+  return encodeBase64(JSON.stringify(payload))
+}
+
+export const decodeTabInfo = (encoded: string): ITabBase => {
+  if (encoded.length > MAX_ENCODED_TAB_INFO_LENGTH) return { ...DEFAULT_TAB_INFO }
+
+  try {
+    const tabString = decodeBase64(encoded)
+    if (tabString.length > MAX_DECODED_TAB_INFO_LENGTH) return { ...DEFAULT_TAB_INFO }
+    if (!tabString.trim().startsWith('{')) return decodeLegacyTabInfo(tabString)
+
+    return toTabInfo(JSON.parse(tabString))
+  } catch {
+    return { ...DEFAULT_TAB_INFO }
   }
-  queryEntries.sort((a, b) => {
-    let result = 0
-    if (a.key > b.key) {
-      result = 1
-    } else if (a.key < b.key) {
-      result = -1
-    }
-    return result
-  })
-  const msg = new TextEncoder().encode(`${tabId}|${path}|${JSON.stringify(queryEntries)}`)
-  const hash = blake3(msg)
-  return Hex.encode(hash)
 }
+
+export const createPageId = (): string => crypto.randomUUID()

package/src/lib/utils/typeGuards.ts

@@ -0,0 +1,3 @@
+/** 类型守卫：判断值是否为非数组的普通对象 */
+export const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value)