跨平台开发 / 系统课时
刷新接口并保留状态边界
刷新接口并保留状态边界
刷新不是把页面重新变成首次加载。更好的交互是:首次请求没有数据时显示完整 loading;已有数据后再次刷新时保留旧内容,只给出轻量反馈;刷新完成再切到新数据或错误。AsyncNotifier 可以通过自己的方法触发重新计算,并让 UI 根据刷新状态决定反馈强度。
学习目标
- 通过
AsyncNotifier方法触发数据重新加载 - 区分首次 loading 与已有数据后的 refreshing
- 使用
isRefreshing和skipLoadingOnRefresh控制刷新反馈
把刷新入口放进 Notifier
如果页面直接拼接网络请求,刷新逻辑会散落在 Widget 中。把 refresh 暴露为 Notifier 方法后,Widget 只表达“用户请求刷新”,具体怎样让 provider 重算由状态层负责。
这里使用 ref.invalidateSelf() 使当前 provider 失效。只要页面仍在监听它,Riverpod 会重新执行 build。在已经产生过数据后发生这种主动重算时,UI 可以识别刷新状态,而不必把它当成第一次加载。

实现保留旧内容的刷新
下面的示例用仓库中的计数器模拟服务端版本。首次加载显示“版本 1”;点击刷新后,旧内容继续显示,同时顶部出现线性进度条;请求完成后变为“版本 2”。
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(),
],
),
),
);
}
}预期结果
首次进入:显示居中的圆形加载指示器,随后列表出现“版本 1”
点击刷新:列表“版本 1”继续可见,顶部出现线性进度条
刷新完成:顶部进度条消失,列表更新为“版本 2”把首次加载和刷新分开设计
首次加载时页面没有可展示的数据,因此 loading 分支承担完整占位很合理。刷新时已经有可用内容,如果再次切成整页加载,会产生闪烁,也会让用户误以为页面状态被重置。
skipLoadingOnRefresh: true 的意义就是保持这个边界:刷新期间优先继续展示已有 data,isRefreshing 则额外告诉页面“新请求仍在进行”。因此可以把主内容和刷新反馈拆开,而不是让一个 loading 分支同时承担两种完全不同的交互。
刷新失败时要明确取舍
示例没有设置 skipError: true,因此刷新最终失败时会进入 error 分支。这适合“新鲜数据是页面继续工作的前提”的场景。如果旧数据仍然可用,也可以设计成保留旧列表,再通过 SnackBar、Banner 或局部提示告知刷新失败。
关键不是永远隐藏错误,而是保持状态边界一致:首次无数据、刷新旧数据、最终成功或失败应该对应清晰的页面反馈。把刷新入口集中在 Notifier,再由 AsyncValue 的状态信息驱动 UI,后续加入下拉刷新、自动重试或缓存时也不需要把请求逻辑重新塞回 Widget。