# APK 下拉刷新 / 删除后页面不刷新 修复 **日期**: 2026-06-22 **问题**: 删除作品后页面不刷新;下拉刷新不生效,无法重新请求当前页数据 --- ## 根因分析 ### 根因 1:`RefreshIndicator` 放错位置,嵌套在 `FutureBuilder` 内部 `RefreshIndicator` 被放在 `FutureBuilder` 的 `builder` 闭包内。每次 `setState` 更新 `future` → `FutureBuilder` 重建 → `RefreshIndicator` 被销毁再创建 → 下拉手势/动画状态丢失。 **正常工作**的 `feed_tab.dart` 结构: ``` RefreshIndicator → ListView → FutureBuilder(内部) ``` **异常结构**(修复前): ``` FutureBuilder → RefreshIndicator → CustomScrollView ``` ### 根因 2:缺少 `AlwaysScrollableScrollPhysics` `CustomScrollView` 未设置 `physics: AlwaysScrollableScrollPhysics()`。数据少于一屏时不可滚动 → `RefreshIndicator` 无法探测下拉手势。 ### 根因 3(核心):API 客户端缓存导致的"假刷新" `api_client.dart` 的 `gallery()` 方法有 **30 分钟 SharedPreferences 缓存**: ```dart // 修复前 - 每次都先查缓存 final cacheKey = _cacheKey('gallery', params); final cached = await _readCache>(cacheKey); if (cached != null) return cached; // ← 始终返回旧数据 ``` 刷新链路全追踪: ``` _refresh() → ref.invalidate(apiClientProvider) ✅ 创建新 SakuraApiClient → _load() → gallery() → _cacheKey('gallery', params) ❌ token 没变 → cache key 一样 → _readCache(cacheKey) ❌ 命中 30 分钟前的缓存 → 返回删除/修改前的旧数据 ❌ 表现:刷新无效 ``` Token 不变 → `_cacheKey` 内 `token.hashCode` 不变 → **缓存 key 不变** → 永远返回缓存。即使 `ref.invalidate` 创建了新客户端实例也无效,因为缓存存在 SharedPreferences 中,跨实例共享。 --- ## 修改文件清单(3 个文件) | 文件 | 改动 | |------|------| | `sakura_mobile/lib/src/core/api_client.dart` | `gallery()` 加 `bypassCache` 参数 | | `sakura_mobile/lib/src/pages/tabs/gallery_tab.dart` | 结构调整 + 缓存穿透 + 删除刷新按钮 | | `sakura_mobile/lib/src/pages/tabs/novels_tab.dart` | 结构调整 + 删除刷新按钮 | --- ## 改动详情 ### 一、`sakura_mobile/lib/src/core/api_client.dart` #### `gallery()` 加 `bypassCache` 参数 **改动前**: ```dart Future> gallery({ String? search, String searchScope = 'all', bool? isFavorite, String? contentType, String? sort, int page = 1, int limit = 60, bool includeTotal = true, }) async { ... final cacheKey = _cacheKey('gallery', params); final cached = await _readCache>(cacheKey); if (cached != null) return cached; final response = await dio.get('/api/v1/gallery', queryParameters: params); final data = response.data['data']['items'] as List; await _writeCache(cacheKey, data); return data; } ``` **改动后**: ```dart Future> gallery({ String? search, String searchScope = 'all', bool? isFavorite, String? contentType, String? sort, int page = 1, int limit = 60, bool includeTotal = true, bool bypassCache = false, // ← 新增 }) async { ... final cacheKey = _cacheKey('gallery', params); if (!bypassCache) { // ← 新增:仅在非刷新时读缓存 final cached = await _readCache>(cacheKey); if (cached != null) return cached; } final response = await dio.get('/api/v1/gallery', queryParameters: params); final data = response.data['data']['items'] as List; await _writeCache(cacheKey, data); return data; } ``` --- ### 二、`sakura_mobile/lib/src/pages/tabs/gallery_tab.dart` #### 改动 1:`_load()` 加 `forceRefresh` 参数,传递到 `gallery()` **改动前**: ```dart Future> _load({bool reset = true}) async { if (reset) { _page = 1; _hasMore = true; _items.clear(); selectedIds.clear(); selectionMode = false; } final rows = await ref.read(apiClientProvider).gallery( search: search.text.trim().isEmpty ? null : search.text.trim(), searchScope: searchScope, isFavorite: favoritesOnly ? true : null, contentType: _effectiveContentType, sort: recentUpdatesOnly ? 'updated' : null, page: _page, limit: _pageSize, includeTotal: false, ); ``` **改动后**: ```dart Future> _load({bool reset = true, bool forceRefresh = false}) async { if (reset) { _page = 1; _hasMore = true; _items.clear(); selectedIds.clear(); selectionMode = false; } final rows = await ref.read(apiClientProvider).gallery( search: search.text.trim().isEmpty ? null : search.text.trim(), searchScope: searchScope, isFavorite: favoritesOnly ? true : null, contentType: _effectiveContentType, sort: recentUpdatesOnly ? 'updated' : null, page: _page, limit: _pageSize, includeTotal: false, bypassCache: forceRefresh, // ← 新增:刷新时绕过缓存 ); ``` #### 改动 2:`_refresh()` 改为 async,传递 `forceRefresh: true` **改动前**: ```dart void _refresh() { setState(() { future = _load(); }); } ``` **改动后**: ```dart Future _refresh() async { ref.invalidate(apiClientProvider); final f = _load(forceRefresh: true); // ← 绕过缓存 setState(() { future = f; }); await f; // ← RefreshIndicator 等 future 完成才停止动画 } ``` #### 改动 3:`RefreshIndicator` 移到 `FutureBuilder` 外层 **改动前**: ```dart return FutureBuilder>( future: future, builder: (context, snapshot) { ... return RefreshIndicator( onRefresh: _refresh, child: CustomScrollView( controller: _scrollController, slivers: [...], ), ); }, ); ``` **改动后**: ```dart return RefreshIndicator( color: const Color(0xFFD95A83), onRefresh: _refresh, child: FutureBuilder>( future: future, builder: (context, snapshot) { ... return CustomScrollView( controller: _scrollController, physics: const AlwaysScrollableScrollPhysics(), // ← 新增 slivers: [...], ); }, ), ); ``` #### 改动 4:删除刷新 IconButton **改动前**: ```dart trailing: [ ... IconButton( tooltip: '刷新', onPressed: _refresh, icon: const Icon(Icons.refresh), ), ], ``` **改动后**: ```dart trailing: [ ... // 刷新按钮已移除,统一使用下拉刷新 ], ``` --- ### 三、`sakura_mobile/lib/src/pages/tabs/novels_tab.dart` 同 gallery_tab 的改动 3、4(结构调整 + 删除按钮)。novels API 本身无缓存,无需 `bypassCache`。 --- ## 修复后的刷新链路 ``` 用户下拉 → RefreshIndicator.onRefresh → _refresh() → ref.invalidate(apiClientProvider) ✅ 创建新客户端 → _load(forceRefresh: true) → gallery(bypassCache: true) ✅ 跳过缓存 → dio.get('/api/v1/gallery') ✅ 真实 HTTP 请求 → _writeCache(cacheKey, newData) ✅ 写入新缓存 → 返回服务器最新数据 ✅ → setState({future: f}) ✅ FutureBuilder 拿到新 future → await f ✅ 等待完成,停止下拉动画 → UI 展示最新数据 ✅ 删除/修改后的数据正确 ``` ## 构建产物 | 产物 | 路径 | 大小 | |------|------|------| | APK | `release/sakura.apk` | 66.8 MB | | EXE | `dist/sakuradownloader.exe` | 63 MB |