跨平台开发 / 系统课时

刷新接口并保留状态边界

刷新接口并保留状态边界

刷新不是把页面重新变成首次加载。更好的交互是:首次请求没有数据时显示完整 loading;已有数据后再次刷新时保留旧内容,只给出轻量反馈;刷新完成再切到新数据或错误。AsyncNotifier 可以通过自己的方法触发重新计算,并让 UI 根据刷新状态决定反馈强度。

学习目标

  • 通过 AsyncNotifier 方法触发数据重新加载
  • 区分首次 loading 与已有数据后的 refreshing
  • 使用 isRefreshing 和 skipLoadingOnRefresh 控制刷新反馈

把刷新入口放进 Notifier

如果页面直接拼接网络请求,刷新逻辑会散落在 Widget 中。把 refresh 暴露为 Notifier 方法后,Widget 只表达“用户请求刷新”,具体怎样让 provider 重算由状态层负责。

这里使用 ref.invalidateSelf() 使当前 provider 失效。只要页面仍在监听它,Riverpod 会重新执行 build。在已经产生过数据后发生这种主动重算时,UI 可以识别刷新状态,而不必把它当成第一次加载。

首次加载与刷新时的状态边界

实现保留旧内容的刷新

下面的示例用仓库中的计数器模拟服务端版本。首次加载显示“版本 1”;点击刷新后,旧内容继续显示,同时顶部出现线性进度条;请求完成后变为“版本 2”。

dart
import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';

void main() {
  runApp(const ProviderScope(child: MyApp()));
}

class ArticleRepository {
  int _version = 0;

  Future<List<String>> fetchArticles() async {
    await Future<void>.delayed(const Duration(milliseconds: 600));
    _version += 1;
    return ['版本 $_version', 'Riverpod 异步数据'];
  }
}

final articleRepositoryProvider = Provider<ArticleRepository>((ref) {
  return ArticleRepository();
});

class ArticleController extends AsyncNotifier<List<String>> {
  @override
  Future<List<String>> build() {
    return ref.read(articleRepositoryProvider).fetchArticles();
  }

  void refresh() {
    // 让 provider 重新执行 build,而不是在 Widget 中直接请求仓库。
    ref.invalidateSelf();
  }
}

final articleProvider =
    AsyncNotifierProvider<ArticleController, List<String>>(
  ArticleController.new,
);

class MyApp extends ConsumerWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final articles = ref.watch(articleProvider);

    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(
          title: const Text('文章'),
          actions: [
            IconButton(
              onPressed: () {
                ref.read(articleProvider.notifier).refresh();
              },
              icon: const Icon(Icons.refresh),
            ),
          ],
        ),
        body: Stack(
          children: [
            articles.when(
              // 明确声明:刷新时继续走 data 分支,保留旧内容。
              skipLoadingOnRefresh: true,
              data: (items) => ListView(
                children: [
                  for (final item in items) ListTile(title: Text(item)),
                ],
              ),
              loading: () => const Center(
                child: CircularProgressIndicator(),
              ),
              error: (error, stackTrace) => Center(
                child: Text('加载失败:$error'),
              ),
            ),
            if (articles.isRefreshing)
              const LinearProgressIndicator(),
          ],
        ),
      ),
    );
  }
}

预期结果

text
首次进入:显示居中的圆形加载指示器,随后列表出现“版本 1”
点击刷新:列表“版本 1”继续可见,顶部出现线性进度条
刷新完成:顶部进度条消失,列表更新为“版本 2”

把首次加载和刷新分开设计

首次加载时页面没有可展示的数据,因此 loading 分支承担完整占位很合理。刷新时已经有可用内容,如果再次切成整页加载,会产生闪烁,也会让用户误以为页面状态被重置。

skipLoadingOnRefresh: true 的意义就是保持这个边界:刷新期间优先继续展示已有 data,isRefreshing 则额外告诉页面“新请求仍在进行”。因此可以把主内容和刷新反馈拆开,而不是让一个 loading 分支同时承担两种完全不同的交互。

刷新失败时要明确取舍

示例没有设置 skipError: true,因此刷新最终失败时会进入 error 分支。这适合“新鲜数据是页面继续工作的前提”的场景。如果旧数据仍然可用,也可以设计成保留旧列表,再通过 SnackBar、Banner 或局部提示告知刷新失败。

关键不是永远隐藏错误,而是保持状态边界一致:首次无数据、刷新旧数据、最终成功或失败应该对应清晰的页面反馈。把刷新入口集中在 Notifier,再由 AsyncValue 的状态信息驱动 UI,后续加入下拉刷新、自动重试或缓存时也不需要把请求逻辑重新塞回 Widget。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

刷新接口并保留状态边界

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通