feat(flutter): 统一文字下拉刷新

lib/core/widgets/app_pull_to_refresh.dart

@@ -0,0 +1,163 @@
+// Author: fruit.com.cn
+
+import 'dart:async';
+
+import 'package:flutter/material.dart';
+
+import '../../l10n/app_localizations.dart';
+import '../theme/app_colors.dart';
+
+const double _maxPullDistance = 96;
+const double _refreshThreshold = 56;
+const Duration _arrowTurnDuration = Duration(milliseconds: 160);
+const Duration _retractDuration = Duration(milliseconds: 200);
+
+enum _PullState { idle, pull, armed, refreshing }
+
+/// 带文字状态提示的下拉刷新容器，指示区悬浮在内容上方。
+class AppPullToRefresh extends StatefulWidget {
+  const AppPullToRefresh({
+    super.key,
+    required this.child,
+    required this.onRefresh,
+    this.edgeOffset = 0,
+  });
+
+  final Widget child;
+  final Future<void> Function() onRefresh;
+  final double edgeOffset;
+
+  @override
+  State<AppPullToRefresh> createState() => _AppPullToRefreshState();
+}
+
+class _AppPullToRefreshState extends State<AppPullToRefresh> {
+  _PullState _state = _PullState.idle;
+  double _pullDistance = 0;
+  bool _refreshing = false;
+
+  bool _onScroll(ScrollNotification notification) {
+    if (notification.depth != 0 || _refreshing) return false;
+    if (notification is ScrollStartNotification) {
+      if (notification.dragDetails != null) _setPullDistance(0);
+    } else if (notification is OverscrollNotification) {
+      if (notification.dragDetails != null) {
+        _setPullDistance(_pullDistance - notification.overscroll);
+      }
+    } else if (notification is ScrollEndNotification) {
+      _release();
+    }
+    return false;
+  }
+
+  void _setPullDistance(double value) {
+    final distance = value.clamp(0.0, _maxPullDistance);
+    final state = distance >= _refreshThreshold
+        ? _PullState.armed
+        : distance > 0
+        ? _PullState.pull
+        : _PullState.idle;
+    if (distance == _pullDistance && state == _state) return;
+    setState(() {
+      _pullDistance = distance;
+      _state = state;
+    });
+  }
+
+  void _release() {
+    if (_state == _PullState.armed) {
+      unawaited(_refresh());
+    } else if (_state == _PullState.pull) {
+      setState(() {
+        _pullDistance = 0;
+        _state = _PullState.idle;
+      });
+    }
+  }
+
+  Future<void> _refresh() async {
+    if (_refreshing) return;
+    _refreshing = true;
+    setState(() => _state = _PullState.refreshing);
+    try {
+      await widget.onRefresh();
+    } finally {
+      await Future<void>.delayed(_retractDuration);
+      if (mounted) {
+        setState(() {
+          _pullDistance = 0;
+          _state = _PullState.idle;
+          _refreshing = false;
+        });
+      }
+    }
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    return NotificationListener<ScrollNotification>(
+      onNotification: _onScroll,
+      child: Stack(
+        fit: StackFit.expand,
+        children: [
+          widget.child,
+          if (_state != _PullState.idle)
+            Positioned(
+              top: widget.edgeOffset,
+              left: 0,
+              right: 0,
+              child: IgnorePointer(child: _indicator(context)),
+            ),
+        ],
+      ),
+    );
+  }
+
+  Widget _indicator(BuildContext context) {
+    final l10n = AppLocalizations.of(context)!;
+    if (_state == _PullState.refreshing) {
+      return _label(
+        const SizedBox.square(
+          dimension: 18,
+          child: CircularProgressIndicator(
+            strokeWidth: 2,
+            color: AppColors.blue,
+          ),
+        ),
+        l10n.refreshingLabel,
+      );
+    }
+    final armed = _state == _PullState.armed;
+    return _label(
+      AnimatedRotation(
+        turns: armed ? 0.5 : 0,
+        duration: _arrowTurnDuration,
+        child: Icon(
+          Icons.arrow_downward_rounded,
+          size: 18,
+          color: armed ? AppColors.blue : AppColors.muted,
+        ),
+      ),
+      armed ? l10n.releaseToRefresh : l10n.pullToRefresh,
+      emphasized: armed,
+    );
+  }
+
+  Widget _label(Widget icon, String text, {bool emphasized = false}) {
+    return Row(
+      mainAxisAlignment: MainAxisAlignment.center,
+      children: [
+        icon,
+        const SizedBox(width: 6),
+        Text(
+          text,
+          style: TextStyle(
+            color: emphasized ? AppColors.blue : AppColors.muted,
+            fontSize: 12,
+            fontWeight: emphasized ? FontWeight.w700 : FontWeight.w500,
+          ),
+        ),
+      ],
+    );
+  }
+}

