vue-stack-tabs 1.0.1 → 1.3.0

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

@@ -4,19 +4,31 @@
   职责：展示图标和标题，支持 disabled 状态
 -->
 <template>
-  <div class="stack-tab__contextmenu-item">
-    <div class="stack-tab__contextmenu-icon" :class="icon"></div>
-    <div style="margin-left: 8px" @contextmenu.prevent>{{ title }}</div>
-  </div>
+  <button type="button" role="menuitem" class="stack-tab__contextmenu-item" :disabled="disabled">
+    <span class="stack-tab__contextmenu-icon" :class="icon" aria-hidden="true" />
+    <span class="stack-tab__contextmenu-title" @contextmenu.prevent>{{ title }}</span>
+  </button>
 </template>
 
 <script setup lang="ts">
-defineProps<{
-  /** 图标 class，如 stack-tab__icon-reload svg-mask */
-  icon?: string
-  /** 显示文本 */
-  title: string
-}>()
+withDefaults(
+  defineProps<{
+    /** 图标 class，如 stack-tab__icon-reload svg-mask */
+    icon?: string
+    /** 显示文本 */
+    title: string
+    /** 是否禁用 */
+    disabled?: boolean
+  }>(),
+  {
+    icon: '',
+    disabled: false
+  }
+)
 </script>
 
-<style lang="scss" scoped></style>
+<style lang="scss" scoped>
+.stack-tab__contextmenu-title {
+  margin-left: 8px;
+}
+</style>

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

@@ -8,16 +8,19 @@
   <div
     ref="menuElementRef"
     class="stack-tab__contextmenu"
+    role="menu"
+    tabindex="-1"
     :style="{
       left: `${menuPosition.left}px`,
       top: `${menuPosition.top}px`,
       'z-index': getMaxZIndex('.stack-tab,.stack-tab *')
     }"
+    @keydown="handleMenuKeydown"
   >
     <context-menu-item
       icon="stack-tab__icon-reload svg-mask"
       :title="t('VueStackTab.reload')"
-      :disabled="!tabItem.refreshable ? 'disabled' : null"
+      :disabled="!tabItem.refreshable"
       @click="handleMenuItemClick(() => refreshTab(tabItem.id))"
     />
     <context-menu-item
@@ -28,19 +31,19 @@
     <context-menu-item
       icon="stack-tab__icon-close svg-mask"
       :title="t('VueStackTab.close')"
-      :disabled="!tabItem.closable ? 'disabled' : null"
+      :disabled="!tabItem.closable"
       @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"
+      :disabled="index <= 0"
       @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"
+      :disabled="index >= max - 1"
       @click="handleMenuItemClick(() => removeRightTabs(tabItem.id))"
     />
     <context-menu-item
@@ -62,20 +65,23 @@
     <div
       v-if="contextMenu !== undefined && contextMenu.length > 0"
       class="divider div-transparent"
+      role="separator"
+      aria-orientation="horizontal"
     ></div>
     <context-menu-item
-      v-for="(item, menuIndex) in contextMenu"
-      :key="menuIndex"
+      v-for="item in contextMenu"
+      :key="getCustomMenuKey(item)"
+      :data-menu-key="getCustomMenuKey(item)"
       :icon="item.icon"
       :title="item.title"
-      :disabled="item.disabled(tabItem) ? 'disabled' : null"
+      :disabled="item.disabled(tabItem)"
       @click="handleMenuItemClick(() => !item.disabled(tabItem) && item.callback(tabItem.id))"
     />
   </div>
 </template>
 
 <script setup lang="ts">
-import { ref, onMounted, reactive } from 'vue'
+import { ref, onMounted, reactive, nextTick } from 'vue'
 import type { ITabItem, IContextMenu } from '../../model/TabModel'
 import { useI18n } from 'vue-i18n-lite'
 import { getMaxZIndex } from '../../utils/scrollUtils'
@@ -89,13 +95,15 @@ const props = withDefaults(
     left?: number
     top?: number
     contextMenu?: Array<IContextMenu>
+    restoreFocusElement?: HTMLElement | null
     tabItem: ITabItem
     max: number
   }>(),
   {
     left: 0,
     top: 0,
-    contextMenu: () => []
+    contextMenu: () => [],
+    restoreFocusElement: null
   }
 )
 const emit = defineEmits<{ close: [] }>()
@@ -107,17 +115,93 @@ const menuPosition = reactive({ left: props.left, top: props.top })
 const { closeTab, closeAllTabs, refreshTab, refreshAllTabs, openInNewWindow } = useTabActions()
 const { removeLeftTabs, removeRightTabs, removeOtherTabs } = useTabPanel()
 
