refactor(player/subtitle): comprehensive subtitle overlay improvements

src/renderer/src/pages/player/components/SubtitleResizeHandle.tsx

@@ -0,0 +1,96 @@
+/**
+ * SubtitleResizeHandle Component
+ *
+ * 独立的调整尺寸句柄组件：
+ * - 只在遮罩模式下渲染
+ * - 包含 Tooltip
+ * - 处理鼠标事件
+ * - 包含样式定义
+ * - 支持主题变量适配
+ */
+
+import { ANIMATION_DURATION, EASING } from '@renderer/infrastructure/styles/theme'
+import { Tooltip } from 'antd'
+import React, { memo } from 'react'
+import { useTranslation } from 'react-i18next'
+import styled from 'styled-components'
+
+export interface SubtitleResizeHandleProps {
+  /** 句柄是否可见 */
+  visible: boolean
+  /** 鼠标按下事件处理 */
+  onMouseDown: (event: React.MouseEvent) => void
+  /** 双击事件处理 */
+  onDoubleClick: (event: React.MouseEvent) => void
+  /** 自定义 className */
+  className?: string
+  /** 测试 ID */
+  testId?: string
+}
+
+/**
+ * 调整尺寸句柄组件
+ */
+export const SubtitleResizeHandle = memo(function SubtitleResizeHandle({
+  visible,
+  onMouseDown,
+  onDoubleClick,
+  className,
+  testId = 'subtitle-resize-handle'
+}: SubtitleResizeHandleProps) {
+  const { t } = useTranslation()
+
+  if (!visible) {
+    return null
+  }
+
+  return (
+    <Tooltip
+      title={t('settings.playback.subtitle.overlay.resizeHandle.tooltip')}
+      placement="top"
+      mouseEnterDelay={0.5}
+      mouseLeaveDelay={0}
+    >
+      <ResizeHandle
+        className={className}
+        $visible={visible}
+        onMouseDown={onMouseDown}
+        onDoubleClick={onDoubleClick}
+        data-testid={testId}
+      />
+    </Tooltip>
+  )
+})
+
+export default SubtitleResizeHandle
+
+// === 样式组件 ===
+
+const ResizeHandle = styled.div<{ $visible: boolean }>`
+  position: absolute;
+  bottom: -4px;
+  right: -4px;
+  width: 12px;
+  height: 12px;
+
+  /* 使用主题变量支持主题切换 */
+  background: var(--ant-color-primary, rgba(102, 126, 234, 0.8));
+  border: 2px solid var(--ant-color-white, rgba(255, 255, 255, 0.9));
+  border-radius: 50%;
+  cursor: nw-resize;
+
+  opacity: ${(props) => (props.$visible ? 1 : 0)};
+  transition: all ${ANIMATION_DURATION.MEDIUM} ${EASING.STANDARD};
+
+  &:hover {
+    background: var(--ant-color-primary-hover, var(--ant-color-primary));
+    transform: scale(1.2);
+
+    /* 使用主题变量 */
+    box-shadow: var(--ant-box-shadow-secondary, 0 2px 8px rgba(102, 126, 234, 0.4));
+  }
+
+  &:active {
+    transform: scale(1.1);
+  }
+`

src/renderer/src/pages/player/components/SubtitleToast.tsx

@@ -0,0 +1,79 @@
+/**
+ * SubtitleToast Component
+ *
+ * 独立的 Toast 通知组件：
+ * - 接收 visible 和 message props
+ * - 包含样式组件定义
+ * - 支持自动隐藏逻辑
+ * - 使用主题变量适配深色/浅色模式
+ */
+
+import {
+  ANIMATION_DURATION,
+  BORDER_RADIUS,
+  EASING,
+  FONT_SIZES,
+  FONT_WEIGHTS,
+  GLASS_EFFECT,
+  SHADOWS,
+  SPACING,
+  Z_INDEX
+} from '@renderer/infrastructure/styles/theme'
+import { memo } from 'react'
+import styled from 'styled-components'
+
+export interface SubtitleToastProps {
+  /** Toast 是否可见 */
+  visible: boolean
+  /** Toast 消息内容 */
+  message: string
+  /** 自动隐藏延迟时间（毫秒），0 表示不自动隐藏 */
+  autoHideDelay?: number
+  /** onAutoHide?: () => void - 可选的自动隐藏回调 */
+}
+
+/**
+ * Toast 通知组件
+ */
+export const SubtitleToast = memo(function SubtitleToast({ visible, message }: SubtitleToastProps) {
+  if (!visible || !message) {
+    return null
+  }
+
+  return (
+    <ToastContainer $visible={visible} role="status" aria-live="polite" aria-atomic="true">
+      <ToastContent>{message}</ToastContent>
+    </ToastContainer>
+  )
+})
+
+export default SubtitleToast
+
+// === 样式组件 ===
+
+const ToastContainer = styled.div<{ $visible: boolean }>`
+  position: absolute;
+  top: -40px;
+  left: 50%;
+  transform: translateX(-50%);
+  opacity: ${(props) => (props.$visible ? 1 : 0)};
+  visibility: ${(props) => (props.$visible ? 'visible' : 'hidden')};
+  transition: opacity ${ANIMATION_DURATION.SLOW} ${EASING.APPLE};
+  z-index: ${Z_INDEX.MODAL};
+  pointer-events: none;
+`
+
+const ToastContent = styled.div`
+  /* 使用 CSS 变量支持主题切换 */
+  background: var(--ant-color-bg-elevated, rgba(0, 0, 0, ${GLASS_EFFECT.BACKGROUND_ALPHA.LIGHT}));
+  color: var(--ant-color-text, #ffffff);
+  padding: ${SPACING.XS}px ${SPACING.MD}px;
+  border-radius: ${BORDER_RADIUS.SM}px;
+  font-size: ${FONT_SIZES.SM}px;
+  font-weight: ${FONT_WEIGHTS.MEDIUM};
+  white-space: nowrap;
+  backdrop-filter: blur(${GLASS_EFFECT.BLUR_STRENGTH.SUBTLE}px);
+  border: 1px solid
+    var(--ant-color-border, rgba(255, 255, 255, ${GLASS_EFFECT.BORDER_ALPHA.SUBTLE}));
+  box-shadow: var(--ant-box-shadow-secondary, ${SHADOWS.SM});
+`

