跨平台开发 / 系统课时
在页面中渲染异步状态
在页面中渲染异步状态
拿到 AsyncValue 只是异步状态管理的一半,另一半是让用户始终知道页面正在发生什么。本节把 AsyncNotifier 的 loading、data、error 三个分支完整映射到 Flutter 界面,并加入失败后的重试路径。
学习目标
- 使用
AsyncValue.when为三种异步结果构建不同界面 - 在
AsyncNotifier执行期间显示加载、成功和错误反馈 - 为失败状态提供可操作的重试入口
先把三种页面反馈补齐
异步页面最容易遗漏的是失败分支。只显示进度条和成功内容时,一旦请求抛出异常,用户既不知道发生了什么,也没有恢复入口。
一个完整页面至少需要明确三种反馈:loading 阶段告诉用户仍在处理;data 阶段渲染真正内容;error 阶段说明操作失败,并在适合重试的场景提供按钮。when 正好要求调用方分别处理这三条路径。
用 AsyncNotifier 驱动完整页面
下面示例不依赖代码生成。ProfileNotifier 首次加载成功后,可以主动触发一次失败;错误页面再通过“重新加载”恢复到成功状态。这样能够实际观察三种 UI 分支如何切换。
import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
void main() {
runApp(
const ProviderScope(
child: MaterialApp(home: ProfilePage()),
),
);
}
class ProfileNotifier extends AsyncNotifier<String> {
@override
Future<String> build() async {
return _loadProfile(shouldFail: false);
}
Future<String> _loadProfile({required bool shouldFail}) async {
await Future<void>.delayed(const Duration(milliseconds: 600));
if (shouldFail) {
throw Exception('服务器暂时不可用');
}
return 'Ada Lovelace';
}
Future<void> reload({required bool shouldFail}) async {
// 先进入 loading,再把成功值或异常统一转换回 AsyncValue。
state = const AsyncLoading();
state = await AsyncValue.guard(
() => _loadProfile(shouldFail: shouldFail),
);
}
}
final profileProvider = AsyncNotifierProvider<ProfileNotifier, String>(
ProfileNotifier.new,
);
class ProfilePage extends ConsumerWidget {
const ProfilePage({super.key});
@override
Widget build(BuildContext context, WidgetRef ref) {
final profile = ref.watch(profileProvider);
return Scaffold(
appBar: AppBar(title: const Text('用户资料')),
body: profile.when(
loading: () => const Center(
child: CircularProgressIndicator(),
),
data: (name) => Center(
child: Column(
mainAxisSize: MainAxisSize.min,
children: [
Text('欢迎,$name'),
const SizedBox(height: 16),
ElevatedButton(
onPressed: () {
ref
.read(profileProvider.notifier)
.reload(shouldFail: true);
},
child: const Text('模拟加载失败'),
),
],
),
),
error: (error, stackTrace) => Center(
child: Column(
mainAxisSize: MainAxisSize.min,
children: [
const Text('资料加载失败,请稍后重试'),
const SizedBox(height: 16),
ElevatedButton(
onPressed: () {
ref
.read(profileProvider.notifier)
.reload(shouldFail: false);
},
child: const Text('重新加载'),
),
],
),
),
),
);
}
}预期结果
启动后:先显示圆形加载指示器,约 600 毫秒后显示“欢迎,Ada Lovelace”。
点击“模拟加载失败”:再次显示加载指示器,随后进入错误页面。
点击“重新加载”:显示加载指示器,随后恢复为“欢迎,Ada Lovelace”。为什么更新前先进入 Loading
reload 先把 state 设置为 AsyncLoading,页面就会立即获得新的状态并显示进度反馈。异步函数结束后,AsyncValue.guard 会把返回值包装成 AsyncData,或者把抛出的异常包装成 AsyncError,避免在每个请求方法中重复编写 try、catch 和状态赋值。
这种写法尤其适合用户主动点击刷新、重试或提交后需要明确等待反馈的操作。页面只观察 provider,不需要知道请求内部用了 HTTP、数据库还是其他数据源。
错误页面应该提供恢复路径
示例没有把异常对象原样显示给最终用户,而是给出“资料加载失败,请稍后重试”的稳定提示。异常和堆栈更适合交给日志与监控系统;页面应告诉用户当前结果以及下一步能做什么。
对于无网络、服务暂时不可用等可恢复问题,可以提供重试按钮。权限不足、参数非法等无法通过重复请求解决的问题,则应给出相应说明,而不是让用户无限重试。
检查页面是否真正完整
验收异步页面时,不要只验证正常返回数据的路径。至少实际触发一次 loading、一次成功和一次失败,并确认失败后能够回到正常状态。只要这三条路径都由同一个 AsyncValue 驱动,页面状态与业务状态就能保持一致,后续替换真实数据源时也更容易维护。