Files
SakuraHub/docs/2026-06-22_apk_refresh_fix.md
T

280 lines
7.9 KiB
Markdown
Raw Normal View History

2026-11-16 20:45:22 +08:00
# 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<List<dynamic>>(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<List<dynamic>> 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<List<dynamic>>(cacheKey);
if (cached != null) return cached;
final response = await dio.get('/api/v1/gallery', queryParameters: params);
final data = response.data['data']['items'] as List<dynamic>;
await _writeCache(cacheKey, data);
return data;
}
```
**改动后**:
```dart
Future<List<dynamic>> 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<List<dynamic>>(cacheKey);
if (cached != null) return cached;
}
final response = await dio.get('/api/v1/gallery', queryParameters: params);
final data = response.data['data']['items'] as List<dynamic>;
await _writeCache(cacheKey, data);
return data;
}
```
---
### 二、`sakura_mobile/lib/src/pages/tabs/gallery_tab.dart`
#### 改动 1:`_load()` 加 `forceRefresh` 参数,传递到 `gallery()`
**改动前**:
```dart
Future<List<Artwork>> _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<List<Artwork>> _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<void> _refresh() async {
ref.invalidate(apiClientProvider);
final f = _load(forceRefresh: true); // ← 绕过缓存
setState(() {
future = f;
});
await f; // ← RefreshIndicator 等 future 完成才停止动画
}
```
#### 改动 3:`RefreshIndicator` 移到 `FutureBuilder` 外层
**改动前**:
```dart
return FutureBuilder<List<Artwork>>(
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<List<Artwork>>(
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 |