src/renderer/src/pages/player/components/index.ts

@@ -11,6 +11,8 @@ export { default as SettingsPopover } from './SettingsPopover'
 export { default as SubtitleContent } from './SubtitleContent'
 export { default as SubtitleListPanel } from './SubtitleListPanel'
 export { default as SubtitleOverlay } from './SubtitleOverlay'
+export { default as SubtitleResizeHandle } from './SubtitleResizeHandle'
+export { default as SubtitleToast } from './SubtitleToast'
 export { default as SubtitleTrackSelector } from './SubtitleTrackSelector'
 export { default as VideoErrorRecovery } from './VideoErrorRecovery'
 export { default as VideoSurface } from './VideoSurface'

src/renderer/src/pages/player/hooks/index.ts

@@ -1,4 +1,9 @@
+export { useContainerBounds } from './useContainerBounds'
+export { useContentWidth } from './useContentWidth'
+export { useMaskViewport } from './useMaskViewport'
 export { usePlayerEngine } from './usePlayerEngine'
+export { useSubtitleDrag } from './useSubtitleDrag'
 export { useSubtitleEngine } from './useSubtitleEngine'
 export { useSubtitleOverlay } from './useSubtitleOverlay'
 export { useSubtitleOverlayUI } from './useSubtitleOverlayUI'
+export { useSubtitleResize } from './useSubtitleResize'

src/renderer/src/pages/player/hooks/useContainerBounds.ts

