vue-stack-tabs 0.1.50 → 1.0.0

package/src/lib/components/ContextMenu/index.vue

@@ -1,62 +1,75 @@
+<!--
+  ContextMenu - 标签右键菜单
+
+  职责：刷新、关闭、关闭左侧/右侧/其他/全部、新窗口打开（iframe），以及自定义菜单项
+  扩展：通过 contextMenu prop 传入 IContextMenu[] 添加自定义项
+-->
 <template>
   <div
-    ref="contextmenu"
+    ref="menuElementRef"
     class="stack-tab__contextmenu"
     :style="{
-      left: `${modifyData.left}px`,
-      top: `${modifyData.top}px`,
+      left: `${menuPosition.left}px`,
+      top: `${menuPosition.top}px`,
       'z-index': getMaxZIndex('.stack-tab,.stack-tab *')
     }"
   >
     <context-menu-item
       icon="stack-tab__icon-reload svg-mask"
       :title="t('VueStackTab.reload')"
-      @click="refreshTab(tabItem.id)"
+      :disabled="!tabItem.refreshable ? 'disabled' : null"
+      @click="handleMenuItemClick(() => refreshTab(tabItem.id))"
     />
     <context-menu-item
       icon="stack-tab__icon-reload-all svg-mask"
       :title="t('VueStackTab.reloadAll')"
-      @click="refreshAllTabs"
+      @click="handleMenuItemClick(refreshAllTabs)"
     />
     <context-menu-item
       icon="stack-tab__icon-close svg-mask"
       :title="t('VueStackTab.close')"
       :disabled="!tabItem.closable ? 'disabled' : null"
-      @click="removeTab(tabItem.id)"
+      @click="handleMenuItemClick(() => closeTab(tabItem.id))"
     />
     <context-menu-item
       icon="stack-tab__icon-close-lefts svg-mask"
       :title="t('VueStackTab.closeLeft')"
       :disabled="index <= 0 ? 'disabled' : null"
-      @click="removeLeftTabs(tabItem.id)"
+      @click="handleMenuItemClick(() => removeLeftTabs(tabItem.id))"
     />
     <context-menu-item
       icon="stack-tab__icon-close-rights svg-mask"
       :title="t('VueStackTab.closeRight')"
       :disabled="index >= max - 1 ? 'disabled' : null"
-      @click="removeRightTabs(tabItem.id)"
+      @click="handleMenuItemClick(() => removeRightTabs(tabItem.id))"
     />
     <context-menu-item
       icon="stack-tab__icon-close-others svg-mask"
       :title="t('VueStackTab.closeOthers')"
-      @click="removeOtherTabs(tabItem.id)"
+      @click="handleMenuItemClick(() => removeOtherTabs(tabItem.id))"
     />
     <context-menu-item
       icon="stack-tab__icon-close-all svg-mask"
       :title="t('VueStackTab.closeAll')"
-      @click="removeAllTabs"
+      @click="handleMenuItemClick(closeAllTabs)"
+    />
+    <context-menu-item
+      v-if="tabItem.iframe && tabItem.url"
+      icon="stack-tab__icon-open svg-mask"
+      :title="t('VueStackTab.openInNewWindow')"
+      @click="handleMenuItemClick(() => openInNewWindow(tabItem.id))"
     />
     <div
       v-if="contextMenu !== undefined && contextMenu.length > 0"
       class="divider div-transparent"
     ></div>
     <context-menu-item
-      v-for="(item, index) in contextMenu"
-      :key="index"
+      v-for="(item, menuIndex) in contextMenu"
+      :key="menuIndex"
       :icon="item.icon"
       :title="item.title"
       :disabled="item.disabled(tabItem) ? 'disabled' : null"
-      @click="!item.disabled && item.callback(tabItem.id)"
+      @click="handleMenuItemClick(() => !item.disabled(tabItem) && item.callback(tabItem.id))"
     />
   </div>
 </template>
@@ -65,15 +78,16 @@
 import { ref, onMounted, reactive } from 'vue'
 import type { ITabItem, IContextMenu } from '../../model/TabModel'
 import { useI18n } from 'vue-i18n-lite'
