FEAT: 调整播放器横向手势语义

echo-loop · echo-loop · commit 187fd4abb730 · 2026-06-22T23:11:02.000+08:00
diff --git a/TASKS.md b/TASKS.md
@@ -1,8 +1,18 @@
 # Echo Loop 任务清单
 
-> 最后更新：2026-06-22（学习版通知提示收敛到逐句精听完成）
+> 最后更新：2026-06-22（Free Player 禁止 tab swipe，逐句精听支持左右滑动切句）
 > 当前焦点：Android 结束录音闪退（离线 ASR / Silero VAD）——**仍未解决**
 
+## 已完成：Free Player 禁止 tab swipe，逐句精听支持左右滑动切句
+
+此前 Free Player 的 `全文 / 收藏` 使用 `TabBarView` 默认横向切页，和产品想要的“横向手势优先用于学习态切句”语义冲突；逐句精听则只有底部上下句按钮，没有对应的左右滑动切句入口。现统一调整为：Free Player 只允许点击 tab 切换，逐句精听支持左右 swipe 切换句子。
+
+- [x] `player_screen.dart`：`TabBarView` 显式禁用横向 swipe，仅保留点击 `TabBar` 切换。
+- [x] `intensive_listen_player_screen.dart`：在主体内容区新增横向手势，左滑下一句、右滑上一句，并补边界防越界处理。
+- [x] 测试：`player_screen_test.dart` 增加“横向滑动不会切 tab”回归；`intensive_listen_player_screen_test.dart` 增加左右滑动切句与首句防越界回归。
+
+  **完成时间**: 2026-06-22 22:09:26 +0800
+
 ## 已完成：学习版通知提示收敛到逐句精听完成
 
 此前“开启通知提醒”的学习版 pre-prompt 同时挂在逐句精听、跟读、盲听、难句补练、复述多个完成页上；任务顺序调整后，用户可能在错误的任务完成点看到提示。现收敛为只在逐句精听完成后直接弹出，其它任务完成页不再主动弹学习版通知提示。
diff --git a/lib/l10n/app_en.arb b/lib/l10n/app_en.arb
@@ -1484,7 +1484,7 @@
   "guideFavoritesSentencesReviewDescription": "Tap here to review every saved sentence at once.",
   "guideFavoritesVocabularyListDescription": "Your saved words and phrases. Expand a card to see definitions and hear how they sound in the original sentences.",
   "guideFavoritesFlashcardDescription": "Tap here to enter flashcard mode and review every saved word. Seeing the word and hearing it in context makes memory stick.",
-  "guideIntensiveListenCantUnderstandDescription": "Tap here when a sentence is hard to follow. It will be auto-marked as difficult and you'll enter single-sentence analysis mode.",
+  "guideIntensiveListenCantUnderstandDescription": "Tap here when a sentence is hard to follow. It will be auto-marked as difficult and you'll enter explanation mode.",
   "guideIntensiveListenAnnotationContinueDescription": "Once you understand this sentence, tap Continue to move on to the next one.",
   "guideIntensiveListenAnnotationPlayDescription": "Tap the play button to play the current sentence.",
   "guideSentenceTileNumberDescription": "Tap the number to play from this sentence.",
