feat(player): 进度条拖动预览改用雪碧图

lib/pages/player/player_logic.dart

@@ -149,6 +149,7 @@ class PlayerLogic extends ChangeNotifier {
   Episode displayEpisode(Drama drama, Episode fallback) {
     final number = pickedEpisode[drama.id];
     if (number == null) return fallback;
+    if (fallback.number == number) return fallback;
     for (final episode in drama.episodes) {
       if (episode.number == number) return episode;
     }
@@ -438,6 +439,7 @@ class PlayerLogic extends ChangeNotifier {
           ticket.playUrl,
           likeCount: ticket.likeCount,
           commentCount: ticket.commentCount,
+          thumbnailsUrl: ticket.thumbnailsUrl,
         );
         return true;
       }

lib/pages/player/player_view.dart

@@ -14,6 +14,7 @@ import '../../core/data/services/download_controller.dart';
 import '../../core/data/services/interaction_controller.dart';
 import '../../core/data/services/playback_position_cache.dart';
 import '../../core/data/services/playback_session.dart';
+import '../../core/data/services/sprite_thumbnail_axis.dart';
 import '../../core/data/services/playback_thumbnail_service.dart';
 import '../../core/data/services/video_player_port.dart';
 import '../../core/data/services/wallet_controller.dart';
@@ -106,6 +107,7 @@ class _PlayerPageState extends State<PlayerPage>
     with WidgetsBindingObserver, RouteAware {
   late final PlayerLogic logic;
   late final PlaybackThumbnailService _thumbnailService;
+  late final SpriteThumbnailAxisService _spriteAxisService;
   PageRoute<dynamic>? _subscribedRoute;
   bool _chromeVisible = true;
   double _playbackSpeed = 1.0;
@@ -131,6 +133,7 @@ class _PlayerPageState extends State<PlayerPage>
     _thumbnailService = PlaybackThumbnailService(
       sourceResolver: _resolveThumbnailSource,
     );
+    _spriteAxisService = SpriteThumbnailAxisService();
     WidgetsBinding.instance.addObserver(this);
     logic.start(
       factory: context.read<PlayerFactory>(),
@@ -247,6 +250,7 @@ class _PlayerPageState extends State<PlayerPage>
   void dispose() {
     WidgetsBinding.instance.removeObserver(this);
     appRouteObserver.unsubscribe(this);
+    _spriteAxisService.dispose();
     _thumbnailService.dispose();
     logic.dispose();
     super.dispose();
@@ -422,9 +426,12 @@ class _PlayerPageState extends State<PlayerPage>
     final l10n = AppLocalizations.of(context)!;
     final entry = logic.queue.entryAt(index);
     final drama = entry.drama;
-    final episode = widget.homeMode
-        ? logic.displayEpisode(drama, entry.episode)
+    final sessionEpisode = index >= 0 && index < logic.sessionEpisodes.length
+        ? logic.sessionEpisodes[index]
         : entry.episode;
+    final episode = widget.homeMode
+        ? logic.displayEpisode(drama, sessionEpisode)
+        : sessionEpisode;
     final selected = index == logic.session.currentIndex;
     // Selection changes before the prepared slot is promoted. Use its controller
     // throughout the handoff instead of briefly falling back to a placeholder.
@@ -435,6 +442,14 @@ class _PlayerPageState extends State<PlayerPage>
     final ready = videoPort?.controller.value.isInitialized ?? false;
     final theater = logic.pip || logic.pipPreparing;
     final locked = logic.session.isLocked || episode.locked;
+    if (selected && ready) {
+      unawaited(
+        _spriteAxisService.prepareAt(
+          episode.thumbnailsUrl,
+          videoPort!.controller.value.position,
+        ),
+      );
+    }
 
     return Stack(
       fit: StackFit.expand,
@@ -606,6 +621,7 @@ class _PlayerPageState extends State<PlayerPage>
                 ? (position) => logic.seekTo(context, videoPort!, position)
                 : null,
             thumbnailService: _thumbnailService,
+            spriteAxisService: _spriteAxisService,
           )
         else
           PlayerPlaybackOverlay(
@@ -629,6 +645,7 @@ class _PlayerPageState extends State<PlayerPage>
               totalEpisodes: logic.visibleIndices.length,
               boosting: _boosting,
               thumbnailService: _thumbnailService,
+              spriteAxisService: _spriteAxisService,
             ),
             actions: PlayerOverlayActions(
               onBack: widget.embedded

lib/pages/player/widgets/home_feed_overlay.dart

@@ -8,6 +8,7 @@ import 'package:video_player/video_player.dart';
 
 import '../../../core/data/models/drama.dart';
 import '../../../core/data/services/playback_thumbnail_service.dart';
+import '../../../core/data/services/sprite_thumbnail_axis.dart';
 import '../../../core/formatting/count_format.dart';
 import '../../../core/formatting/localized_content.dart';
 import '../../../core/theme/app_colors.dart';
@@ -63,6 +64,7 @@ class HomeFeedOverlay extends StatefulWidget {
     this.onScrubStart,
     this.onSeek,
     this.thumbnailService,
+    this.spriteAxisService,
   });
 
   final AppLocalizations l10n;
@@ -91,6 +93,7 @@ class HomeFeedOverlay extends StatefulWidget {
   final VoidCallback? onScrubStart;
   final ValueChanged<Duration>? onSeek;
   final PlaybackThumbnailService? thumbnailService;
+  final SpriteThumbnailAxisService? spriteAxisService;
 
   @override
   State<HomeFeedOverlay> createState() => _HomeFeedOverlayState();
@@ -405,6 +408,8 @@ class _HomeFeedOverlayState extends State<HomeFeedOverlay> {
                 onScrubStart: widget.onScrubStart,
                 onSeek: widget.onSeek,
                 thumbnailService: widget.thumbnailService,
+                spriteAxisService: widget.spriteAxisService,
+                thumbnailsUrl: widget.episode.thumbnailsUrl,
                 episodeId: widget.episode.id,
                 posterUrl: widget.drama.posterUrl,
               ),

lib/pages/player/widgets/home_feed_overlay_parts.dart

@@ -18,6 +18,8 @@ class _FeedProgressBar extends StatefulWidget {
     this.onScrubStart,
     this.onSeek,
     this.thumbnailService,
+    this.spriteAxisService,
+    this.thumbnailsUrl,
     required this.episodeId,
     required this.posterUrl,
   });
@@ -29,6 +31,8 @@ class _FeedProgressBar extends StatefulWidget {
   final VoidCallback? onScrubStart;
   final ValueChanged<Duration>? onSeek;
   final PlaybackThumbnailService? thumbnailService;
+  final SpriteThumbnailAxisService? spriteAxisService;
+  final String? thumbnailsUrl;
   final String episodeId;
   final String posterUrl;
 
@@ -148,6 +152,8 @@ class _FeedProgressBarState extends State<_FeedProgressBar> {
                   bottom: widget.hitHeight + 8,
                   child: ScrubPreviewCard(
                     service: widget.thumbnailService!,
+                    spriteAxisService: widget.spriteAxisService,
+                    thumbnailsUrl: widget.thumbnailsUrl,
                     episodeId: widget.episodeId,
                     posterUrl: widget.posterUrl,
                     position: previewPosition,

lib/pages/player/widgets/player_overlay.dart

@@ -266,6 +266,8 @@ class PlayerPlaybackOverlay extends StatelessWidget {
         compact: true,
         locked: data.locked,
         thumbnailService: data.thumbnailService,
+        spriteAxisService: data.spriteAxisService,
+        thumbnailsUrl: data.episode.thumbnailsUrl,
         episodeId: data.episode.id,
         posterUrl: data.drama.posterUrl,
         inactiveTrackColor: Colors.white24,

lib/pages/player/widgets/player_overlay_models.dart

@@ -5,6 +5,7 @@ import 'package:video_player/video_player.dart';
 
 import '../../../core/data/models/drama.dart';
 import '../../../core/data/services/playback_thumbnail_service.dart';
+import '../../../core/data/services/sprite_thumbnail_axis.dart';
 import '../../../l10n/app_localizations.dart';
 
 /// 播放浮层展示数据。
@@ -26,6 +27,7 @@ class PlayerOverlayData {
     required this.boosting,
     required this.locked,
     this.thumbnailService,
+    this.spriteAxisService,
     this.authorNote = '',
   });
 
@@ -73,6 +75,7 @@ class PlayerOverlayData {
 
   /// 拖动进度时按当前集和时间点取帧。
   final PlaybackThumbnailService? thumbnailService;
+  final SpriteThumbnailAxisService? spriteAxisService;
 
   /// 作者声明；没有后端字段时为空。
   final String authorNote;

lib/pages/player/widgets/scrub_preview_card.dart

@@ -2,10 +2,12 @@
 
 import 'dart:async';
 import 'dart:typed_data';
+import 'dart:ui' as ui;
 
 import 'package:flutter/material.dart';
 
 import '../../../core/data/services/playback_thumbnail_service.dart';
+import '../../../core/data/services/sprite_thumbnail_axis.dart';
 import '../../../core/theme/app_colors.dart';
 import '../../../core/widgets/remote_image.dart';
 
@@ -36,9 +38,13 @@ class ScrubPreviewCard extends StatefulWidget {
     required this.posterUrl,
     required this.position,
     required this.duration,
+    this.spriteAxisService,
+    this.thumbnailsUrl,
   });
 
   final PlaybackThumbnailService service;
+  final SpriteThumbnailAxisSource? spriteAxisService;
+  final String? thumbnailsUrl;
   final String episodeId;
   final String posterUrl;
   final Duration position;
@@ -49,50 +55,109 @@ class ScrubPreviewCard extends StatefulWidget {
 }
 
 class _ScrubPreviewCardState extends State<ScrubPreviewCard> {
-  ByteData? _frame;
+  ByteData? _fallbackFrame;
   int _requestSerial = 0;
   int? _requestedBucket;
+  String? _requestedEpisodeId;
 
   @override
   void initState() {
     super.initState();
-    _requestFrame();
+    widget.spriteAxisService?.addListener(_handleSpriteAxisChanged);
+    _syncFallbackSource();
   }
 
   @override
   void didUpdateWidget(covariant ScrubPreviewCard oldWidget) {
     super.didUpdateWidget(oldWidget);
-    final bucket = playbackThumbnailBucket(widget.position);
+    if (oldWidget.spriteAxisService != widget.spriteAxisService) {
+      oldWidget.spriteAxisService?.removeListener(_handleSpriteAxisChanged);
+      widget.spriteAxisService?.addListener(_handleSpriteAxisChanged);
+    }
     if (oldWidget.service != widget.service ||
         oldWidget.episodeId != widget.episodeId ||
-        _requestedBucket != bucket) {
-      _frame = null;
-      _requestFrame();
-    } else {
-      // 同 bucket 内继续拖动时不重复取帧，但会重置 120ms 预取停顿计时。
+        oldWidget.thumbnailsUrl != widget.thumbnailsUrl) {
+      _resetFallback();
+      _syncFallbackSource();
+      return;
+    }
+    if (_requestedBucket != playbackThumbnailBucket(widget.position)) {
+      _fallbackFrame = null;
+      _syncFallbackSource();
+    } else if (_fallbackFrame != null || _shouldUseLocalFallback()) {
       unawaited(widget.service.thumbnail(widget.episodeId, widget.position));
     }
   }
 
   @override
   void dispose() {
+    widget.spriteAxisService?.removeListener(_handleSpriteAxisChanged);
     _requestSerial++;
+    widget.service.cancelPending();
     super.dispose();
   }
 
-  void _requestFrame() {
+  void _handleSpriteAxisChanged() {
+    if (!mounted) return;
+    if (_spriteFrame != null) {
+      widget.service.cancelPending();
+    }
+    setState(() {});
+    _syncFallbackSource();
+  }
+
+  SpriteThumbnailFrame? get _spriteFrame => widget.spriteAxisService
+      ?.cachedFrameAt(widget.thumbnailsUrl, widget.position);
+
+  bool _shouldUseLocalFallback() {
+    if (_spriteFrame != null) return false;
+    final url = widget.thumbnailsUrl?.trim() ?? '';
+    if (url.isEmpty || widget.spriteAxisService == null) return true;
+    return widget.spriteAxisService!.hasAxis(widget.thumbnailsUrl);
+  }
+
+  void _syncFallbackSource() {
+    if (_spriteFrame != null) {
+      widget.service.cancelPending();
+      return;
+    }
+    if (!_shouldUseLocalFallback()) return;
+    _requestFallbackFrame();
+  }
+
+  void _requestFallbackFrame() {
     final bucket = playbackThumbnailBucket(widget.position);
+    if (_requestedBucket == bucket &&
+        _requestedEpisodeId == widget.episodeId &&
+        (_fallbackFrame != null || _requestSerial > 0)) {
+      return;
+    }
     _requestedBucket = bucket;
+    _requestedEpisodeId = widget.episodeId;
     final serial = ++_requestSerial;
-    final future = widget.service.thumbnail(widget.episodeId, widget.position);
-    future.then((frame) {
-      if (!mounted || serial != _requestSerial) return;
-      setState(() => _frame = frame);
+    widget.service.thumbnail(widget.episodeId, widget.position).then((frame) {
+      if (!mounted || serial != _requestSerial || _spriteFrame != null) return;
+      setState(() => _fallbackFrame = frame);
     });
   }
 
+  void _resetFallback() {
+    widget.service.cancelPending();
+    _fallbackFrame = null;
+    _requestedBucket = null;
+    _requestedEpisodeId = null;
+    _requestSerial++;
+  }
+
   @override
   Widget build(BuildContext context) {
+    final spriteFrame = _spriteFrame;
+    final stage = decideScrubPreviewStage(
+      hasThumbnailsUrl: (widget.thumbnailsUrl?.trim().isNotEmpty ?? false),
+      hasSpriteFrame: spriteFrame != null,
+      hasAxis: widget.spriteAxisService?.hasAxis(widget.thumbnailsUrl) ?? false,
+      hasLocalFrame: _fallbackFrame != null,
+    );
     return Container(
       key: const Key('scrub-preview-card'),
       width: scrubPreviewWidth,
@@ -135,11 +200,18 @@ class _ScrubPreviewCardState extends State<ScrubPreviewCard> {
                     fit: BoxFit.cover,
                     fallbackColor: AppColors.bar,
                   ),
-                  if (_frame case final frame?)
+                  if (stage == ScrubPreviewStage.sprite && spriteFrame != null)
+                    SpriteCropPreview(
+                      key: const Key('scrub-preview-sprite'),
+                      image: spriteFrame.image,
+                      sourceRect: spriteFrame.sourceRect,
+                    ),
+                  if (stage == ScrubPreviewStage.localFrame &&
+                      _fallbackFrame != null)
                     Image.memory(
-                      frame.buffer.asUint8List(
-                        frame.offsetInBytes,
-                        frame.lengthInBytes,
+                      _fallbackFrame!.buffer.asUint8List(
+                        _fallbackFrame!.offsetInBytes,
+                        _fallbackFrame!.lengthInBytes,
                       ),
                       key: const Key('scrub-preview-frame'),
                       fit: BoxFit.cover,
@@ -157,6 +229,61 @@ class _ScrubPreviewCardState extends State<ScrubPreviewCard> {
   }
 }
 
+/// 对已解码 sprite 做 sourceRect 裁剪，不触发再次解码。
+class SpriteCropPreview extends StatelessWidget {
+  const SpriteCropPreview({
+    super.key,
+    required this.image,
+    required this.sourceRect,
+  });
+
+  final ui.Image image;
+  final ui.Rect sourceRect;
+
+  @override
+  Widget build(BuildContext context) => CustomPaint(
+    painter: _SpriteCropPainter(image: image, sourceRect: sourceRect),
+  );
+}
+
+class _SpriteCropPainter extends CustomPainter {
+  const _SpriteCropPainter({required this.image, required this.sourceRect});
+
+  final ui.Image image;
+  final ui.Rect sourceRect;
+
+  @override
+  void paint(Canvas canvas, Size size) {
+    final fitted = applyBoxFit(BoxFit.cover, sourceRect.size, size);
+    final sourceOffset = Alignment.center.inscribe(
+      fitted.source,
+      Offset.zero & sourceRect.size,
+    );
+    final source = Rect.fromLTWH(
+      sourceRect.left + sourceOffset.left,
+      sourceRect.top + sourceOffset.top,
+      fitted.source.width,
+      fitted.source.height,
+    );
+    final destination = Alignment.center.inscribe(
+      fitted.destination,
+      Offset.zero & size,
+    );
+    canvas.drawImageRect(
+      image,
+      source,
+      destination,
+      Paint()
+        ..filterQuality = FilterQuality.low
+        ..isAntiAlias = false,
+    );
+  }
+
+  @override
+  bool shouldRepaint(covariant _SpriteCropPainter oldDelegate) =>
+      oldDelegate.image != image || oldDelegate.sourceRect != sourceRect;
+}
+
 String _format(Duration value) {
   final minutes = value.inMinutes.remainder(60).toString().padLeft(2, '0');
   final seconds = value.inSeconds.remainder(60).toString().padLeft(2, '0');

lib/pages/player/widgets/seek_progress_bar.dart

@@ -7,6 +7,7 @@ import 'package:flutter/material.dart';
 import 'package:video_player/video_player.dart';
 
 import '../../../core/data/services/playback_thumbnail_service.dart';
+import '../../../core/data/services/sprite_thumbnail_axis.dart';
 import '../../../core/theme/app_colors.dart';
 import 'loading_progress_track.dart';
 import 'scrub_preview_card.dart';
@@ -35,8 +36,10 @@ class SeekProgressBar extends StatefulWidget {
     this.inactiveTrackColor = AppColors.border,
     this.locked = false,
     this.thumbnailService,
+    this.spriteAxisService,
     this.episodeId,
     this.posterUrl = '',
+    this.thumbnailsUrl,
   });
 
   final ValueListenable<VideoPlayerValue>? valueListenable;
@@ -48,8 +51,10 @@ class SeekProgressBar extends StatefulWidget {
   final Color inactiveTrackColor;
   final bool locked;
   final PlaybackThumbnailService? thumbnailService;
+  final SpriteThumbnailAxisService? spriteAxisService;
   final String? episodeId;
   final String posterUrl;
+  final String? thumbnailsUrl;
 
   @override
   State<SeekProgressBar> createState() => _SeekProgressBarState();
@@ -299,6 +304,8 @@ class _SeekProgressBarState extends State<SeekProgressBar> {
                 bottom: trackAreaHeight + 8,
                 child: ScrubPreviewCard(
                   service: widget.thumbnailService!,
+                  spriteAxisService: widget.spriteAxisService,
+                  thumbnailsUrl: widget.thumbnailsUrl,
                   episodeId: widget.episodeId!,
                   posterUrl: widget.posterUrl,
                   position: previewPosition,