vue-stack-tabs 0.1.51 → 1.0.1

package/src/lib/hooks/useTabRouter.ts

@@ -1,103 +1,114 @@
-import { defu } from 'defu'
-
-import { getCurrentInstance } from 'vue'
-import type { ComponentInternalInstance } from 'vue'
-import { type RouteLocationPathRaw, useRoute, useRouter } from 'vue-router'
-
-import useTabpanel from '@/lib/hooks/useTabpanel'
-import { uriDecode } from '@/lib/utils/UriHelper'
-import { useEmitter } from '@/lib/hooks/useTabMitt'
-export default () => {
-  const { attrs, props } = getCurrentInstance() as ComponentInternalInstance
-  const { pageShown, getTab, markDeletableCache, removeComponent, getComponent, addPageScroller } =
-    useTabpanel()
-  const route = useRoute()
-  const router = useRouter()
-  const emitter = useEmitter()
-  let currentId = ''
-  // const currentPageId = ''
-  let currentTab = ''
-  currentId = (attrs.tId || props.tId) as string
-  const currentPageId = (attrs.pId || props.pId) as string
-  // currentPageId = attrs.pId as string
-  currentTab = route.query.__tab as string
-
-  const addScroller = (...scroller: string[]) => {
-    addPageScroller(currentPageId, ...scroller)
-  }
-  const forward = (to: RouteLocationPathRaw) => {
-    // pageShown.value = false
-    const query = defu(
-      {
-        __tab: currentTab
-      },
-      to.query
-    )
-    emitter.emit('FORWARD')
-    router.push({
-      path: to.path,
-      query
-    })
-  }
-  /**
-   * 返回
-   * @param to url or step
-   * @param query 返回时要加截的数据
-   */
-  const backward = (to: number | string, query?: Object) => {
-    // pageShown.value = false
-
-    const tab = getTab(currentId)
-    if (!tab) {
-      return
-    }
-    const tabStack = tab.pages
-    let absTo = 0
-    if (typeof to === 'number') {
-      absTo = Math.abs(to)
-    } else {
-      let index = 1
-      let hasPath = false
-      const pageItems = tabStack.list()
-      const url = uriDecode(to)
-      query = defu(url.query, query)
-      for (let i = tabStack.size() - 2; i >= 0; i--) {
-        if (pageItems[i].path === url.path) {
-          hasPath = true
-          break
-        }
-        index += 1
-      }
-      if (hasPath) {
-        absTo = index
-      }
-    }
-
-    if (absTo === 0 || tabStack!.size() <= absTo) {
-      return
-    }
-    // const removeCaches = new Set()
-    for (let i = 0; i < absTo; i++) {
-      const popRoute = tabStack.pop()
-      // removeComponent(popRoute!.id)
-      markDeletableCache(popRoute!.id)
-    }
-    const pageRoute = tabStack?.peek()
-    const component = getComponent(pageRoute!.id)
-    if (component !== null && component !== undefined) {
-      const sourceComponent = component.components.DynamicComponent
-      sourceComponent.props = defu(query, sourceComponent.props)
-    }
-    emitter.emit('BACKWARD')
-    router.push({
-      path: pageRoute!.path,
-      query: pageRoute!.query
-    })
-  }
-
-  return {
-    forward,
-    backward,
-    addScroller
-  }
-}
+import { defu } from 'defu'
+import { getCurrentInstance } from 'vue'
+import type { ComponentInternalInstance } from 'vue'
+import type { RouteLocationPathRaw } from 'vue-router'
+import { useRoute, useRouter } from 'vue-router'
+
+import useTabPanel from './useTabPanel'
+import { parseUrl } from '../utils/urlParser'
+import { useTabEmitter } from './useTabEventBus'
+
+/** StackTabs 监听此事件切换前进动画 */
+const ROUTER_EVENT_FORWARD = 'FORWARD'
+/** StackTabs 监听此事件切换后退动画 */
+const ROUTER_EVENT_BACKWARD = 'BACKWARD'
+
+/**
+ * useTabRouter - 标签内路由 Hook
+ *
+ * 职责：在单个标签内实现「前进/后退」栈式导航，以及滚动位置的记录与恢复
+ * 使用范围：仅在标签内的页面组件中使用，依赖 router-view 传入的 tId、pId
+ *
+ * 主要 API：
+ * - forward(to) 前进：push 新页面到该标签的 pages 栈
+ * - backward(to, backQuery?) 后退：pop 栈顶、markCacheForEviction，跳转到新栈顶
+ * - addScrollTarget(...selectors) 注册需要记录滚动位置的选择器
+ */
+export default function useTabRouter() {
+  const instance = getCurrentInstance() as ComponentInternalInstance
+  const { attrs, props } = instance
+  /** 当前标签 id，由 cache 组件的 dynamic-component 传入 */
+  const tabId = (attrs.tId ?? props.tId) as string
+  /** 当前页面缓存 id */
+  const pageId = (attrs.pId ?? props.pId) as string
+
+  const route = useRoute()
+  const router = useRouter()
+  const emitter = useTabEmitter()
+  const { getTab, markCacheForEviction, getComponent, addPageScroller } = useTabPanel()
+
+  /** 当前标签的编码信息，用于 push 时保持 __tab */
+  const tabInfo = route.query.__tab as string
+
+  /** 注册需记录滚动位置的容器选择器 */
+  const addScrollTarget = (...selectors: string[]) => {
+    addPageScroller(pageId, ...selectors)
+  }
+
+  /** 前进：进栈，跳转到新页面 */
+  const forward = (to: RouteLocationPathRaw) => {
+    const query = defu({ __tab: tabInfo }, to.query)
+    emitter.emit(ROUTER_EVENT_FORWARD)
+    router.push({ path: to.path, query })
+  }
+
+  /**
+   * 后退：从该标签的 pages 栈中 pop，并跳转到新栈顶
+   * @param to 数字=退几步，字符串=回退到首个路径匹配的页面
+   * @param backQuery 回退后传给目标页面的 props 数据（目标页通过 props 接收）
+   */
+  const backward = (to: number | string, backQuery?: object) => {
+    const tab = getTab(tabId)
+    if (!tab) return
+
+    const stack = tab.pages
+    let steps = 0
+
+    if (typeof to === 'number') {
+      steps = Math.abs(to)
+    } else {
+      const parsed = parseUrl(to)
+      backQuery = defu(parsed.query, backQuery)
+      const pages = stack.list()
+      let found = false
+      for (let i = stack.size() - 2; i >= 0; i--) {
+        steps++
+        if (pages[i]?.path === parsed.path) {
+          found = true
+          break
+        }
+      }
+      if (!found) return
+    }
+
+    if (steps <= 0 || stack.size() <= steps) return
+
+    for (let i = 0; i < steps; i++) {
+      const popped = stack.pop()
+      if (popped) markCacheForEviction(popped.id)
+    }
+
+    const target = stack.peek()
+    if (!target) return
+
+    const component = getComponent(target.id)
+    if (component && backQuery) {
+      const comp = component as {
+        components?: { DynamicComponent?: { props?: object } }
+      }
+      const dynamic = comp.components?.DynamicComponent
+      if (dynamic?.props) {
+        dynamic.props = defu(backQuery, dynamic.props)
+      }
+    }
+
+    emitter.emit(ROUTER_EVENT_BACKWARD)
+    router.push({ path: target.path, query: target.query })
+  }
+
+  return {
+    forward,
+    backward,
+    addScrollTarget
+  }
+}

