feat: implement Ctrl+C subtitle copy with lightweight toast notification (#140)

* feat(player): add subtitle copy shortcut with Ctrl+C

- Add copy_subtitle shortcut to constants with CommandOrControl+C
- Implement copy functionality in usePlayerShortcuts hook
- Support copying selected text or current subtitle based on display mode
- Add success/error notifications for copy operations
- Remove obsolete keyboard handling from SubtitleContent component
- Add i18n label support for copy_subtitle shortcut

* fix(player): enable text selection in subtitle tokens for copy functionality

- Change WordToken user-select from 'none' to 'text' to allow native text selection
- Add debug logging to copy function to help diagnose selection issues
- This enables Ctrl+C to copy selected subtitle text properly

* fix(player): use custom subtitle selection for copy functionality

- Use selectedText from useSubtitleOverlayUI instead of window.getSelection()
- Integrate with custom selection system used by SubtitleContent component
- Restore WordToken user-select: none to maintain custom selection behavior
- Update copy logic to properly detect custom selected text vs full subtitle
- Remove window.getSelection() debugging code as it's no longer used

* debug: add logging to copy function to diagnose selectedText state

* feat(player): add DOM-based selected text detection for copy

- Add fallback to DOM query when selectedText state is empty
- Check for selected tokens by background color style
- Maintains both state-based and DOM-based selection detection
- This should fix the issue where selectedText state gets cleared before copy

* simplify: remove word selection feature, keep only full subtitle copy

- Remove all selected text detection logic (selectedText state and DOM queries)
- Simplify copy function to only copy current subtitle based on display mode
- Remove dependency on useSubtitleOverlayUI hook
- Clean up notification message to show copied character count
- This makes the copy functionality simple and reliable

* feat(player): add lightweight toast notifications for subtitle copy

- Add Ctrl+C shortcut to copy current subtitle based on display mode
- Replace intrusive NotificationService with lightweight toast positioned above subtitle overlay
- Implement custom event system for decoupled toast communication between components
- Add i18n support for copy success/failure messages in zh-cn.json
- Toast automatically hides after 2 seconds with smooth fade transition
- Support copying original, translated, or bilingual subtitle content based on current display mode
- Position toast relative to subtitle overlay for better UX during immersive video watching

This improves user experience by providing non-intrusive feedback while maintaining
clean component architecture and supporting internationalization.

* Update src/renderer/src/pages/player/components/SubtitleOverlay.tsx

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

* Update src/renderer/src/pages/player/components/SubtitleOverlay.tsx

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

* Update src/renderer/src/pages/player/components/SubtitleOverlay.tsx

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

* 📝 Add docstrings to `copy-subtitle-shortcut` (#142)

Docstrings generation was requested by @mkdir700.

* #140 (comment)

The following files were modified:

* `src/renderer/src/pages/player/hooks/usePlayerShortcuts.ts`

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

* Update

* refactor: use design tokens in Toast components and add theming best practices

- Replace hardcoded values with design tokens in ToastContainer and ToastContent
- Use ANIMATION_DURATION, EASING, FONT_SIZES, FONT_WEIGHTS, SPACING, Z_INDEX, GLASS_EFFECT tokens
- Reduce toast display duration from 2000ms to 800ms for better UX
- Add comprehensive theming best practices to CLAUDE.md
- Document mixed approach: CSS variables for theme-related properties, JS variables for design constants

---------

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

Author: mkdir700

CLAUDE.md

@@ -10,6 +10,44 @@
 - 在布局实现上，后续优先使用 flex 布局（尽量避免使用 grid 作为默认方案）。
 - 项目优先使用 antd 组件库，如果组件可以被 antd 复用则优先使用 antd 而不是自定义开发
 
+## 主题变量使用最佳实践
+
+项目启用了 Ant Design 的 CSS 变量模式 (`cssVar: true`)，在 styled-components 中应采用分类使用策略：
+
+### 使用 CSS 变量的场景（主题相关属性）：
+
+- 颜色系统：`var(--ant-color-bg-elevated, fallback)`
+- 阴影效果：`var(--ant-box-shadow-secondary, fallback)`
+- 主题切换时会发生变化的属性
+
+### 使用 JS 变量的场景（设计系统常量）：
+
+- 尺寸间距：`${SPACING.XS}px`、`${BORDER_RADIUS.SM}px`
+- 动画配置：`${ANIMATION_DURATION.SLOW}`、`${EASING.APPLE}`
+- 层级关系：`${Z_INDEX.MODAL}`
+- 字体配置：`${FONT_SIZES.SM}px`、`${FONT_WEIGHTS.MEDIUM}`
+- 毛玻璃效果：`${GLASS_EFFECT.BACKGROUND_ALPHA.LIGHT}`
+
+### 推荐模式：
+
+```typescript
+const StyledComponent = styled.div`
+  /* 主题相关：使用 CSS 变量 */
+  background: var(--ant-color-bg-elevated, rgba(0, 0, 0, ${GLASS_EFFECT.BACKGROUND_ALPHA.LIGHT}));
+  color: var(--ant-color-white, #ffffff);
+  box-shadow: var(--ant-box-shadow-secondary, ${SHADOWS.SM});
+
+  /* 设计系统常量：使用 JS 变量 */
+  padding: ${SPACING.XS}px ${SPACING.MD}px;
+  border-radius: ${BORDER_RADIUS.SM}px;
+  font-size: ${FONT_SIZES.SM}px;
+  transition: opacity ${ANIMATION_DURATION.SLOW} ${EASING.APPLE};
+  z-index: ${Z_INDEX.MODAL};
+`
+```
+
+这种混合模式既保持了类型安全和构建时优化，又支持主题的运行时切换，是当前架构下的最佳实践。
+
 # State Management
 
 - 项目使用 Zustand 作为状态管理库，配合 Immer 中间件支持不可变状态更新，使用自定义的中间件栈包含持久化、DevTools 和订阅选择器功能

src/renderer/src/i18n/label.ts

@@ -179,7 +179,8 @@ const shortcutKeys = [
   'subtitle_mode_none',
   'subtitle_mode_original',
   'subtitle_mode_translated',
-  'subtitle_mode_bilingual'
+  'subtitle_mode_bilingual',
+  'copy_subtitle'
 ] as const
 
 const shortcutKeyMap = shortcutKeys.reduce(

src/renderer/src/i18n/locales/zh-cn.json

@@ -106,6 +106,10 @@
       "fullscreen": {
         "enter": "全屏",
         "exit": "退出全屏"
+      },
+      "copy": {
+        "success": "已复制",
+        "failed": "复制失败，无法访问剪贴板"
       }
     },
     "subtitles": {
@@ -290,6 +294,7 @@
       "clear_shortcut": "清除快捷键",
       "clear_topic": "清空消息",
       "copy_last_message": "复制上一条消息",
+      "copy_subtitle": "复制字幕",
       "enabled": "启用",
       "escape_fullscreen": "退出全屏",
       "exit_fullscreen": "退出全屏",

src/renderer/src/infrastructure/constants/shortcuts.const.ts

@@ -130,5 +130,12 @@ export const DEFAULT_SHORTCUTS: Shortcut[] = [
     editable: true,
     enabled: true,
     system: false
+  },
+  {
+    key: 'copy_subtitle',
+    shortcut: ['CommandOrControl', 'C'],
+    editable: true,
+    enabled: true,
+    system: false
   }
 ]

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

@@ -235,26 +235,6 @@ export const SubtitleContent = memo(function SubtitleContent({
     return undefined
   }, [selectionState.startIndex, selectionState.endIndex, handleGlobalClick])
 
-  // === 键盘复制支持 ===
-  const handleKeyDown = useCallback((e: React.KeyboardEvent) => {
-    if ((e.ctrlKey || e.metaKey) && e.key === 'c') {
-      const selection = window.getSelection()
-      const selectedText = selection?.toString()
-
-      if (selectedText) {
-        // 复制到剪贴板
-        navigator.clipboard
-          .writeText(selectedText)
-          .then(() => {
-            logger.info('字幕文本已复制到剪贴板', { length: selectedText.length })
-          })
-          .catch((error) => {
-            logger.error('复制到剪贴板失败', { error })
-          })
-      }
-    }
-  }, [])
-
   // === 渲染分词文本 ===
   const renderTokenizedText = useCallback(
     (tokens: WordToken[]) => {
@@ -366,8 +346,6 @@ export const SubtitleContent = memo(function SubtitleContent({
       ref={containerRef}
       className={className}
       style={style}
-      onKeyDown={handleKeyDown}
-      tabIndex={0} // 使元素可聚焦，支持键盘操作
       role="region"
       data-testid="subtitle-content"
     >

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

@@ -11,10 +11,21 @@
  */
 
 import { loggerService } from '@logger'
+import {
+  ANIMATION_DURATION,
+  BORDER_RADIUS,
+  EASING,
+  FONT_SIZES,
+  FONT_WEIGHTS,
+  GLASS_EFFECT,
+  SHADOWS,
+  SPACING,
+  Z_INDEX
+} from '@renderer/infrastructure/styles/theme'
 import { usePlayerStore } from '@renderer/state'
 import { SubtitleBackgroundType, SubtitleDisplayMode } from '@types'
 import { Tooltip } from 'antd'
-import React, { memo, useCallback, useEffect, useMemo, useRef } from 'react'
+import React, { memo, useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import { useTranslation } from 'react-i18next'
 import styled, { css } from 'styled-components'
 
@@ -70,6 +81,37 @@ export const SubtitleOverlay = memo(function SubtitleOverlay({
 
   // === 本地状态 ===
   const overlayRef = useRef<HTMLDivElement>(null)
+  const [toastVisible, setToastVisible] = useState(false)
+  const [toastMessage, setToastMessage] = useState('')
+  const hideToastTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+
+  // === 复制成功toast监听器 ===
+  useEffect(() => {
+    const handleSubtitleCopied = (event: CustomEvent<{ message: string }>) => {
+      const { message } = event.detail
+      setToastMessage(message)
+      setToastVisible(true)
+
+      // 2秒后自动隐藏toast（防抖）
+      if (hideToastTimerRef.current) {
+        clearTimeout(hideToastTimerRef.current)
+      }
+      hideToastTimerRef.current = setTimeout(() => {
+        setToastVisible(false)
+        hideToastTimerRef.current = null
+      }, 800)
+    }
+
+    window.addEventListener('subtitle-copied', handleSubtitleCopied as EventListener)
+
+    return () => {
+      if (hideToastTimerRef.current) {
+        clearTimeout(hideToastTimerRef.current)
+        hideToastTimerRef.current = null
+      }
+      window.removeEventListener('subtitle-copied', handleSubtitleCopied as EventListener)
+    }
+  }, [])
 
   // === 初始化和容器边界更新 ===
   useEffect(() => {
@@ -434,6 +476,10 @@ export const SubtitleOverlay = memo(function SubtitleOverlay({
           data-testid="subtitle-resize-handle"
         />
       </Tooltip>
+
+      <ToastContainer $visible={toastVisible} role="status" aria-live="polite" aria-atomic="true">
+        <ToastContent>{toastMessage}</ToastContent>
+      </ToastContainer>
     </OverlayContainer>
   )
 })
@@ -569,3 +615,28 @@ const ResizeHandle = styled.div<{ $visible: boolean }>`
     box-shadow: 0 2px 8px rgba(102, 126, 234, 0.4);
   }
 `
+
+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`
+  background: rgba(0, 0, 0, ${GLASS_EFFECT.BACKGROUND_ALPHA.LIGHT});
+  color: #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 rgba(255, 255, 255, ${GLASS_EFFECT.BORDER_ALPHA.SUBTLE});
+  box-shadow: ${SHADOWS.SM};
+`

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

@@ -2,16 +2,99 @@ import { loggerService } from '@logger'
 import { useShortcut } from '@renderer/infrastructure/hooks/useShortcut'
 import { usePlayerStore } from '@renderer/state/stores/player.store'
 import { SubtitleDisplayMode } from '@types'
+import { useCallback } from 'react'
+import { useTranslation } from 'react-i18next'
 
 import { usePlayerCommands } from './usePlayerCommands'
 import useSubtitleOverlay from './useSubtitleOverlay'
 
 const logger = loggerService.withContext('TransportBar')
 
+/**
+ * Registers global keyboard shortcuts for player controls and subtitle-related actions.
+ *
+ * Sets up shortcuts for playback (play/pause, seek, volume, loop), subtitle navigation
+ * (previous/next, replay), subtitle display mode toggles (none/original/translated/bilingual),
+ * subtitle panel toggle, cycling favorite playback rates, and copying the current subtitle to the clipboard.
+ *
+ * The copy action selects text according to the current subtitle display mode:
+ * - ORIGINAL: original text
+ * - TRANSLATED: translated text, falling back to original if missing
+ * - BILINGUAL: original and translated joined by a newline
+ * - NONE or unsupported: no copy performed
+ *
+ * Side effects:
+ * - Invokes player command functions and store actions.
+ * - Writes subtitle text to the clipboard via `navigator.clipboard.writeText`.
+ * - Emits a `CustomEvent` named `subtitle-copied` with a localized success or failure message.
+ * - Logs informational and error events via the module logger.
+ */
 export function usePlayerShortcuts() {
+  const { t } = useTranslation()
   const cmd = usePlayerCommands()
-  const { setDisplayMode } = useSubtitleOverlay()
+  const { setDisplayMode, currentSubtitle } = useSubtitleOverlay()
   const { toggleSubtitlePanel, cycleFavoriteRateNext, cycleFavoriteRatePrev } = usePlayerStore()
+  const displayMode = usePlayerStore((s) => s.subtitleOverlay.displayMode)
+
+  // 复制字幕内容处理函数
+  const handleCopySubtitle = useCallback(async () => {
+    try {
+      let textToCopy = ''
+
+      if (currentSubtitle) {
+        // 根据显示模式复制相应的字幕内容
+        switch (displayMode) {
+          case SubtitleDisplayMode.ORIGINAL:
+            textToCopy = currentSubtitle.originalText
+            break
+          case SubtitleDisplayMode.TRANSLATED:
+            textToCopy = currentSubtitle.translatedText || currentSubtitle.originalText
+            break
+          case SubtitleDisplayMode.BILINGUAL: {
+            const texts = [currentSubtitle.originalText, currentSubtitle.translatedText].filter(
+              Boolean
+            )
+            textToCopy = texts.join('\n')
+            break
+          }
+          default:
+            logger.warn('当前显示模式不支持复制')
+            return // NONE 模式不复制
+        }
+        logger.info('复制字幕内容', {
+          mode: displayMode,
+          length: textToCopy.length
+        })
+      } else {
+        logger.warn('没有当前字幕内容')
+        return
+      }
+
+      if (textToCopy) {
+        await navigator.clipboard.writeText(textToCopy)
+
+        // 触发自定义事件显示toast
+        window.dispatchEvent(
+          new CustomEvent('subtitle-copied', {
+            detail: {
+              message: t('player.controls.copy.success')
+            }
+          })
+        )
+      }
+    } catch (error) {
+      logger.error('复制字幕失败', { error })
+
+      // 错误情况下也使用toast显示
+      window.dispatchEvent(
+        new CustomEvent('subtitle-copied', {
+          detail: {
+            message: t('player.controls.copy.failed')
+          }
+        })
+      )
+    }
+  }, [currentSubtitle, displayMode, t])
 
   useShortcut('play_pause', () => {
     cmd.playPause()
@@ -87,4 +170,9 @@ export function usePlayerShortcuts() {
     cycleFavoriteRatePrev()
     logger.info('播放速度切换: 上一个常用速度')
   })
+
+  // 复制字幕内容
+  useShortcut('copy_subtitle', () => {
+    handleCopySubtitle()
+  })
 }