+const focusActiveTabFallback = () => {
+  const activeTab = document.querySelector<HTMLElement>('[role="tab"][aria-selected="true"]')
+  activeTab?.focus()
+}
+
+const restoreFocusToTrigger = () => {
+  if (props.restoreFocusElement && document.contains(props.restoreFocusElement)) {
+    props.restoreFocusElement.focus()
+    return
+  }
+
+  focusActiveTabFallback()
+}
+
+const closeMenu = () => {
+  emit('close')
+  void nextTick(restoreFocusToTrigger)
+}
+
 /** 菜单项点击：执行回调并关闭菜单 */
 const handleMenuItemClick = (fn?: () => void) => {
   fn?.()
-  emit('close')
+  closeMenu()
+}
+
+const getMenuButtons = (): HTMLButtonElement[] => {
+  const root = menuElementRef.value
+  if (!root) return []
+  return Array.from(root.querySelectorAll<HTMLButtonElement>('[role="menuitem"]')).filter(
+    (button) => !button.disabled
+  )
 }
+
+const focusMenuItem = (index: number) => {
+  const buttons = getMenuButtons()
+  if (buttons.length <= 0) return
+  const safeIndex = (index + buttons.length) % buttons.length
+  buttons[safeIndex]?.focus()
+}
+
+const getFocusedMenuItemIndex = (): number => {
+  const buttons = getMenuButtons()
+  return buttons.findIndex((button) => button === document.activeElement)
+}
+
+const handleMenuKeydown = (event: KeyboardEvent) => {
+  if (event.key === 'Escape') {
+    event.preventDefault()
+    closeMenu()
+    return
+  }
+
+  if (event.key === 'ArrowDown') {
+    event.preventDefault()
+    const focusedIndex = getFocusedMenuItemIndex()
+    focusMenuItem(focusedIndex === -1 ? 0 : focusedIndex + 1)
+    return
+  }
+
+  if (event.key === 'ArrowUp') {
+    event.preventDefault()
+    const focusedIndex = getFocusedMenuItemIndex()
+    focusMenuItem(focusedIndex === -1 ? -1 : focusedIndex - 1)
+    return
+  }
+
+  if (event.key === 'Home') {
+    event.preventDefault()
+    focusMenuItem(0)
+    return
+  }
+
+  if (event.key === 'End') {
+    event.preventDefault()
+    focusMenuItem(getMenuButtons().length - 1)
+  }
+}
+
+const getCustomMenuKey = (item: IContextMenu): string => item.key ?? `${item.title}-${item.icon ?? ''}`
+
 /** 挂载后修正菜单位置，避免超出右边界 */
 onMounted(() => {
   const menuWidth = menuElementRef.value?.clientWidth ?? 0
   if (menuPosition.left + menuWidth > window.innerWidth) {
     menuPosition.left = window.innerWidth - menuWidth - 5
   }
+  focusMenuItem(0)
 })
 </script>
 

package/src/lib/components/PageLoading.vue

@@ -8,34 +8,36 @@
   <div
     v-if="isLoading"
     class="stack-tab-loading-mask"
+    role="status"
+    aria-live="polite"
+    :aria-label="t('VueStackTab.loading')"
     :style="{ zIndex: getMaxZIndex('.cache-page-wrapper *') }"
   >
-    <div class="stack-tab-loading--spin turn" />
+    <div class="stack-tab-loading--spin turn" aria-hidden="true" />
   </div>
 </template>
 <script setup lang="ts">
 import { ref, onUnmounted } from 'vue'
+import { useI18n } from 'vue-i18n-lite'
 import { TabEventType, useTabEmitter } from '../hooks/useTabEventBus'
 import { getMaxZIndex } from '../utils/scrollUtils'
 const props = defineProps<{
   /** 当前标签 id，用于过滤 PAGE_LOADING 事件 */
   tabId: string
 }>()
