feat(shell): overlay tooltips for AppBar (#1183)

Author: Simon-He95

electron.vite.config.ts

@@ -102,6 +102,7 @@ export default defineConfig({
       rollupOptions: {
         input: {
           shell: resolve('src/renderer/shell/index.html'),
+          shellTooltipOverlay: resolve('src/renderer/shell/tooltip-overlay/index.html'),
           index: resolve('src/renderer/index.html'),
           floating: resolve('src/renderer/floating/index.html'),
           splash: resolve('src/renderer/splash/index.html'),

src/main/presenter/windowPresenter/index.ts

@@ -40,6 +40,8 @@ export class WindowPresenter implements IWindowPresenter {
   >()
   private floatingChatWindow: FloatingChatWindow | null = null
   private settingsWindow: BrowserWindow | null = null
+  private tooltipOverlayWindows = new Map<number, BrowserWindow>()
+  private pendingTooltipPayload = new Map<number, { x: number; y: number; text: string }>()
 
   constructor(configPresenter: IConfigPresenter) {
     this.windows = new Map()
@@ -66,6 +68,44 @@ export class WindowPresenter implements IWindowPresenter {
       }
     })
 
+    ipcMain.on(
+      'shell-tooltip:show',
+      (event, payload: { x: number; y: number; text: string } | undefined) => {
+        if (!payload) return
+
+        const parentWindow = BrowserWindow.fromWebContents(event.sender)
+        if (!parentWindow || parentWindow.isDestroyed()) return
+
+        const overlay = this.getOrCreateTooltipOverlay(parentWindow)
+        if (!overlay) return
+
+        this.pendingTooltipPayload.set(parentWindow.id, payload)
+
+        if (!overlay.webContents.isLoadingMainFrame()) {
+          overlay.webContents.send('shell-tooltip-overlay:show', payload)
+          return
+        }
+
+        overlay.webContents.once('did-finish-load', () => {
+          const pending = this.pendingTooltipPayload.get(parentWindow.id)
+          if (!pending) return
+          if (overlay.isDestroyed()) return
+          overlay.webContents.send('shell-tooltip-overlay:show', pending)
+        })
+      }
+    )
+
+    ipcMain.on('shell-tooltip:hide', (event) => {
+      const parentWindow = BrowserWindow.fromWebContents(event.sender)
+      if (!parentWindow || parentWindow.isDestroyed()) return
+
+      const overlay = this.tooltipOverlayWindows.get(parentWindow.id)
+      if (!overlay || overlay.isDestroyed()) return
+
+      this.pendingTooltipPayload.delete(parentWindow.id)
+      overlay.webContents.send('shell-tooltip-overlay:hide')
+    })
+
     // Listen for shortcut event: create new window
     eventBus.on(SHORTCUT_EVENTS.CREATE_NEW_WINDOW, () => {
       console.log('Creating new shell window via shortcut.')
@@ -734,6 +774,7 @@ export class WindowPresenter implements IWindowPresenter {
       if (!shellWindow.isDestroyed()) {
         shellWindow.webContents.send('window-blurred', windowId)
       }
+      this.clearTooltipOverlay(windowId)
     })
 
     // 窗口最大化
@@ -881,6 +922,7 @@ export class WindowPresenter implements IWindowPresenter {
       this.windowFocusStates.delete(windowIdBeingClosed)
       shellWindowState.unmanage() // 停止管理窗口状态
       eventBus.sendToMain(WINDOW_EVENTS.WINDOW_CLOSED, windowIdBeingClosed)
+      this.destroyTooltipOverlay(windowIdBeingClosed)
       console.log(
         `Window ${windowIdBeingClosed} closed event handled. Map size AFTER delete: ${this.windows.size}`
       )
@@ -911,6 +953,12 @@ export class WindowPresenter implements IWindowPresenter {
       shellWindow.loadFile(join(__dirname, '../renderer/shell/index.html'))
     }
 
+    // Pre-create tooltip overlay so first hover is instant
+    shellWindow.webContents.once('did-finish-load', () => {
+      if (shellWindow.isDestroyed()) return
+      this.getOrCreateTooltipOverlay(shellWindow)
+    })
+
     // --- 处理初始标签页创建或激活 ---
 
     // 如果提供了 options?.initialTab，等待窗口加载完成，然后创建新标签页
@@ -982,6 +1030,117 @@ export class WindowPresenter implements IWindowPresenter {
     return windowId // 返回新创建窗口的 ID
   }
 
+  private getOrCreateTooltipOverlay(parentWindow: BrowserWindow): BrowserWindow | null {
+    if (parentWindow.isDestroyed()) return null
+
+    const existing = this.tooltipOverlayWindows.get(parentWindow.id)
+    if (existing && !existing.isDestroyed()) {
+      this.syncTooltipOverlayBounds(parentWindow, existing)
+      if (!existing.isVisible()) {
+        existing.showInactive()
+      }
+      return existing
+    }
+
+    const bounds = parentWindow.getContentBounds()
+
+    const overlay = new BrowserWindow({
+      x: bounds.x,
+      y: bounds.y,
+      width: bounds.width,
+      height: bounds.height,
+      parent: parentWindow,
+      show: false,
+      frame: false,
+      transparent: true,
+      backgroundColor: '#00000000',
+      resizable: false,
+      movable: false,
+      minimizable: false,
+      maximizable: false,
+      closable: false,
+      hasShadow: false,
+      focusable: false,
+      skipTaskbar: true,
+      autoHideMenuBar: true,
+      webPreferences: {
+        preload: join(__dirname, '../preload/index.mjs'),
+        sandbox: false,
+        devTools: is.dev
+      }
+    })
+
+    overlay.setIgnoreMouseEvents(true, { forward: true })
+
+    const sync = () => {
+      const current = this.tooltipOverlayWindows.get(parentWindow.id)
+      if (!current || current.isDestroyed() || parentWindow.isDestroyed()) return
+      this.syncTooltipOverlayBounds(parentWindow, current)
+    }
+
+    parentWindow.on('move', sync)
+    parentWindow.on('resize', sync)
+    parentWindow.on('show', () => {
+      if (!overlay.isDestroyed()) overlay.showInactive()
+    })
+    parentWindow.on('hide', () => {
+      if (!overlay.isDestroyed()) overlay.hide()
+    })
+    parentWindow.on('minimize', () => {
+      if (!overlay.isDestroyed()) overlay.hide()
+    })
+    parentWindow.on('restore', () => {
+      if (!overlay.isDestroyed()) overlay.showInactive()
+    })
+
+    overlay.on('closed', () => {
+      this.tooltipOverlayWindows.delete(parentWindow.id)
+      this.pendingTooltipPayload.delete(parentWindow.id)
+    })
+
+    if (is.dev && process.env['ELECTRON_RENDERER_URL']) {
+      overlay.loadURL(process.env['ELECTRON_RENDERER_URL'] + '/shell/tooltip-overlay/index.html')
+    } else {
+      overlay.loadFile(join(__dirname, '../renderer/shell/tooltip-overlay/index.html'))
+    }
+
+    overlay.webContents.once('did-finish-load', () => {
+      if (overlay.isDestroyed()) return
+      overlay.showInactive()
+      overlay.webContents.send('shell-tooltip-overlay:clear')
+
+      const pending = this.pendingTooltipPayload.get(parentWindow.id)
+      if (pending) {
+        overlay.webContents.send('shell-tooltip-overlay:show', pending)
+      }
+    })
+
+    this.tooltipOverlayWindows.set(parentWindow.id, overlay)
+    return overlay
+  }
+
+  private syncTooltipOverlayBounds(parentWindow: BrowserWindow, overlay: BrowserWindow): void {
+    if (parentWindow.isDestroyed() || overlay.isDestroyed()) return
+    const bounds = parentWindow.getContentBounds()
+    overlay.setBounds(bounds)
+  }
+
+  private clearTooltipOverlay(windowId: number): void {
+    const overlay = this.tooltipOverlayWindows.get(windowId)
+    if (!overlay || overlay.isDestroyed()) return
+    this.pendingTooltipPayload.delete(windowId)
+    overlay.webContents.send('shell-tooltip-overlay:hide')
+  }
+
+  private destroyTooltipOverlay(windowId: number): void {
+    const overlay = this.tooltipOverlayWindows.get(windowId)
+    if (overlay && !overlay.isDestroyed()) {
+      overlay.destroy()
+    }
+    this.tooltipOverlayWindows.delete(windowId)
+    this.pendingTooltipPayload.delete(windowId)
+  }
+
   /**
    * 更新指定窗口的内容保护设置。
    * @param window BrowserWindow 实例。

src/renderer/shell/components/AppBar.vue

@@ -18,6 +18,8 @@
         variant="ghost"
         class="window-no-drag-region shrink-0 w-10 bg-transparent shadow-none rounded-none hover:bg-card/80 text-xs font-medium text-foreground flex items-center justify-center transition-all duration-200 group border-r border-border"
         @click="scrollTabContainer('left')"
+        @mouseenter="onOverlayMouseEnter('scroll-left', t('common.scrollLeft'), $event)"
+        @mouseleave="onOverlayMouseLeave('scroll-left')"
       >
         <Icon icon="lucide:chevron-left" class="w-4 h-4" />
       </Button>
@@ -26,6 +28,8 @@
         variant="ghost"
         class="window-no-drag-region shrink-0 w-10 bg-transparent shadow-none rounded-none hover:bg-card/80 text-xs font-medium text-foreground flex items-center justify-center transition-all duration-200 group border-border"
         @click="scrollTabContainer('right')"
+        @mouseenter="onOverlayMouseEnter('scroll-right', t('common.scrollRight'), $event)"
+        @mouseleave="onOverlayMouseLeave('scroll-right')"
       >
         <Icon icon="lucide:chevron-right" class="w-4 h-4" />
       </Button>
@@ -51,6 +55,8 @@
             @close="tabStore.removeTab(tab.id)"
             @dragstart="onTabDragStart(tab.id, $event)"
             @dragover="onTabItemDragOver(idx, $event)"
+            @mouseenter="onTabMouseEnter(tab, $event)"
+            @mouseleave="onTabMouseLeave(tab.id)"
           >
             <img src="@/assets/logo.png" class="w-4 h-4 mr-2 rounded-sm" />
             <span class="truncate">{{ tab.title ?? 'DeepChat' }}</span>
@@ -69,6 +75,8 @@
         size="icon"
         class="window-no-drag-region shrink-0 w-10 bg-transparent shadow-none rounded-none hover:bg-card/80 text-xs font-medium text-foreground flex items-center justify-center transition-all duration-200 group"
         @click="onNewTabClick"
+        @mouseenter="onOverlayMouseEnter('new-tab', t('common.newTab'), $event)"
+        @mouseleave="onOverlayMouseLeave('new-tab')"
       >
         <Icon icon="lucide:plus" class="w-4 h-4" />
       </Button>
@@ -78,27 +86,41 @@
         size="icon"
         class="window-no-drag-region shrink-0 w-10 bg-transparent shadow-none rounded-none hover:bg-card/80 text-xs font-medium text-foreground flex items-center justify-center transition-all duration-200 group border-l"
         @click="onHistoryClick"
+        @mouseenter="onOverlayMouseEnter('history', t('common.history'), $event)"
+        @mouseleave="onOverlayMouseLeave('history')"
       >
         <Icon icon="lucide:history" class="w-4 h-4" />
       </Button>
       <Button
         size="icon"
         class="window-no-drag-region shrink-0 w-10 bg-transparent shadow-none rounded-none hover:bg-card/80 text-xs font-medium text-foreground flex items-center justify-center transition-all duration-200 group border-l"
         @click="openSettings"
+        @mouseenter="onOverlayMouseEnter('settings', t('routes.settings'), $event)"
+        @mouseleave="onOverlayMouseLeave('settings')"
       >
         <Icon icon="lucide:ellipsis" class="w-4 h-4" />
       </Button>
       <Button
         v-if="!isMacOS"
         class="window-no-drag-region shrink-0 w-12 bg-transparent shadow-none rounded-none hover:bg-card/80 text-xs font-medium text-foreground flex items-center justify-center transition-all duration-200 group border-l"
         @click="minimizeWindow"
+        @mouseenter="onOverlayMouseEnter('minimize', t('common.minimize'), $event)"
+        @mouseleave="onOverlayMouseLeave('minimize')"
       >
         <MinimizeIcon class="h-3! w-3!" />
       </Button>
       <Button
         v-if="!isMacOS"
         class="window-no-drag-region shrink-0 w-12 bg-transparent shadow-none rounded-none hover:bg-card/80 text-xs font-medium text-foreground flex items-center justify-center transition-all duration-200 group"
         @click="toggleMaximize"
+        @mouseenter="
+          onOverlayMouseEnter(
+            'toggle-maximize',
+            isMaximized ? t('common.restore') : t('common.maximize'),
+            $event
+          )
+        "
+        @mouseleave="onOverlayMouseLeave('toggle-maximize')"
       >
         <MaximizeIcon v-if="!isMaximized" class="h-3! w-3!" />
         <RestoreIcon v-else class="h-3! w-3!" />
@@ -107,6 +129,8 @@
         v-if="!isMacOS"
         class="window-no-drag-region shrink-0 w-12 bg-transparent shadow-none rounded-none hover:bg-red-700/80 hover:text-white text-xs font-medium text-foreground flex items-center justify-center transition-all duration-200 group"
         @click="closeWindow"
+        @mouseenter="onOverlayMouseEnter('close-window', t('common.close'), $event)"
+        @mouseleave="onOverlayMouseLeave('close-window')"
       >
         <CloseIcon class="h-3! w-3!" />
       </Button>
@@ -123,7 +147,7 @@
 </template>
 
 <script setup lang="ts">
-import { ref, onMounted, nextTick, computed } from 'vue'
+import { ref, onMounted, onBeforeUnmount, nextTick, computed } from 'vue'
 import MaximizeIcon from './icons/MaximizeIcon.vue'
 import RestoreIcon from './icons/RestoreIcon.vue'
 import { usePresenter } from '@/composables/usePresenter'
@@ -160,13 +184,76 @@ let draggedTabId: number | null = null
 const dragInsertIndex = ref(-1)
 const dragInsertPosition = ref(0)
 
+type TooltipHoverTarget = { key: string; text: string; el: HTMLElement }
+
+const hoveredTarget = ref<TooltipHoverTarget | null>(null)
+const isTooltipOpen = ref(false)
+let tooltipTimer: number | null = null
+
 const tabContainerWrapperSize = useElementSize(tabContainerWrapper)
 const tabContainerSize = useElementSize(tabContainer)
 const tabContainerWrapperScrollLeft = ref(0)
 
+const sendTooltipShow = (el: HTMLElement, text: string) => {
+  const rect = el.getBoundingClientRect()
+  ipcRenderer.send('shell-tooltip:show', {
+    x: rect.left + rect.width / 2,
+    y: rect.bottom + 8,
+    text
+  })
+}
+
+const hideTooltip = () => {
+  isTooltipOpen.value = false
+  ipcRenderer.send('shell-tooltip:hide')
+}
+
+const updateTooltipPosition = () => {
+  if (!isTooltipOpen.value) return
+  const current = hoveredTarget.value
+  if (!current) return
+  sendTooltipShow(current.el, current.text)
+}
+
+const onOverlayMouseEnter = (key: string, text: string, event: MouseEvent) => {
+  if (tooltipTimer != null) window.clearTimeout(tooltipTimer)
+
+  const el = event.currentTarget as HTMLElement | null
+  if (!el) return
+
+  hoveredTarget.value = { key, el, text }
+
+  tooltipTimer = window.setTimeout(() => {
+    if (!hoveredTarget.value || hoveredTarget.value.key !== key) return
+    isTooltipOpen.value = true
+    updateTooltipPosition()
+  }, 200)
+}
+
+const onOverlayMouseLeave = (key: string) => {
+  if (tooltipTimer != null) {
+    window.clearTimeout(tooltipTimer)
+    tooltipTimer = null
+  }
+
+  if (hoveredTarget.value && hoveredTarget.value.key === key) {
+    hoveredTarget.value = null
+    hideTooltip()
+  }
+}
+
+const onTabMouseEnter = (tab: { id: number; title?: string | null }, event: MouseEvent) => {
+  onOverlayMouseEnter(`tab:${tab.id}`, tab.title ?? 'DeepChat', event)
+}
+
+const onTabMouseLeave = (tabId: number) => {
+  onOverlayMouseLeave(`tab:${tabId}`)
+}
+
 const onTabContainerWrapperScroll = () => {
   requestAnimationFrame(() => {
     tabContainerWrapperScrollLeft.value = tabContainerWrapper.value?.scrollLeft ?? 0
+    updateTooltipPosition()
   })
 }
 
@@ -486,6 +573,12 @@ onMounted(() => {
 
   window.addEventListener('dragover', handleDragOver)
   window.addEventListener('dragend', handleDragEnd)
+  window.addEventListener('resize', updateTooltipPosition)
+})
+
+onBeforeUnmount(() => {
+  window.removeEventListener('resize', updateTooltipPosition)
+  hideTooltip()
 })
 
 const isPlaygroundEnabled = import.meta.env.VITE_ENABLE_PLAYGROUND === 'true'