跨平台开发 / 系统课时
用 AsyncValue 表达三种结果
用 AsyncValue 表达三种结果
异步请求并不只有“成功或失败”两种结果:请求尚未结束时,页面同样需要明确状态。Riverpod 用 AsyncValue<T> 把等待、成功和失败统一成一个值,让业务状态不再依赖多组容易冲突的布尔变量。
学习目标
- 理解
AsyncLoading、AsyncData和AsyncError分别表达什么 - 使用
AsyncValue<T>保存异步操作的完整结果 - 根据当前结果安全读取数据或错误信息
AsyncValue 解决的核心问题
如果分别维护 isLoading、data 和 error,就可能出现“正在加载但同时有错误”“加载结束却没有数据”等矛盾组合。AsyncValue<T> 把这些结果放进同一个类型中,调用方只需要处理合法状态。
| 状态 | 含义 | 页面通常显示 |
|---|---|---|
AsyncLoading<T> |
异步操作正在等待结果 | 进度指示器、骨架屏 |
AsyncData<T> |
操作成功并得到 T 类型数据 |
正常业务内容 |
AsyncError<T> |
操作失败并记录异常与堆栈 | 错误提示、重试入口 |
这里的泛型 T 表示成功时真正需要的数据。例如 AsyncValue<String> 的成功结果是字符串,AsyncValue<List<User>> 的成功结果则是一组用户。
创建并观察三种结果
下面的完整 Flutter 示例直接创建三种 AsyncValue<String>。点击按钮后,页面会切换当前结果,并通过 when 把状态转换为可读文本。
import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
void main() {
runApp(const MaterialApp(home: AsyncValueDemo()));
}
class AsyncValueDemo extends StatefulWidget {
const AsyncValueDemo({super.key});
@override
State<AsyncValueDemo> createState() => _AsyncValueDemoState();
}
class _AsyncValueDemoState extends State<AsyncValueDemo> {
AsyncValue<String> value = const AsyncLoading();
String describe(AsyncValue<String> current) {
return current.when(
loading: () => 'loading:正在等待结果',
data: (data) => 'data:$data',
error: (error, stackTrace) => 'error:$error',
);
}
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: const Text('AsyncValue 三种结果')),
body: Padding(
padding: const EdgeInsets.all(24),
child: Column(
crossAxisAlignment: CrossAxisAlignment.start,
children: [
Text(describe(value)),
const SizedBox(height: 24),
Wrap(
spacing: 8,
children: [
ElevatedButton(
onPressed: () {
setState(() => value = const AsyncLoading());
},
child: const Text('Loading'),
),
ElevatedButton(
onPressed: () {
setState(
() => value = const AsyncData('用户资料已加载'),
);
},
child: const Text('Data'),
),
ElevatedButton(
onPressed: () {
setState(
() => value = AsyncError(
Exception('请求失败'),
StackTrace.current,
),
);
},
child: const Text('Error'),
),
],
),
],
),
),
);
}
}预期结果
应用启动:loading:正在等待结果
点击 Data:data:用户资料已加载
点击 Error:error:Exception: 请求失败
再次点击 Loading:loading:正在等待结果异常文本的具体展示形式可能随异常对象而变化,但状态分支应分别进入 loading、data 和 error。
不要绕过状态直接取值
AsyncData<T> 才保证包含成功数据,AsyncError<T> 保存的是失败信息,而 AsyncLoading<T> 可能还没有可用结果。因此业务代码不应假设每个 AsyncValue<T> 都已经有值,再通过强制读取来决定页面行为。
更稳妥的思路是让消费端显式处理三种结果。这样以后把本地假数据替换成网络请求、数据库读取或 AsyncNotifier 时,状态模型不需要重写,只需要改变产生 AsyncValue 的过程。
什么时候使用 AsyncValue
只要一次操作存在明确的等待、成功和失败过程,AsyncValue<T> 都适合作为它的结果模型,例如用户资料加载、搜索、分页首屏请求或提交表单。对于完全同步、不会失败的普通计数器等状态,则没有必要为了统一形式强行套上异步状态。