+const { t } = useI18n()
 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) => {
+const handleLoadingEvent = (payload: { tId: string; value: boolean }) => {
   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)
+emitter.on(TabEventType.PAGE_LOADING, handleLoadingEvent)
 onUnmounted(() => {
-  emitter.off(eventType, handleLoadingEvent as (e: unknown) => void)
+  emitter.off(TabEventType.PAGE_LOADING, handleLoadingEvent)
 })
 </script>
 <style scoped></style>

package/src/lib/components/StackKeepAlive/StackCacheRenderer.vue

@@ -0,0 +1,70 @@
+<!--
+  StackCacheRenderer - 内部缓存组件解析层
+
+  职责：
+  - 接收 router-view slot 提供的 route 与 Component
+  - 仅在 route/component 身份变化时调用 useTabPanel.addPage
+  - 通过 scoped slot 暴露包装组件，确保真正的缓存页仍是 keep-alive 的直接子节点
+
+  注意：
+  - 这是内部组件，暂不从 src/lib/index.ts 导出
+  - 不负责 transition、keep-alive、TabHeader、iframe 或 session 初始化
+-->
+<script lang="ts" setup>
+import { defineComponent, shallowRef, watch } from 'vue'
+import type { DefineComponent, VNode } from 'vue'
+import type { RouteLocationNormalizedLoaded } from 'vue-router'
+import useTabPanel from '../../hooks/useTabPanel'
+
+interface StackCacheRendererProps {
+  route: RouteLocationNormalizedLoaded
+  component?: VNode | null
+}
+
+interface StackCacheRendererSlotProps {
+  wrappedComponent: DefineComponent
+  activeCacheKey: string
+  refreshKey: number
+  activePageRefreshVersion: number
+  component?: VNode | null
+}
+
+const props = defineProps<StackCacheRendererProps>()
+
+defineSlots<{
+  default(props: StackCacheRendererSlotProps): unknown
+}>()
+
+const { refreshKey, activeCacheKey, activePageRefreshVersion, addPage } = useTabPanel()
+
+const EmptyRendererComponent = defineComponent({
+  name: 'StackCacheRendererEmpty',
+  setup() {
+    return () => null
+  }
+}) as DefineComponent
+
+const wrappedComponent = shallowRef<DefineComponent>(EmptyRendererComponent)
+
+const getComponentIdentity = (component?: VNode | null): unknown => {
+  return component?.type ?? component
+}
+
+watch(
+  [() => props.route.fullPath, () => getComponentIdentity(props.component), () => refreshKey.value],
+  () => {
+    wrappedComponent.value = addPage(props.route, props.component)
+  },
+  { immediate: true }
+)
+</script>
+
+<template>
+  <slot
+    :wrapped-component="wrappedComponent"
+    :active-cache-key="activeCacheKey"
+    :refresh-key="refreshKey"
+    :active-page-refresh-version="activePageRefreshVersion"
+    :component="component"
+  />
+</template>

package/src/lib/components/StackKeepAlive/StackKeepAlive.vue

@@ -0,0 +1,57 @@
+<!--
+  StackKeepAlive - 内部页面缓存渲染层
+
+  职责：
+  - 渲染 router-view 当前页面
+  - 维持 transition -> keep-alive -> dynamic component 的原有结构
+  - 通过 StackCacheRenderer 注册并解析栈式缓存页
+  - 将缓存页 on-loaded 事件转发为 loaded
+
+  注意：
+  - 这是内部组件，暂不从 src/lib/index.ts 导出
+  - 不负责 TabHeader、iframe、session 初始化或 openTab/closeTab API
+-->
+<script lang="ts" setup>
+import useTabPanel from '../../hooks/useTabPanel'
+import StackCacheRenderer from './StackCacheRenderer.vue'
+
+interface StackKeepAliveProps {
+  transitionName?: string
+}
+
+withDefaults(defineProps<StackKeepAliveProps>(), {
+  transitionName: 'stack-tab-swap'
+})
+
+const emit = defineEmits<{
+  loaded: []
+}>()
+
+const { caches } = useTabPanel()
+
+/** 页面组件加载完成时向父组件转发 */
+const emitLoaded = () => {
+  emit('loaded')
+}
+</script>
+
+<template>
+  <router-view v-slot="{ Component, route }">
+    <StackCacheRenderer
+      v-slot="{ wrappedComponent, activeCacheKey, activePageRefreshVersion, component }"
+      :route="route"
+      :component="Component"
+    >
+      <transition :name="transitionName" appear mode="out-in">
+        <keep-alive :include="caches">
+          <component
+            :is="wrappedComponent"
+            :key="`${activeCacheKey}-${activePageRefreshVersion}`"
+            :vnode="component"
+            @on-loaded="emitLoaded"
+          />
+        </keep-alive>
+      </transition>
+    </StackCacheRenderer>
+  </router-view>
+</template>

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

@@ -4,24 +4,28 @@
   职责：左右滚动箭头、全屏/还原按钮，支持禁用与阴影样式
 -->
 <template>
-  <div
+  <button
+    type="button"
     class="stack-tab__header-button"
     :class="{
       'stack-tab__shadow-right': shadow === 'right',
       'stack-tab__shadow-left': shadow === 'left'
     }"
-    :disabled="disabled ? 'disabled' : null"
+    :disabled="disabled"
     :title="title"
+    :aria-label="resolvedAriaLabel"
   >
-    <div v-if="!('icon' in $slots)" class="stack-tab__mask-button" :class="iconClass" />
-    <div v-if="'icon' in $slots" class="stack-tab__button">
+    <span v-if="!('icon' in $slots)" class="stack-tab__mask-button" :class="iconClass" />
+    <span v-if="'icon' in $slots" class="stack-tab__button">
       <slot name="icon" />