@@ -0,0 +1,165 @@
+/**
+ * useContainerBounds Hook
+ *
+ * 管理容器尺寸变化和冲突检测：
+ * - 容器边界更新
+ * - ResizeObserver 监听
+ * - 冲突区域检测
+ * - 智能避让逻辑
+ */
+
+import { SubtitleDisplayMode } from '@types'
+import { useCallback, useEffect } from 'react'
+
+export interface ConflictArea {
+  x: number
+  y: number
+  width: number
+  height: number
+}
+
+export interface UseContainerBoundsOptions {
+  containerRef?: React.RefObject<HTMLElement | null>
+  displayMode: SubtitleDisplayMode
+  currentConfig?: { isInitialized?: boolean }
+  updateContainerBounds: (bounds: { width: number; height: number }) => void
+  adaptToContainerResize: (bounds: { width: number; height: number }) => void
+  avoidCollision: (conflicts: ConflictArea[]) => void
+}
+
+export function useContainerBounds({
+  containerRef,
+  displayMode,
+  currentConfig,
+  updateContainerBounds,
+  adaptToContainerResize,
+  avoidCollision
+}: UseContainerBoundsOptions) {
+  // === 容器边界更新 ===
+  useEffect(() => {
+    let resizeTimer: NodeJS.Timeout
+
+    const updateBounds = (isInitial = false) => {
+      const container =
+        containerRef?.current || document.querySelector('[data-testid="video-surface"]')
+      if (container) {
+        const rect = container.getBoundingClientRect()
+        const newBounds = { width: rect.width, height: rect.height }
+
+        if (isInitial || !currentConfig?.isInitialized) {
+          // 初始化时使用 updateContainerBounds
+          updateContainerBounds(newBounds)
+        } else {
+          // 容器尺寸变化时使用智能适应
+          adaptToContainerResize(newBounds)
+        }
+      }
+    }
+
+    const handleResize = () => {
+      // 防抖处理，避免频繁重新计算
+      clearTimeout(resizeTimer)
+      resizeTimer = setTimeout(() => updateBounds(false), 150)
+    }
+
+    // 初始化
+    updateBounds(true)
+
+    // 监听窗口尺寸变化
+    window.addEventListener('resize', handleResize)
+
+    // 监听全屏模式变化（可能导致容器尺寸变化）
+    let observer: ResizeObserver | null = null
+
+    if (typeof ResizeObserver !== 'undefined') {
+      observer = new ResizeObserver((entries) => {
+        for (const entry of entries) {
+          if (
+            entry.target ===
+            (containerRef?.current || document.querySelector('[data-testid="video-surface"]'))
+          ) {
+            handleResize()
+          }
+        }
+      })
+
+      const container =
+        containerRef?.current || document.querySelector('[data-testid="video-surface"]')
+      if (container) {
+        observer.observe(container)
+      }
+    }
+
+    return () => {
+      clearTimeout(resizeTimer)
+      window.removeEventListener('resize', handleResize)
+      if (observer && typeof observer.disconnect === 'function') {
+        observer.disconnect()
+      }
+    }
+  }, [containerRef, updateContainerBounds, adaptToContainerResize, currentConfig?.isInitialized])
+
+  // === 冲突区域检测 ===
+  const detectConflictAreas = useCallback((): ConflictArea[] => {
+    const conflictSelectors = [
+      '[data-testid="controller-panel"]',
+      '[data-testid="transport-bar"]',
+      '[aria-label="transport-bar"]',
+      '.progress-section',
+      '.controller-panel'
+    ]
+
+    const conflictAreas: ConflictArea[] = []
+    const container =
+      containerRef?.current || document.querySelector('[data-testid="video-surface"]')
+
+    if (!container) return conflictAreas
+
+    const containerRect = container.getBoundingClientRect()
+
+    conflictSelectors.forEach((selector) => {
+      const element = document.querySelector(selector) as HTMLElement
+      if (element && element.offsetParent) {
+        // 确保元素可见
+        const rect = element.getBoundingClientRect()
+
+        // 转换为相对于容器的百分比坐标
+        const relativeArea = {
+          x: ((rect.left - containerRect.left) / containerRect.width) * 100,
+          y: ((rect.top - containerRect.top) / containerRect.height) * 100,
+          width: (rect.width / containerRect.width) * 100,
+          height: (rect.height / containerRect.height) * 100
+        }
+
+        // 只关注可能与字幕区域重叠的元素
+        if (relativeArea.y > 50) {
+          // 只检测下半部分
+          conflictAreas.push(relativeArea)
+        }
+      }
+    })
+
+    return conflictAreas
+  }, [containerRef])
+
+  // === 智能冲突检测 ===
+  useEffect(() => {
+    // 定期检测冲突区域（UI 元素可能动态显示/隐藏）
+    const conflictCheckTimer = setInterval(() => {
+      if (displayMode !== SubtitleDisplayMode.NONE) {
+        const conflicts = detectConflictAreas()
+        if (conflicts.length > 0) {
+          avoidCollision(conflicts)
+        }
+      }
+    }, 2000) // 每 2 秒检测一次
+
+    return () => {
+      clearInterval(conflictCheckTimer)
+    }
+  }, [detectConflictAreas, displayMode, avoidCollision])
+
+  return {
+    detectConflictAreas
+  }
+}

src/renderer/src/pages/player/hooks/useContentWidth.ts

@@ -0,0 +1,33 @@
+/**
+ * useContentWidth Hook
+ *
+ * 采用 YouTube 风格的字幕宽度控制方案：
+ * - 使用 CSS 的 max-content (fit-content) 让内容自然决定宽度
+ * - 通过 max-width 限制最大宽度为 95%
+ * - 完全由 CSS 处理，无需 JavaScript 计算
+ *
+ * 优势：
+ * - ✅ 零 JavaScript 计算开销
+ * - ✅ 无渲染闪烁
+ * - ✅ 单行内容：容器宽度 = 内容宽度
+ * - ✅ 多行内容：容器宽度 = 95%（自动换行）
+ */
+
+export interface UseContentWidthOptions {
+  /** 容器最大宽度百分比 */
+  maxContainerWidthPercent?: number
+}
+
+export const useContentWidth = ({ maxContainerWidthPercent = 95 }: UseContentWidthOptions) => {
+  // 返回固定的 CSS 宽度策略
+  // width: max-content 让容器完全根据内容宽度扩展（不提前换行）
+  // max-width: 95% 限制最大宽度
+  // 当内容超过 max-width 时，容器会被限制，内容自然换行
+  const widthStyle = 'max-content'
+  const maxWidthStyle = `${maxContainerWidthPercent}%`
+
+  return {
+    widthStyle,
+    maxWidthStyle
+  }
+}