package/src/lib/i18n/index.ts

@@ -9,20 +9,16 @@ export default () => {
    * 获取所有语言文件
    * @param {Object} mList
    */
-  function getLangFiles(mList: any, msg: any) {
+  function getLangFiles(
+    mList: Record<string, { default?: Record<string, unknown> }>,
+    msg: Record<string, Record<string, unknown>>
+  ) {
     for (const path in mList) {
-      if (mList[path].default) {
-        //  获取文件名
+      const mod = mList[path] as { default?: Record<string, unknown> }
+      if (mod?.default) {
         const pathName = path.substring(path.lastIndexOf('/') + 1, path.lastIndexOf('.'))
-
-        if (msg[pathName]) {
-          msg[pathName] = {
-            ...mList[pathName],
-            ...mList[path].default
-          }
-        } else {
-          msg[pathName] = mList[path].default
-        }
+        const existing = msg[pathName] as Record<string, unknown> | undefined
+        msg[pathName] = existing ? { ...existing, ...mod.default } : mod.default
       }
     }
   }
@@ -52,16 +48,16 @@ export default () => {
   // 那么你就可以 使用 :lower:（小写） :upper:（大写） 来引入文件
   // const viewModules = import.meta.globEager('../views/**/locales/[[:lower:]][[:lower:]]-[[:upper:]][[:upper:]].ts')
 
-  const allLangs: any = () => {
-    const message: any = {}
-    getLangFiles(modules, message)
+  const allLangs = (): Record<string, Record<string, unknown>> => {
+    const message: Record<string, Record<string, unknown>> = {}
+    getLangFiles(modules as Record<string, { default?: Record<string, unknown> }>, message)
     return message
   }
   // const localeI18n = inject('locales') as { locale: string; messages: object }
-  const getI18n = (localeI18n?: { locale: string; messages: any }[]) => {
+  const getI18n = (localeI18n?: { locale: string; messages: Record<string, unknown> }[]) => {
     const combinateMessage = { ...allLangs() }
     if (localeI18n) {
-      for (const l of localeI18n!) {
+      for (const l of localeI18n) {
         combinateMessage[l.locale] = l.messages
       }
       // combinateMessage = { ...allLangs(), ...localeI18n.messages }
@@ -70,7 +66,7 @@ export default () => {
     return createI18n({
       locale: 'zh-CN',
       fallbackLocale: 'en',
-      messages: combinateMessage
+      messages: combinateMessage as Record<string, Record<string, string>>
     })
     // const combinateMessage = { ...allLangs(), ...localeI18n.messages }
     // return useI18n({

package/src/lib/i18n/lang/en.ts

@@ -10,6 +10,7 @@ export default {
     maximum: 'maximum',
     restore: 'restore',
     undefined: 'undefined',
-    loading: 'loading'
+    loading: 'loading',
+    openInNewWindow: 'Open in new window'
   }
 }

package/src/lib/i18n/lang/zh-CN.ts

@@ -10,6 +10,7 @@ export default {
     maximum: '最大化',
     restore: '还原',
     undefined: '未命名',
-    loading: '加载中'
+    loading: '加载中',
+    openInNewWindow: '在新窗口打开'
   }
 }

package/src/lib/iframe.vue

@@ -1,3 +1,9 @@
+<!--
+  IFrame - iframe 占位组件
+
+  职责：路由 /iframe 的占位页，仅挂载 useTabRouter 以注入标签内路由能力
+  说明：实际 iframe 内容由 StackTabs 在 iframeTabs 中渲染
+-->
 <script setup lang="ts">
 import useTabRouter from './hooks/useTabRouter'
 useTabRouter()

package/src/lib/index.ts

@@ -1,14 +1,19 @@
+/**
+ * vue-stack-tabs - 入口与导出
+ *
+ * 导出：StackTab（组件）、useTabActions、useTabRouter、useTabLoading、IFrame、TabHeaderButton
+ * 安装：Vue.use(plugin) 注册全局组件 VueStackTabs、事件总线、i18n
+ */
 import type { App } from 'vue'
-// import { createI18n } from 'vue-i18n'
 import i18n from './i18n'
 import StackTab from './StackTabs.vue'
-import tabVersion from './banner'
+import logVersion from './versionLogger'
 import IFrame from './iframe.vue'
 import useTabLoading from './hooks/useTabLoading'
 import useTabRouter from './hooks/useTabRouter'
-import useStackTab from './hooks/useStackTab'
+import useTabActions from './hooks/useTabActions'
 import TabHeaderButton from '@/lib/components/TabHeader/TabHeaderButton.vue'
-import useTabMitt from '@/lib/hooks/useTabMitt'
+import useTabEventBus from '@/lib/hooks/useTabEventBus'
 import './assets/style/index.scss'
 //
 // const i18n = createI18n({
@@ -25,10 +30,24 @@ declare module '@vue/runtime-core' {
   }
 }
 
-export { IFrame, useTabLoading, useTabRouter, useStackTab, TabHeaderButton, StackTab }
+export {
+  IFrame,
+  useTabActions,
+  useTabLoading,
+  useTabRouter,
+  TabHeaderButton,
+  StackTab
+}
+export {
+  postOpenTab,
+  onRefreshRequest,
+  MSG_REFRESH,
+  MSG_OPEN_TAB
+} from './utils/iframeBridge'
+export type { IframeOpenTabPayload } from './utils/iframeBridge'
 export default {
-  install(Vue: App, options?: { locale: string; messages: any }[]): void {
-    tabVersion(import.meta.env.PACKAGE_VERSION)
-    Vue.component('VueStackTabs', StackTab).use(useTabMitt).use(i18n().getI18n(options))
+  install(Vue: App, options?: { locale: string; messages: Record<string, unknown> }[]): void {
+    logVersion(import.meta.env.PACKAGE_VERSION)
+    Vue.component('VueStackTabs', StackTab).use(useTabEventBus).use(i18n().getI18n(options))
   }
 }

package/src/lib/model/TabModel.spec.ts

@@ -0,0 +1,40 @@
+import { describe, it, expect } from 'vitest'
+import { Stack } from './TabModel'
+
+describe('Stack', () => {
+  it('push 与 peek', () => {
+    const s = new Stack<number>()
+    s.push(1)
+    expect(s.peek()).toBe(1)
+    s.push(2)
+    expect(s.peek()).toBe(2)
+  })
+
+  it('pop 返回栈顶并移除', () => {
+    const s = new Stack<string>(['a', 'b'])
+    expect(s.pop()).toBe('b')
+    expect(s.pop()).toBe('a')
+    expect(s.pop()).toBeUndefined()
+  })
+
+  it('size 与 isEmpty', () => {
+    const s = new Stack<number>()
+    expect(s.isEmpty()).toBe(true)
+    expect(s.size()).toBe(0)
+    s.push(1)
+    expect(s.isEmpty()).toBe(false)
+    expect(s.size()).toBe(1)
+  })
+
+  it('list 返回元素数组', () => {
+    const s = new Stack<number>([1, 2, 3])
+    expect(s.list()).toEqual([1, 2, 3])
+  })
+
+  it('clear 清空栈', () => {
+    const s = new Stack<number>([1, 2])
+    s.clear()
+    expect(s.isEmpty()).toBe(true)
+    expect(s.peek()).toBeUndefined()
+  })
+})

package/src/lib/model/TabModel.ts

@@ -1,4 +1,11 @@
-// Tab的滚动方式
+/**
+ * TabModel - 标签页数据模型
+ *
+ * 职责：定义标签、页面、栈结构及右键菜单的数据结构
+ * 使用：useTabPanel、useTabActions、ContextMenu 等
+ */
+
+/** 标签栏滚动方式：滚轮、按钮、或两者 */
 export enum TabScrollMode {
   // 使用滚轮
   WHEEL = 'wheel',
@@ -19,56 +26,63 @@ export enum TabScrollMode {
 //   TAB_REFRESH = 'TAB_REFRESH',
 //   TAB_REFRESH_ALL = 'TAB_REFRESH_ALL'
 // }
-// 拖拽数据接口
+/** 标签栏滚动条拖拽时的临时状态 */
 export interface DragData {
   thumbLeft: number
   startScrollLeft: number
   startThumbLeft: number
   startPageX: number
 }
-// 滑块数据接口
+/** 滚动条滑块计算所需的数据 */
 export interface ScrollData {
   clientWidth: number
   scrollWidth: number
   scrollLeft: number
 }
-// 滚动条事件类型
 export type ScrollEvents = {
   ScrollUpdate: void
 }
 
-/**
- * Tab data for open
- */
+/** 打开标签时传入的完整数据（含 path、query） */
 export interface ITabData extends ITabBase {
   // tab name
   title: string
   path: string
   query?: Record<string, string>
 }
+/** iframe 刷新方式：postMessage 由 iframe 内页自行刷新（不重建 DOM，动画正常）；reload 强制重载 iframe */
+export type IframeRefreshMode = 'postMessage' | 'reload'
+
+/** 标签基础信息（id、title、是否可关闭/刷新、是否 iframe） */
 export interface ITabBase {
   id?: string
   title: string
   closable?: boolean
   refreshable?: boolean
   iframe?: boolean
+  /** iframe 刷新方式，默认 postMessage */
+  iframeRefreshMode?: IframeRefreshMode
 }
+/** 内部使用的标签项，含 active 状态和 pages 栈 */
 export interface ITabItem extends ITabBase {
   id: string
   closable: boolean
   refreshable: boolean
   iframe: boolean
+  iframeRefreshMode?: IframeRefreshMode
   url?: string
   active: boolean
   pages: Stack<ITabPage>
 }
 
+/** 标签内的单个页面（对应 keep-alive 的一个缓存实例） */
 export interface ITabPage {
   id: string
   tabId: string
   path: string
   query?: Record<string, string>
 }
+/** 右键菜单项：图标、标题、回调、禁用条件 */
 export interface IContextMenu {
   icon?: string
   title: string
@@ -84,11 +98,10 @@ export interface IContextMenu {
 //   path: string
 //   query: any
 // }
+/** 使用 Map 实现的栈结构，用于标签内的 pages 页面栈 */
 export class Stack<T> {
-  // 存储的Map
   private items: Map<number, T>
 
-  //
   constructor(items?: T[]) {
     this.items = new Map()
     if (items) {

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

@@ -0,0 +1,19 @@
+import type { ModuleOptions } from './module'
+
+declare module 'nuxt/schema' {
+  interface PublicRuntimeConfig {
+    vueStackTabs: {
+      locale: string
+    }
+  }
+}
+
+declare module '@nuxt/schema' {
+  interface PublicRuntimeConfig {
+    vueStackTabs: {
+      locale: string
+    }
+  }
+}
+
+export type { ModuleOptions }

package/src/lib/nuxt/module.ts

@@ -0,0 +1,34 @@
+import { addPlugin, addImports, createResolver, defineNuxtModule } from '@nuxt/kit'
+
+export interface ModuleOptions {
+  /** 默认语言 */
+  locale?: string
+}
+
+export default defineNuxtModule<ModuleOptions>({
+  meta: {
+    name: 'vue-stack-tabs',
+    configKey: 'vueStackTabs'
+  },
+  defaults: {
+    locale: 'zh-CN'
+  },
+  setup(options, nuxt) {
+    const { resolve } = createResolver(import.meta.url)
+
+    nuxt.options.runtimeConfig.public.vueStackTabs = {
+      locale: options.locale
+    }
+
+    addPlugin({
+      src: resolve('./runtime/plugin.client'),
+      mode: 'client'
+    })
+
+    addImports([
+      { name: 'useTabActions', from: 'vue-stack-tabs' },
+      { name: 'useTabRouter', from: 'vue-stack-tabs' },
+      { name: 'useTabLoading', from: 'vue-stack-tabs' }
+    ])
+  }
+})

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

@@ -0,0 +1,11 @@
+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.spec.ts

@@ -0,0 +1,37 @@
+/**
+ * @vitest-environment happy-dom
+ */
+import { describe, it, expect, vi } from 'vitest'
+import { MSG_REFRESH, MSG_OPEN_TAB, postOpenTab, onRefreshRequest } from './iframeBridge'
+
+describe('iframeBridge', () => {
+  it('MSG_REFRESH 和 MSG_OPEN_TAB 为预期常量', () => {
+    expect(MSG_REFRESH).toBe('vue-stack-tabs:refresh')
+    expect(MSG_OPEN_TAB).toBe('vue-stack-tabs:openTab')
+  })
+
+  describe('postOpenTab', () => {
+    it('有 window.parent 时调用 postMessage', () => {
+      const spy = vi.spyOn(window.parent, 'postMessage')
+      postOpenTab({ title: 't', path: '/p' })
+      expect(spy).toHaveBeenCalledWith(
+        { type: MSG_OPEN_TAB, payload: { title: 't', path: '/p' } },
+        '*'
+      )
+      spy.mockRestore()
+    })
+  })
+
+  describe('onRefreshRequest', () => {
+    it('注册监听并返回取消函数', () => {
+      const cb = vi.fn()
+      const off = onRefreshRequest(cb)
+      expect(typeof off).toBe('function')
+      window.dispatchEvent(new MessageEvent('message', { data: { type: MSG_REFRESH } }))
+      expect(cb).toHaveBeenCalled()
+      off()
+      window.dispatchEvent(new MessageEvent('message', { data: { type: MSG_REFRESH } }))
+      expect(cb).toHaveBeenCalledTimes(1)
+    })
+  })
+})

package/src/lib/utils/iframeBridge.ts

@@ -0,0 +1,52 @@
+/**
+ * iframe 与父窗口的 postMessage 桥接
+ *
+ * 在 iframe 内的页面中引入，用于：
+ * - 接收父窗口的刷新指令并执行
+ * - 向父窗口发送打开新标签的请求
+ */
+
+/** 刷新消息：父 -> iframe，iframe 内页面需监听并执行 location.reload() 或自身刷新逻辑 */
+export const MSG_REFRESH = 'vue-stack-tabs:refresh'
+
+/** 打开标签消息：iframe -> 父，payload 为 ITabData */
+export const MSG_OPEN_TAB = 'vue-stack-tabs:openTab'
+
+export interface IframeOpenTabPayload {
+  id?: string
+  title: string
+  path: string
+  query?: Record<string, string>
+  closable?: boolean
+  refreshable?: boolean
+  iframe?: boolean
+}
+
+/**
+ * 在 iframe 内调用：向父窗口请求打开新标签
+ * @param payload 标签数据，至少需 title、path
+ */
+export function postOpenTab(payload: IframeOpenTabPayload) {
+  if (typeof window === 'undefined' || !window.parent) return
+  window.parent.postMessage(
+    { type: MSG_OPEN_TAB, payload },
+    '*' // 父窗口可校验 origin，此处用 * 便于跨子域
+  )
+}
+
+/**
+ * 在 iframe 内调用：注册刷新监听，收到父窗口刷新指令时执行 callback
+ * @param callback 默认 location.reload()，可自定义
+ * @returns 取消监听的函数
+ */
+export function onRefreshRequest(callback: () => void = () => window.location.reload()) {
+  if (typeof window === 'undefined') return () => {}
+
+  const handler = (ev: MessageEvent) => {
+    if (ev.data?.type === MSG_REFRESH) {
+      callback()
+    }
+  }
+  window.addEventListener('message', handler)
+  return () => window.removeEventListener('message', handler)
+}