Files
SakuraHub/docs/2026-06-22_apk_refresh_fix.md
2026-11-16 20:45:22 +08:00

281 lines
7.9 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 |