-import { getMaxZIndex } from '../../utils/TabScrollHelper'
-import useTabpanel from '../../hooks/useTabpanel'
+import { getMaxZIndex } from '../../utils/scrollUtils'
+import useTabActions from '../../hooks/useTabActions'
+import useTabPanel from '../../hooks/useTabPanel'
 import ContextMenuItem from './ContextMenuItem.vue'
-// const emit = defineEmits(['close', 'closeAll', 'closeLeft', 'closeRight', 'refresh', 'refreshAll'])
+
 const props = withDefaults(
   defineProps<{
     index: number
-    left: number
-    top: number
+    left?: number
+    top?: number
     contextMenu?: Array<IContextMenu>
     tabItem: ITabItem
     max: number
@@ -81,30 +95,28 @@ const props = withDefaults(
   {
     left: 0,
     top: 0,
-    contextMen: []
+    contextMenu: () => []
   }
 )
-// @ts-ignore
+const emit = defineEmits<{ close: [] }>()
 const { t } = useI18n()
-const contextmenu = ref<HTMLElement>()
-const modifyData = reactive({
-  left: props.left,
-  top: props.top
-})
-const {
-  removeTab,
-  removeAllTabs,
-  removeLeftTabs,
-  removeRightTabs,
-  refreshTab,
-  refreshAllTabs,
-  removeOtherTabs
-} = useTabpanel()
+/** 菜单根元素，用于计算宽度做右边界溢出修正 */
+const menuElementRef = ref<HTMLElement>()
+/** 菜单定位坐标，onMounted 时根据右边界修正 left */
+const menuPosition = reactive({ left: props.left, top: props.top })
+const { closeTab, closeAllTabs, refreshTab, refreshAllTabs, openInNewWindow } = useTabActions()
+const { removeLeftTabs, removeRightTabs, removeOtherTabs } = useTabPanel()
+
+/** 菜单项点击：执行回调并关闭菜单 */
+const handleMenuItemClick = (fn?: () => void) => {
+  fn?.()
+  emit('close')
+}
+/** 挂载后修正菜单位置，避免超出右边界 */
 onMounted(() => {
-  const clientWidth = contextmenu.value ? contextmenu.value.clientWidth : 0
-  const winWidth = window.innerWidth
-  if (modifyData.left + clientWidth > winWidth) {
-    modifyData.left = winWidth - clientWidth - 5
+  const menuWidth = menuElementRef.value?.clientWidth ?? 0
+  if (menuPosition.left + menuWidth > window.innerWidth) {
+    menuPosition.left = window.innerWidth - menuWidth - 5
   }
 })
 </script>

package/src/lib/components/PageLoading.vue

@@ -1,21 +1,41 @@
+<!--
+  PageLoading - 页面加载遮罩
+
+  职责：监听 PAGE_LOADING 事件，按 tabId 显示/隐藏 loading 遮罩
+  使用：在 useTabPanel 的 cache 组件内按 tab 渲染
+-->
 <template>
-  <div v-if="loading" class="stack-tab-loading-mask" :style="{zIndex: getMaxZIndex('.cache-page-wrapper *')}">
+  <div
+    v-if="isLoading"
+    class="stack-tab-loading-mask"
+    :style="{ zIndex: getMaxZIndex('.cache-page-wrapper *') }"
+  >
     <div class="stack-tab-loading--spin turn" />
   </div>
 </template>
 <script setup lang="ts">
-import { ref } from 'vue'
-import { MittType, useEmitter } from '../hooks/useTabMitt'
-import { getMaxZIndex } from '../utils/TabScrollHelper'
+import { ref, onUnmounted } from 'vue'
+import { TabEventType, useTabEmitter } from '../hooks/useTabEventBus'
+import { getMaxZIndex } from '../utils/scrollUtils'
 const props = defineProps<{
-  tId: string
+  /** 当前标签 id，用于过滤 PAGE_LOADING 事件 */
+  tabId: string
 }>()
-const emitter = useEmitter()
-const loading = ref<boolean>(false)
-emitter.on(MittType.PAGE_LOADING, ({ tId, value }: any) => {
-  if (tId === props.tId) {
-    loading.value = value
+const emitter = useTabEmitter()
+/** 是否显示 loading 遮罩 */
+const isLoading = ref<boolean>(false)
+/** PAGE_LOADING 事件 payload */
+type PageLoadingPayload = { tId: string; value: boolean }
+/** 处理 PAGE_LOADING 事件，仅当 tId 匹配时更新 */
+const handleLoadingEvent = (payload: PageLoadingPayload) => {
+  if (payload.tId === props.tabId) {
+    isLoading.value = payload.value
   }
+}
+const eventType = TabEventType.PAGE_LOADING as unknown as Parameters<typeof emitter.on>[0]
+emitter.on(eventType, handleLoadingEvent as (e: unknown) => void)
+onUnmounted(() => {
+  emitter.off(eventType, handleLoadingEvent as (e: unknown) => void)
 })
 </script>
 <style scoped></style>

package/src/lib/components/TabHeader/TabHeaderButton.vue

@@ -1,3 +1,8 @@
+<!--
+  TabHeaderButton - 通用图标按钮
+
+  职责：左右滚动箭头、全屏/还原按钮，支持禁用与阴影样式
+-->
 <template>
   <div
     class="stack-tab__header-button"
@@ -18,16 +23,20 @@
 <script lang="ts" setup>
 withDefaults(
   defineProps<{
-    // 是否禁用
+    /** 是否禁用 */
     disabled?: boolean
-    shadow?: string | null
+    /** 阴影方向，用于滚动到边界时的视觉提示 */
+    shadow?: 'left' | 'right' | null
+    /** 图标 class（无 slot 时使用） */
     iconClass?: string
+    /** 悬停提示 */
     title?: string
   }>(),
   {
     disabled: false,
     shadow: null,
-    iconClass: ''
+    iconClass: '',
+    title: ''
   }
 )
 </script>

package/src/lib/components/TabHeader/TabHeaderItem.vue

@@ -1,12 +1,12 @@
 <template>
   <li
-    ref="curtab"
+    ref="tabElementRef"
     class="stack-tab__item"
     :class="{
       'is-active': item.active,
       'is-icon': item.closable
     }"
-    @click="activeTab(true)"
+    @click="handleActivate(true)"
   >
     <!--    <div v-if="!!icon" class="stack-tab__item-icon" :class="icon"></div>-->
     <div class="stack-tab__item-title">
@@ -18,51 +18,55 @@
       v-if="item.closable"
       class="stack-tab__icon-close-fill stack-tab__item-button"
       :title="t('VueStackTab.close')"
-      @click.stop="closeTab"
+      @click.stop="handleClose"
     />
   </li>
 </template>
 
+<!--
+  TabHeaderItem - 单个标签项
+
+  职责：展示标签标题、激活/关闭，监听 TAB_ACTIVE 事件
+-->
 <script setup lang="ts">
-import { computed, ref } from 'vue'
+import { computed, ref, onUnmounted } from 'vue'
 import type { ITabItem } from '@/lib/model/TabModel'
-import { MittType, useEmitter } from '../../hooks/useTabMitt'
+import { TabEventType, useTabEmitter } from '../../hooks/useTabEventBus'
 import { useI18n } from 'vue-i18n-lite'
-// 消息
 const emit = defineEmits(['close', 'active'])
-const emitter = useEmitter()
+const emitter = useTabEmitter()
 const { t } = useI18n()
-const curtab = ref<HTMLElement>()
+/** 当前标签 DOM 元素，用于滚动到可视区域 */
+const tabElementRef = ref<HTMLElement>()
 const props = defineProps<{
   item: ITabItem
 }>()
-/**
- * 如果Active为true，就看看
- */
-// watch(
-//   () => props.item.active,
-//   (val) => {
-//     if (val) {
-//       activeTab()
-//     }
-//   }
-// )
-emitter.on(MittType.TAB_ACTIVE, ({ id, isRoute }: any) => {
-  if (props.item.id === id) {
-    activeTab(isRoute)
+
+/** TAB_ACTIVE 事件 payload */
+type TabActivePayload = { id: string; isRoute?: boolean }
+/** 收到 TAB_ACTIVE 且 id 匹配时，触发激活 */
+const handleTabActiveEvent = (payload: TabActivePayload) => {
+  if (props.item.id === payload.id) {
+    handleActivate(payload.isRoute ?? true)
   }
+}
+const eventType = TabEventType.TAB_ACTIVE as unknown as Parameters<typeof emitter.on>[0]
+emitter.on(eventType, handleTabActiveEvent as (e: unknown) => void)
+onUnmounted(() => {
+  emitter.off(eventType, handleTabActiveEvent as (e: unknown) => void)
 })
+/** 显示标题，空时用 i18n 占位 */
 const title = computed<string>(() => {
   return props.item.title || t('undefined')
 })
 
-const closeTab = () => {
+/** 关闭按钮点击，向父级 emit close */
+const handleClose = () => {
   emit('close', props.item)
 }
-const activeTab = (isRoute: boolean = true) => {
-  // if (!props.active) {
-  emit('active', props.item, curtab, isRoute)
-  // }
+/** 激活当前标签，向父级 emit active 并传递 DOM 引用 */
+const handleActivate = (isRoute = true) => {
+  emit('active', props.item, tabElementRef.value, isRoute)
 }
 </script>
 

package/src/lib/components/TabHeader/TabHeaderScroll.vue

@@ -1,11 +1,16 @@
+<!--
+  TabHeaderScroll - 可横向滚动的标签栏容器
+
+  职责：左右箭头滚动、滚轮滚动、自定义滚动条拖拽、确保激活标签在可视区域内
+-->
 <template>
   <tab-header-button
-    v-if="isButtonVisibled"
+    v-if="isScrollButtonVisible"
     icon-class="stack-tab__icon-left-arrow"
     :disabled="isDisabledLeftButton"
-    @click="!isDisabledLeftButton && onButton(-1 * space)"
+    @click="!isDisabledLeftButton && handleScrollButtonClick(-1 * space)"
   />
-  <div ref="headerScroll" class="stack-tab__scroll" @wheel.passive="onWheel">
+  <div ref="headerScroll" class="stack-tab__scroll" @wheel.passive="handleWheelScroll">
     <div
       ref="container"
       class="stack-tab__scroll-container"
@@ -14,7 +19,7 @@
         'stack-tab__shadow-inset-right': !isDisabledRightButton && isDisabledLeftButton,
         'stack-tab__shadow-inset-all': !isDisabledLeftButton && !isDisabledRightButton
       }"
-      @scroll.passive="update"
+      @scroll.passive="updateScrollState"
     >
       <slot />
     </div>
@@ -32,15 +37,15 @@
           width: `${thumbWidth}px`,
           transform: `translateX(${thumbLeft}px)`
         }"
-        @mousedown.prevent="onDragStart"
+        @mousedown.prevent="handleScrollbarDragStart"
       />
     </div>
   </div>
   <tab-header-button
-    v-if="isButtonVisibled"
+    v-if="isScrollButtonVisible"
     icon-class="stack-tab__icon-right-arrow"
     :disabled="isDisabledRightButton"
-    @click="!isDisabledRightButton && onButton(space!)"
+    @click="!isDisabledRightButton && handleScrollButtonClick(space!)"
   />
 </template>
 
@@ -48,23 +53,35 @@
 import { computed, ref, reactive, onMounted, watch, onUnmounted } from 'vue'
 import { ResizeObserver } from '@juggle/resize-observer'
 import type { ScrollData, DragData } from '@/lib/model/TabModel'
-import { _scrollTo, _scrollIntoView } from '@/lib/utils/TabScrollHelper'
+import {
+  scrollTo as scrollToUtil,
+  scrollIntoView as scrollIntoViewUtil
+} from '@/lib/utils/scrollUtils'
 import TabHeaderButton from '@/lib/components/TabHeader/TabHeaderButton.vue'
 
-// ref
+/** 标签列表滚动容器 */
 const container = ref<HTMLElement | null>(null)
+/** 滚动条轨道 */
 const bar = ref<HTMLElement | null>(null)
+/** 滚动条滑块 */
 const thumb = ref<HTMLElement | null>(null)
+/** 是否正在拖拽滚动条 */
 const scrollDragging = ref<boolean>(false)
+/** 左箭头是否禁用（已到最左） */
 const isDisabledLeftButton = ref<boolean>(false)
+/** 右箭头是否禁用（已到最右） */
 const isDisabledRightButton = ref<boolean>(false)
-const isButtonVisibled = ref<boolean>(true)
+/** 是否有横向滚动条（内容超出时显示左右箭头） */
+const isScrollButtonVisible = ref<boolean>(true)
+/** 外层滚动区域，用于 ResizeObserver */
 const headerScroll = ref<HTMLElement>()
 const props = withDefaults(
   defineProps<{
-    // 每次移动距离
+    /** 每次点击箭头或滚轮的移动距离（px） */
     space?: number
+    /** 是否支持滚轮滚动 */
     isScrollWheel?: boolean
+    /** 是否显示左右箭头 */
     isScrollButton?: boolean
   }>(),
   {
@@ -73,14 +90,13 @@ const props = withDefaults(
     isScrollButton: true
   }
 )
-/**
- * 滚动条数据
- */
+/** 滚动容器尺寸与滚动位置，用于计算滑块和按钮状态 */
 const scrollData = reactive<ScrollData>({
   clientWidth: 0,
   scrollWidth: 0,
   scrollLeft: 0
 })
+/** 拖拽滚动条时的起始状态 */
 const dragData = reactive<DragData>({
   thumbLeft: 0,
   startScrollLeft: 0,
@@ -88,25 +104,25 @@ const dragData = reactive<DragData>({
   startPageX: 0
 })
 
-// 监控滚动条数据用于启用/禁用按钮
-watch(scrollData, (newValue) => {
-  setScrollButton(newValue)
+/** 滚动数据变化时更新箭头与滚动条的启用状态 */
+watch(scrollData, (data) => {
+  updateScrollButtonState(data)
 })
 
-const setScrollButton = (scrollData: ScrollData) => {
-  isDisabledLeftButton.value = scrollData.scrollLeft <= 10
+/** 根据滚动位置更新左右箭头禁用状态及滚动条可见性 */
+const updateScrollButtonState = (data: ScrollData) => {
+  isDisabledLeftButton.value = data.scrollLeft <= 10
   isDisabledRightButton.value =
-    scrollData.clientWidth + scrollData.scrollLeft - scrollData.scrollWidth >= -10
-  isButtonVisibled.value = scrollData.scrollWidth !== scrollData.clientWidth
+    data.clientWidth + data.scrollLeft - data.scrollWidth >= -10
+  isScrollButtonVisible.value = data.scrollWidth !== data.clientWidth
 }
 
-// 计算属性
-// 是否拥有滚动条
+/** 内容是否超出容器宽度，需要显示滚动条 */
 const hasScroller = computed<boolean>(() => {
   return scrollData.scrollWidth > scrollData.clientWidth
 })
 
-// 滑块宽度
+/** 滚动条滑块宽度（按内容比例计算） */
 const thumbWidth = computed<number>(() => {
   if (!hasScroller.value) return 0
 
@@ -114,7 +130,7 @@ const thumbWidth = computed<number>(() => {
   return (clientWidth / scrollWidth) * clientWidth
 })
 
-// 滑块 left
+/** 滚动条滑块 left 偏移（与 scrollLeft 对应） */
 const thumbLeft = computed(() => {
   if (!hasScroller.value) return 0
 
@@ -123,52 +139,45 @@ const thumbLeft = computed(() => {
   return (clientWidth - thumbWidth.value) * (scrollLeft / (scrollWidth - clientWidth))
 })
 
-// 方法
-// 更新滚动数据
-const update = () => {
-  // 判断 container是否为空，主空直接返回
-  if (container.value === null || container.value === undefined) {
-    return
-  }
+/** 更新滚动条数据 */
+const updateScrollState = () => {
+  if (!container.value) return
   const { clientWidth, scrollWidth, scrollLeft } = container.value
-
   Object.assign(scrollData, { clientWidth, scrollWidth, scrollLeft })
 }
-const resizeUpdate = new ResizeObserver(() => {
-  update()
-  const cur = container.value?.querySelector('.stack-tab__item.is-active')
-  if (cur) {
-    if (!isInView(cur as HTMLElement)) {
-      scrollIntoView(cur as HTMLElement)
-    }
+
+/** 确保激活的标签在可视区域内 */
+const ensureActiveTabInView = () => {
+  const activeTabEl = container.value?.querySelector('.stack-tab__item.is-active') as HTMLElement | null
+  if (activeTabEl && !isInView(activeTabEl)) {
+    scrollIntoView(activeTabEl)
   }
+}
+
+const scrollContainerResizeObserver = new ResizeObserver(() => {
+  updateScrollState()
+  ensureActiveTabInView()
 })
-const tabsUpdate = new ResizeObserver(() => {
-  if (!hasScroller.value) {
-    const cur = container.value?.querySelector('.stack-tab__item.is-active')
-    if (cur) {
-      if (!isInView(cur as HTMLElement)) {
-        scrollIntoView(cur as HTMLElement)
-      }
-    }
-  }
-  update()
+
+const tabListResizeObserver = new ResizeObserver(() => {
+  if (!hasScroller.value) ensureActiveTabInView()
+  updateScrollState()
 })
-// 滚动到指定位置
+/** 滚动到指定 left 位置 */
 const scrollTo = (left: number, smooth = true) => {
-  _scrollTo({ wrap: container.value, left, smooth })
+  scrollToUtil({ wrap: container.value, left, top: 0, smooth })
 }
 
-const onButton = (space: number) => {
-  scrollTo(container.value!.scrollLeft + space)
+const handleScrollButtonClick = (delta: number) => {
+  scrollTo(container.value!.scrollLeft + delta)
 }
-// 页签鼠标滚动
-const onWheel = (e: WheelEvent) => {
-  const isWheelUp = e.deltaY < 0
-  scrollTo(container.value!.scrollLeft + (isWheelUp ? -props.space : props.space))
+
+const handleWheelScroll = (e: WheelEvent) => {
+  const isScrollUp = e.deltaY < 0
+  scrollTo(container.value!.scrollLeft + (isScrollUp ? -props.space : props.space))
 }
-// 拖拽
-const onDragStart = (e: MouseEvent) => {
+
+const handleScrollbarDragStart = (e: MouseEvent) => {
   Object.assign(dragData, {
     startPageX: e.pageX,
     startScrollLeft: container.value?.scrollLeft,
@@ -176,12 +185,11 @@ const onDragStart = (e: MouseEvent) => {
     thumbLeft: thumbLeft.value
   })
   scrollDragging.value = true
-  document.addEventListener('mousemove', onDragMove)
-  document.addEventListener('mouseup', onDragEnd)
+  document.addEventListener('mousemove', handleScrollbarDragMove)
+  document.addEventListener('mouseup', handleScrollbarDragEnd)
 }
 
-// 拖拽移动
-const onDragMove = (e: MouseEvent) => {
+const handleScrollbarDragMove = (e: MouseEvent) => {
   const { clientWidth, scrollWidth } = scrollData
   let thumbLeft = dragData.startThumbLeft + e.pageX - dragData.startPageX
   const maxThumbLeft = clientWidth - thumbWidth.value
@@ -197,30 +205,28 @@ const onDragMove = (e: MouseEvent) => {
   scrollTo((thumbLeft * (scrollWidth - clientWidth)) / (clientWidth - thumbWidth.value), false)
   e.preventDefault()
 }
-// 拖拽结束
-const onDragEnd = (e: MouseEvent) => {
-  scrollDragging.value = false
-  document.removeEventListener('mousemove', onDragMove)
-  document.removeEventListener('mouseup', onDragEnd)
 
-  e.preventDefault()
+const handleScrollbarDragEnd = () => {
+  scrollDragging.value = false
+  document.removeEventListener('mousemove', handleScrollbarDragMove)
+  document.removeEventListener('mouseup', handleScrollbarDragEnd)
 }
+
 onMounted(() => {
-  resizeUpdate.observe(headerScroll.value as Element)
+  scrollContainerResizeObserver.observe(headerScroll.value as Element)
   const tabNav = container.value?.querySelector('.stack-tab__nav')
-  tabsUpdate.observe(tabNav!)
+  tabListResizeObserver.observe(tabNav!)
 })
 onUnmounted(() => {
-  resizeUpdate.disconnect()
-  tabsUpdate.disconnect()
+  scrollContainerResizeObserver.disconnect()
+  tabListResizeObserver.disconnect()
 })
 
-// 滚动到元素
 const scrollIntoView = (el: HTMLElement) => {
-  _scrollIntoView({ el, wrap: container, block: 'end', inline: 'center' })
+  scrollIntoViewUtil({ el, wrap: container.value, block: 'end', inline: 'center' })
 }
 
-// 判断子节点是否完全在可视区域
+/** 判断元素是否在横向滚动可视区域内 */
 const isInView = (el: HTMLElement) => {
   if (!hasScroller.value) {
     return true