diff --git a/lib/l10n/app_localizations.dart b/lib/l10n/app_localizations.dart
@@ -5045,7 +5045,7 @@ abstract class AppLocalizations {
   /// No description provided for @guideIntensiveListenCantUnderstandDescription.
   ///
   /// In en, this message translates to:
-  /// **'Tap here when a sentence is hard to follow. It will be auto-marked as difficult and you\'ll enter single-sentence analysis mode.'**
+  /// **'Tap here when a sentence is hard to follow. It will be auto-marked as difficult and you\'ll enter explanation mode.'**
   String get guideIntensiveListenCantUnderstandDescription;
 
   /// No description provided for @guideIntensiveListenAnnotationContinueDescription.
diff --git a/lib/l10n/app_localizations_en.dart b/lib/l10n/app_localizations_en.dart
@@ -2844,7 +2844,7 @@ class AppLocalizationsEn extends AppLocalizations {
 
   @override
   String get guideIntensiveListenCantUnderstandDescription =>
-      'Tap here when a sentence is hard to follow. It will be auto-marked as difficult and you\'ll enter single-sentence analysis mode.';
+      'Tap here when a sentence is hard to follow. It will be auto-marked as difficult and you\'ll enter explanation mode.';
 
   @override
   String get guideIntensiveListenAnnotationContinueDescription =>
diff --git a/lib/l10n/app_localizations_zh.dart b/lib/l10n/app_localizations_zh.dart
@@ -2743,7 +2743,7 @@ class AppLocalizationsZh extends AppLocalizations {
 
   @override
   String get guideIntensiveListenCantUnderstandDescription =>
-      '遇到听不懂的句子时点这里，会自动标记为难句并进入单句解析模式。';
+      '遇到听不懂的句子时点这里，会自动标记为难句并进入讲解模式。';
 
   @override
   String get guideIntensiveListenAnnotationContinueDescription =>
diff --git a/lib/l10n/app_zh.arb b/lib/l10n/app_zh.arb
@@ -1100,7 +1100,7 @@
   "guideFavoritesSentencesReviewDescription": "点击这里，一键复习所有收藏的句子。",
   "guideFavoritesVocabularyListDescription": "这里是你收藏的单词和意群。展开后可查看释义，也可以收听它们在原句中的发音。",
   "guideFavoritesFlashcardDescription": "点击这里进入闪卡模式，复习所有收藏的词汇。通过看单词、听原句，可以更高效地巩固记忆。",
-  "guideIntensiveListenCantUnderstandDescription": "遇到听不懂的句子时点这里，会自动标记为难句并进入单句解析模式。",
+  "guideIntensiveListenCantUnderstandDescription": "遇到听不懂的句子时点这里，会自动标记为难句并进入讲解模式。",
   "guideIntensiveListenAnnotationContinueDescription": "搞懂这句后点「继续」进入下一句。",
   "guideIntensiveListenAnnotationPlayDescription": "点击播放按钮，播放当前句。",
   "guideSentenceTileNumberDescription": "点击编号从这句开始播放。",
diff --git a/lib/screens/intensive_listen_player_screen.dart b/lib/screens/intensive_listen_player_screen.dart
@@ -887,6 +887,10 @@ bool _isIntensiveMainPlaybackActive(IntensiveListenState state) {
 
 extension on _IntensiveListenPlayerScreenState {
   void _handlePrevious() {
+    final playerState = ref.read(intensiveListenPlayerProvider);
+    if (playerState.currentSentenceIndex <= 0) {
+      return;
+    }
     final player = ref.read(intensiveListenPlayerProvider.notifier);
     unawaited(player.goToPrevious());
   }
diff --git a/lib/screens/player_screen.dart b/lib/screens/player_screen.dart
@@ -26,6 +26,10 @@ import '../widgets/player_hotkey_scope.dart';
 import '../widgets/practice/annotation_content_view.dart';
 import 'sentence_detail_screen.dart';
 
+const kPlayerSingleSentenceSwipeAreaKey = ValueKey(
+  'player-single-sentence-swipe-area',
+);
+
 class PlayerScreen extends ConsumerStatefulWidget {
   const PlayerScreen({super.key});
 
@@ -35,6 +39,12 @@ class PlayerScreen extends ConsumerStatefulWidget {
 
 class _PlayerScreenState extends ConsumerState<PlayerScreen>
     with SingleTickerProviderStateMixin {
+  static const double _singleSentenceSwipeVelocityThreshold = 250;
+  String? _lastSingleSentenceContentId;
+  PlaylistMode? _lastSingleSentencePlaylistMode;
+  int? _lastSingleSentenceIndex;
+  int _singleSentenceTransitionDirection = 0;
+
   late TabController _tabController;
   int _previousTabIndex = 0;
   Duration? _seekPreviewPosition;
@@ -213,6 +223,8 @@ class _PlayerScreenState extends ConsumerState<PlayerScreen>
         Expanded(
           child: TabBarView(
             controller: _tabController,
+            // Free Player 的横向手势保留给学习态切句，这里只允许点 tab 切换。
+            physics: const NeverScrollableScrollPhysics(),
             children: [
               _buildFullTextTab(playerState, controller),
               _buildBookmarkedTab(playerState, controller),
@@ -398,78 +410,187 @@ class _PlayerScreenState extends ConsumerState<PlayerScreen>
     if (audioItem == null) {
       return const SizedBox.shrink();
     }
+    final contentId = '${playerState.playlistMode.name}-$index';
+    if (_lastSingleSentenceContentId != contentId) {
+      if (_lastSingleSentencePlaylistMode == playerState.playlistMode &&
+          _lastSingleSentenceIndex != null) {
+        final previousIndex = _lastSingleSentenceIndex!;
+        _singleSentenceTransitionDirection = index > previousIndex
+            ? 1
+            : index < previousIndex
+            ? -1
+            : 0;
+      } else {
+        _singleSentenceTransitionDirection = 0;
+      }
+      _lastSingleSentenceContentId = contentId;
+      _lastSingleSentencePlaylistMode = playerState.playlistMode;
+      _lastSingleSentenceIndex = index;
+    }
 
-    return Padding(
-      padding: const EdgeInsets.symmetric(horizontal: AppSpacing.l),
-      child: Column(
-        crossAxisAlignment: CrossAxisAlignment.stretch,
-        children: [
-          // 序号 + 时间区间（弱化辅助信息）
-          Padding(
-            padding: const EdgeInsets.only(
-              top: AppSpacing.m,
-              bottom: AppSpacing.s,
+    return GestureDetector(
+      key: kPlayerSingleSentenceSwipeAreaKey,
+      behavior: HitTestBehavior.translucent,
+      onHorizontalDragEnd: (details) =>
+          _handleSingleSentenceSwipe(details, playerState, controller),
+      child: Padding(
+        padding: const EdgeInsets.symmetric(horizontal: AppSpacing.l),
+        child: Column(
+          crossAxisAlignment: CrossAxisAlignment.stretch,
+          children: [
+            // 序号 + 时间区间（弱化辅助信息）
+            Padding(
+              padding: const EdgeInsets.only(
+                top: AppSpacing.m,
+                bottom: AppSpacing.s,
+              ),
+              child: Row(
+                children: [
+                  Text(
+                    '#${currentSentence.index + 1}',
+                    style: AppTextStyles.caption(context),
+                  ),
+                  const SizedBox(width: AppSpacing.l),
+                  Text(
+                    '${SubtitleParser.formatDuration(currentSentence.startTime)} - ${SubtitleParser.formatDuration(currentSentence.endTime)}',
+                    style: AppTextStyles.caption(context),
+                  ),
+                ],
+              ),
             ),
-            child: Row(
-              children: [
-                Text(
-                  '#${currentSentence.index + 1}',
-                  style: AppTextStyles.caption(context),
-                ),
-                const SizedBox(width: AppSpacing.l),
-                Text(
-                  '${SubtitleParser.formatDuration(currentSentence.startTime)} - ${SubtitleParser.formatDuration(currentSentence.endTime)}',
-                  style: AppTextStyles.caption(context),
-                ),
-              ],
+            // 难句标记行（复用精听）—— 不被遮蔽，盲听时仍可标记
+            BookmarkToggleRow(
+              isDifficult: isBookmarked,
+              onTap: () => controller.toggleBookmark(currentSentence.index),
             ),
-          ),
-          // 难句标记行（复用精听）—— 不被遮蔽，盲听时仍可标记
-          BookmarkToggleRow(
-            isDifficult: isBookmarked,
-            onTap: () => controller.toggleBookmark(currentSentence.index),
-          ),
-          const SizedBox(height: AppSpacing.m),
-          // 精听解析内容 + 隐藏字幕遮罩
-          Expanded(
-            child: Stack(
-              children: [
-                AnnotationContentView(
-                  // 切句时重建，确保 AnnotationContentView 内部意群等状态重置
-                  key: ValueKey(currentSentence.index),
-                  text: currentSentence.text,
-                  aiNotifier: ref.read(sentenceAiNotifierProvider),
-                  audioItemId: audioItem.id,
-                  sentenceIndex: currentSentence.index,
-                  sentenceStartMs: currentSentence.startTime.inMilliseconds,
-                  sentenceEndMs: currentSentence.endTime.inMilliseconds,
-                  // 意群试听与主播放共用引擎，播放前先暂停主播放
-                  onStopMainPlayer: () => controller.pause(),
+            const SizedBox(height: AppSpacing.m),
+            // 精听解析内容 + 隐藏字幕遮罩。切句时做轻量滑动过渡，降低跳变感。
+            Expanded(
+              child: AnimatedSwitcher(
+                duration: const Duration(milliseconds: 220),
+                switchInCurve: Curves.easeOutCubic,
+                switchOutCurve: Curves.easeOutCubic,
+                layoutBuilder: (currentChild, previousChildren) => Stack(
+                  fit: StackFit.expand,
+                  children: [
+                    ...previousChildren,
+                    if (currentChild != null) currentChild,
+                  ],
                 ),
-                // 隐藏字幕遮罩：覆盖整个内容区（含工具栏），模糊且不可点击
-                if (!settings.showTranscript)
-                  Positioned.fill(
-                    child: IgnorePointer(
-                      child: ClipRRect(
-                        child: BackdropFilter(
-                          filter: ImageFilter.blur(sigmaX: 5, sigmaY: 5),
-                          child: Container(
-                            color: Theme.of(
-                              context,
-                            ).colorScheme.onSurface.withValues(alpha: 0.05),
+                transitionBuilder: (child, animation) {
+                  final page = child is _SingleSentenceAnimatedPage
+                      ? child
+                      : _SingleSentenceAnimatedPage(
+                          direction: 0,
+                          child: child,
+                        );
+                  final beginOffset = switch (page.direction) {
+                    1 => const Offset(0.1, 0),
+                    -1 => const Offset(-0.1, 0),
+                    _ => const Offset(0, 0),
+                  };
+                  return FadeTransition(
+                    opacity: animation,
+                    child: SlideTransition(
+                      position:
+                          Tween<Offset>(
+                            begin: beginOffset,
+                            end: Offset.zero,
+                          ).animate(
+                            CurvedAnimation(
+                              parent: animation,
+                              curve: Curves.easeOutCubic,
+                            ),
                           ),
-                        ),
-                      ),
+                      child: page.child,
                     ),
+                  );
+                },
+                child: _SingleSentenceAnimatedPage(
+                  key: ValueKey(contentId),
+                  direction: _singleSentenceTransitionDirection,
+                  child: Stack(
+                    children: [
+                      AnnotationContentView(
+                        // 切句时重建，确保 AnnotationContentView 内部意群等状态重置
+                        key: ValueKey(currentSentence.index),
+                        text: currentSentence.text,
+                        aiNotifier: ref.read(sentenceAiNotifierProvider),
+                        audioItemId: audioItem.id,
+                        sentenceIndex: currentSentence.index,
+                        sentenceStartMs: currentSentence.startTime.inMilliseconds,
+                        sentenceEndMs: currentSentence.endTime.inMilliseconds,
+                        // 意群试听与主播放共用引擎，播放前先暂停主播放
+                        onStopMainPlayer: () => controller.pause(),
+                      ),
+                      // 隐藏字幕遮罩：覆盖整个内容区（含工具栏），模糊且不可点击
+                      if (!settings.showTranscript)
+                        Positioned.fill(
+                          child: IgnorePointer(
+                            child: ClipRRect(
+                              child: BackdropFilter(
+                                filter: ImageFilter.blur(sigmaX: 5, sigmaY: 5),
+                                child: Container(
+                                  color: Theme.of(context).colorScheme.onSurface
+                                      .withValues(alpha: 0.05),
+                                ),
+                              ),
+                            ),
+                          ),
+                        ),
+                    ],
                   ),
-              ],
+                ),
+              ),
             ),
-          ),
-        ],
+          ],
+        ),
       ),
     );
   }
 
+  void _handleSingleSentenceSwipe(
+    DragEndDetails details,
+    ListeningPracticeState playerState,
+    ListeningPractice controller,
+  ) {
+    final velocity = details.primaryVelocity ?? 0;
+    if (velocity.abs() < _singleSentenceSwipeVelocityThreshold) {
+      return;
+    }
+    if (velocity < 0) {
+      if (playerState.playlistMode == PlaylistMode.bookmarks) {
+        final currentIndex = playerState.currentBookmarkIndex;
+        final bookmarked = playerState.bookmarkedSentences;
+        final currentPos = currentIndex == null
+            ? -1
+            : bookmarked.indexWhere((s) => s.index == currentIndex);
+        if (currentPos >= bookmarked.length - 1) {
+          return;
+        }
+      } else if ((playerState.currentFullIndex ?? 0) >=
+          playerState.sentences.length - 1) {
+        return;
+      }
+      unawaited(controller.nextSentence());
+      return;
+    }
+
+    if (playerState.playlistMode == PlaylistMode.bookmarks) {
+      final currentIndex = playerState.currentBookmarkIndex;
+      final bookmarked = playerState.bookmarkedSentences;
+      final currentPos = currentIndex == null
+          ? -1
+          : bookmarked.indexWhere((s) => s.index == currentIndex);
+      if (currentPos <= 0) {
+        return;
+      }
+    } else if ((playerState.currentFullIndex ?? 0) <= 0) {
+      return;
+    }
+    unawaited(controller.previousSentence());
+  }
+
   /// 点击句子主体 → 暂停播放 → 进入句子讲解页
   ///
   /// 与盲听任务行为一致：导航前停止音频，返回后同步收藏状态。
@@ -708,6 +829,20 @@ class _PlayerScreenState extends ConsumerState<PlayerScreen>
   }
 }
 
+class _SingleSentenceAnimatedPage extends StatelessWidget {
+  final int direction;
+  final Widget child;
+
+  const _SingleSentenceAnimatedPage({
+    super.key,
+    required this.direction,
+    required this.child,
+  });
+
+  @override
+  Widget build(BuildContext context) => child;
+}
+
 class _HotkeyTipsCarousel extends StatefulWidget {
   final AppLocalizations l10n;
 
diff --git a/test/screens/intensive_listen_player_screen_test.dart b/test/screens/intensive_listen_player_screen_test.dart
diff --git a/test/screens/player_screen_test.dart b/test/screens/player_screen_test.dart
diff --git a/test/screens/review_difficult_practice_screen_test.dart b/test/screens/review_difficult_practice_screen_test.dart
diff --git a/test/services/storage_service_test.dart b/test/services/storage_service_test.dart