lib/l10n/app_en.arb

@@ -338,6 +338,9 @@
     }
   },
   "retry": "Retry",
+  "pullToRefresh": "Pull to refresh",
+  "releaseToRefresh": "Release to refresh",
+  "refreshingLabel": "Refreshing…",
   "backToSeries": "Back to series",
   "nextEpisode": "Next episode",
   "pause": "Pause",

lib/l10n/app_id.arb

@@ -312,6 +312,9 @@
     }
   },
   "retry": "Coba lagi",
+  "pullToRefresh": "Tarik untuk menyegarkan",
+  "releaseToRefresh": "Lepaskan untuk menyegarkan",
+  "refreshingLabel": "Menyegarkan…",
   "backToSeries": "Kembali ke serial",
   "nextEpisode": "Episode berikutnya",
   "pause": "Jeda",

lib/l10n/app_localizations.dart

@@ -1336,6 +1336,24 @@ abstract class AppLocalizations {
   /// **'Retry'**
   String get retry;
 
+  /// No description provided for @pullToRefresh.
+  ///
+  /// In en, this message translates to:
+  /// **'Pull to refresh'**
+  String get pullToRefresh;
+
+  /// No description provided for @releaseToRefresh.
+  ///
+  /// In en, this message translates to:
+  /// **'Release to refresh'**
+  String get releaseToRefresh;
+
+  /// No description provided for @refreshingLabel.
+  ///
+  /// In en, this message translates to:
+  /// **'Refreshing…'**
+  String get refreshingLabel;
+
   /// No description provided for @backToSeries.
   ///
   /// In en, this message translates to:

lib/l10n/app_localizations_en.dart

@@ -676,6 +676,15 @@ class AppLocalizationsEn extends AppLocalizations {
   @override
   String get retry => 'Retry';
 
+  @override
+  String get pullToRefresh => 'Pull to refresh';
+
+  @override
+  String get releaseToRefresh => 'Release to refresh';
+
+  @override
+  String get refreshingLabel => 'Refreshing…';
+
   @override
   String get backToSeries => 'Back to series';
 

lib/l10n/app_localizations_id.dart

@@ -679,6 +679,15 @@ class AppLocalizationsId extends AppLocalizations {
   @override
   String get retry => 'Coba lagi';
 
+  @override
+  String get pullToRefresh => 'Tarik untuk menyegarkan';
+
+  @override
+  String get releaseToRefresh => 'Lepaskan untuk menyegarkan';
+
+  @override
+  String get refreshingLabel => 'Menyegarkan…';
+
   @override
   String get backToSeries => 'Kembali ke serial';
 

lib/l10n/app_localizations_zh.dart

@@ -668,6 +668,15 @@ class AppLocalizationsZh extends AppLocalizations {
   @override
   String get retry => '重试';
 
+  @override
+  String get pullToRefresh => '下拉刷新';
+
+  @override
+  String get releaseToRefresh => '松手刷新';
+
+  @override
+  String get refreshingLabel => '正在刷新…';
+
   @override
   String get backToSeries => '返回剧集详情';
 

lib/l10n/app_zh.arb

@@ -274,6 +274,9 @@
     }
   },
   "retry": "重试",
+  "pullToRefresh": "下拉刷新",
+  "releaseToRefresh": "松手刷新",
+  "refreshingLabel": "正在刷新…",
   "backToSeries": "返回剧集详情",
   "nextEpisode": "下一集",
   "pause": "暂停",

lib/pages/discover/discover_view.dart

@@ -14,6 +14,7 @@ import '../../core/theme/app_colors.dart';
 import '../../core/theme/app_dimens.dart';
 import '../../core/theme/app_theme.dart';
 import '../../core/widgets/app_bottom_nav.dart';
+import '../../core/widgets/app_pull_to_refresh.dart';
 import '../../core/widgets/empty_state.dart';
 import '../../l10n/app_localizations.dart';
 import '../filter/filter_page.dart';
@@ -152,11 +153,8 @@ class _DiscoverPageState extends State<DiscoverPage> {
       child: Stack(
         children: [
           Positioned.fill(
-            child: RefreshIndicator(
+            child: AppPullToRefresh(
               key: const Key('discover-refresh'),
-              color: AppColors.blue,
-              backgroundColor: AppColors.card,
-              strokeWidth: 2,
               edgeOffset: _stickyHeaderHeight + 8,
               onRefresh: categories.load,
               child: ListView(

lib/pages/downloads/downloads_page.dart

@@ -16,6 +16,7 @@ import '../../core/platform/haptics.dart';
 import '../../core/theme/app_colors.dart';
 import '../../core/theme/app_dimens.dart';
 import '../../core/theme/app_theme.dart';
+import '../../core/widgets/app_pull_to_refresh.dart';
 import '../../core/widgets/auth_gate.dart';
 import '../../core/widgets/empty_state.dart';
 import '../../core/widgets/plain_page_scaffold.dart';
@@ -90,9 +91,10 @@ class _DownloadsBody extends StatelessWidget {
       );
     }
     final policy = downloads.policy!;
-    return RefreshIndicator(
+    return AppPullToRefresh(
       onRefresh: downloads.load,
       child: ListView(
+        physics: const AlwaysScrollableScrollPhysics(),
         padding: const EdgeInsets.fromLTRB(16, 10, 16, 28),
         children: [
           _PolicyPanel(downloads: downloads, policy: policy),

lib/pages/favorites/favorites_page.dart

@@ -13,6 +13,7 @@ import '../../core/formatting/error_text.dart';
 import '../../core/platform/haptics.dart';
 import '../../core/theme/app_colors.dart';
 import '../../core/theme/app_theme.dart';
+import '../../core/widgets/app_pull_to_refresh.dart';
 import '../../core/widgets/auth_gate.dart';
 import '../../core/widgets/empty_state.dart';
 import '../../core/widgets/remote_image.dart';
@@ -163,10 +164,7 @@ class _FavoritesBody extends StatelessWidget {
     FavoriteController favorites, {
     required List<Widget> children,
   }) {
-    return RefreshIndicator(
-      color: AppColors.blue,
-      backgroundColor: AppColors.card,
-      strokeWidth: 2,
+    return AppPullToRefresh(
       onRefresh: favorites.load,
       child: ListView(
         physics: const AlwaysScrollableScrollPhysics(),

lib/pages/home/home_browse_view.dart

@@ -12,6 +12,7 @@ import '../../core/data/repositories/watch_history_repository.dart';
 import '../../core/data/services/catalog_controller.dart';
 import '../../core/theme/app_colors.dart';
 import '../../core/theme/app_dimens.dart';
+import '../../core/widgets/app_pull_to_refresh.dart';
 import '../../core/widgets/empty_state.dart';
 import '../../l10n/app_localizations.dart';
 import '../discover/widgets/feed_banner_carousel.dart';
@@ -137,10 +138,8 @@ class _HomeBrowseViewState extends State<HomeBrowseView> {
     return Stack(
       children: [
         Positioned.fill(
-          child: RefreshIndicator(
+          child: AppPullToRefresh(
             key: const Key('home-refresh'),
-            color: AppColors.blue,
-            backgroundColor: AppColors.card,
             onRefresh: () async {
               await Future.wait([catalog.load(), logic.refreshRecent()]);
             },

lib/pages/notices/notices_page.dart

@@ -13,6 +13,7 @@ import '../../core/formatting/localized_date_time.dart';
 import '../../core/theme/app_colors.dart';
 import '../../core/theme/app_dimens.dart';
 import '../../core/theme/app_theme.dart';
+import '../../core/widgets/app_pull_to_refresh.dart';
 import '../../core/widgets/empty_state.dart';
 import '../../core/widgets/plain_page_scaffold.dart';
 import '../../l10n/app_localizations.dart';
@@ -65,7 +66,7 @@ class _NoticesPageState extends State<NoticesPage> {
       );
     }
     if (_controller.error != null && _controller.notices.isEmpty) {
-      return RefreshIndicator(
+      return AppPullToRefresh(
         onRefresh: _controller.refresh,
         child: ListView(
           physics: const AlwaysScrollableScrollPhysics(),
@@ -90,7 +91,7 @@ class _NoticesPageState extends State<NoticesPage> {
       );
     }
     if (_controller.notices.isEmpty) {
-      return RefreshIndicator(
+      return AppPullToRefresh(
         onRefresh: _controller.refresh,
         child: ListView(
           physics: const AlwaysScrollableScrollPhysics(),
@@ -108,7 +109,7 @@ class _NoticesPageState extends State<NoticesPage> {
         ),
       );
     }
-    return RefreshIndicator(
+    return AppPullToRefresh(
       onRefresh: _controller.refresh,
       child: ListView.separated(
         key: const Key('notices-list'),

lib/pages/wallet/wallet_page.dart

@@ -12,6 +12,7 @@ import '../../core/formatting/localized_date_time.dart';
 import '../../core/theme/app_colors.dart';
 import '../../core/theme/app_dimens.dart';
 import '../../core/theme/app_theme.dart';
+import '../../core/widgets/app_pull_to_refresh.dart';
 import '../../core/widgets/empty_state.dart';
 import '../../core/widgets/plain_page_scaffold.dart';
 import '../store/recharge_page.dart';
@@ -116,9 +117,10 @@ class _WalletPageState extends State<WalletPage> {
         onAction: () => unawaited(wallet.load()),
       );
     }
-    return RefreshIndicator(
+    return AppPullToRefresh(
       onRefresh: wallet.load,
       child: ListView(
+        physics: const AlwaysScrollableScrollPhysics(),
         padding: const EdgeInsets.fromLTRB(16, 8, 16, 28),
         children: [
           _BalanceHero(wallet: snapshot.wallet),

lib/pages/watch_records/watch_records_page.dart

@@ -14,6 +14,7 @@ import '../../core/formatting/error_text.dart';
 import '../../core/platform/haptics.dart';
 import '../../core/theme/app_colors.dart';
 import '../../core/theme/app_theme.dart';
+import '../../core/widgets/app_pull_to_refresh.dart';
 import '../../core/widgets/auth_gate.dart';
 import '../../core/widgets/empty_state.dart';
 import '../../core/widgets/subpage_header.dart';
@@ -145,10 +146,7 @@ class _WatchRecordsBodyState extends State<_WatchRecordsBody> {
   }
 
   Widget _refreshable({required List<Widget> children}) {
-    return RefreshIndicator(
-      color: AppColors.blue,
-      backgroundColor: AppColors.card,
-      strokeWidth: 2,
+    return AppPullToRefresh(
       onRefresh: controller.load,
       child: ListView(
         physics: const AlwaysScrollableScrollPhysics(),