-    </div>
-  </div>
+    </span>
+  </button>
 </template>
 
 <script lang="ts" setup>
-withDefaults(
+import { computed } from 'vue'
+
+const props = withDefaults(
   defineProps<{
     /** 是否禁用 */
     disabled?: boolean
@@ -31,14 +35,21 @@ withDefaults(
     iconClass?: string
     /** 悬停提示 */
     title?: string
+    /** 辅助技术标签，未传时使用 title */
+    ariaLabel?: string
   }>(),
   {
     disabled: false,
     shadow: null,
     iconClass: '',
-    title: ''
+    title: '',
+    ariaLabel: ''
   }
 )
+
+const resolvedAriaLabel = computed<string>(() => {
+  return props.ariaLabel || props.title
+})
 </script>
 
 <style scoped></style>

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

@@ -1,23 +1,41 @@
 <template>
   <li
     ref="tabElementRef"
+    role="presentation"
     class="stack-tab__item"
     :class="{
       'is-active': item.active,
       'is-icon': item.closable
     }"
-    @click="handleActivate(true)"
+    @click.self="handleActivate(true)"
+    @contextmenu="$emit('contextmenu', $event)"
   >
-    <!--    <div v-if="!!icon" class="stack-tab__item-icon" :class="icon"></div>-->
-    <div class="stack-tab__item-title">
-      <div class="stack-tab__item-title-content" :title="title">
-        {{ title }}
-      </div>
-    </div>
-    <div
+    <button
+      :id="getStackTabTabId(item.id)"
+      type="button"
+      role="tab"
+      class="stack-tab__item-tab"
+      :data-tab-id="item.id"
+      :aria-controls="getStackTabPanelId(item.id)"
+      :aria-selected="item.active ? 'true' : 'false'"
+      :tabindex="item.active ? 0 : -1"
+      :title="title"
+      @click="handleActivate(true)"
+      @keydown="handleTabKeydown"
+    >
+      <span class="stack-tab__item-title">
+        <span class="stack-tab__item-title-content">
+          {{ title }}
+        </span>
+      </span>
+    </button>
+    <button
       v-if="item.closable"
+      type="button"
       class="stack-tab__icon-close-fill stack-tab__item-button"
       :title="t('VueStackTab.close')"
+      :aria-label="`${t('VueStackTab.close')} ${title}`"
+      :tabindex="item.active ? 0 : -1"
       @click.stop="handleClose"
     />
   </li>
@@ -30,10 +48,11 @@
 -->
 <script setup lang="ts">
 import { computed, ref, onUnmounted } from 'vue'
-import type { ITabItem } from '@/lib/model/TabModel'
+import type { ITabItem } from '../../model/TabModel'
 import { TabEventType, useTabEmitter } from '../../hooks/useTabEventBus'
+import { getStackTabPanelId, getStackTabTabId } from '../../utils/stackTabsA11y'
 import { useI18n } from 'vue-i18n-lite'
-const emit = defineEmits(['close', 'active'])
+const emit = defineEmits(['close', 'active', 'contextmenu'])
 const emitter = useTabEmitter()
 const { t } = useI18n()
 /** 当前标签 DOM 元素，用于滚动到可视区域 */
@@ -50,15 +69,12 @@ const handleTabActiveEvent = (payload: TabActivePayload) => {
     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)
+emitter.on(TabEventType.TAB_ACTIVE, handleTabActiveEvent)
 onUnmounted(() => {
-  emitter.off(eventType, handleTabActiveEvent as (e: unknown) => void)
+  emitter.off(TabEventType.TAB_ACTIVE, handleTabActiveEvent)
 })
 /** 显示标题，空时用 i18n 占位 */
-const title = computed<string>(() => {
-  return props.item.title || t('undefined')
-})
+const title = computed<string>(() => props.item.title || t('VueStackTab.undefined'))
 
 /** 关闭按钮点击，向父级 emit close */
 const handleClose = () => {
@@ -68,6 +84,19 @@ const handleClose = () => {
 const handleActivate = (isRoute = true) => {
   emit('active', props.item, tabElementRef.value, isRoute)
 }
+
+const handleTabKeydown = (event: KeyboardEvent) => {
+  if (event.key === 'Enter' || event.key === ' ') {
+    event.preventDefault()
+    handleActivate(true)
+    return
+  }
+
+  if ((event.key === 'Delete' || event.key === 'Backspace') && props.item.closable) {
+    event.preventDefault()
+    handleClose()
+  }
+}
 </script>
 
 <style lang="scss" scoped></style>