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

7.9 KiB
Raw Blame History

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 缓存:

// 修复前 - 每次都先查缓存
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

改动前:

  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;
  }

改动后:

  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

改动前:

  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,
        );

改动后:

  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

改动前:

  void _refresh() {
    setState(() {
      future = _load();
    });
  }

改动后:

  Future<void> _refresh() async {
    ref.invalidate(apiClientProvider);
    final f = _load(forceRefresh: true);  // ← 绕过缓存
    setState(() {
      future = f;
    });
    await f;  // ← RefreshIndicator 等 future 完成才停止动画
  }

改动 3:RefreshIndicator 移到 FutureBuilder 外层

改动前:

    return FutureBuilder<List<Artwork>>(
      future: future,
      builder: (context, snapshot) {
        ...
        return RefreshIndicator(
          onRefresh: _refresh,
          child: CustomScrollView(
            controller: _scrollController,
            slivers: [...],
          ),
        );
      },
    );

改动后:

    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

改动前:

    trailing: [
      ...
      IconButton(
        tooltip: '刷新',
        onPressed: _refresh,
        icon: const Icon(Icons.refresh),
      ),
    ],

改动后:

    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