跨平台开发 / 系统课时
用 AsyncNotifier 加载初始数据
用 AsyncNotifier 加载初始数据
页面首次进入时常要先读取接口、数据库或缓存,再决定显示内容。AsyncNotifier 把这段初始化放进 build(),并把等待、成功和失败统一暴露为 AsyncValue。这样 UI 不需要自己维护 isLoading、error 和数据三套字段。
学习目标
- 在
AsyncNotifier.build()中执行异步初始化 - 理解初始加载期间
AsyncValue的 loading、data 与 error 状态 - 在 Flutter 页面中用
ref.watch和when渲染统一异步状态
build 是异步状态的入口
AsyncNotifier<T> 的 build() 可以返回 Future<T>。Provider 首次被监听时,Riverpod 会执行 build():Future 未完成时对外是 loading,成功返回后变为 data,抛出异常则变为 error。

因此,初始加载不需要在 build() 开头手动写 state = const AsyncLoading(),也不需要为了把异常塞进状态而包一层 try/catch。正常返回或抛出异常即可由 Riverpod 转换成对应的 AsyncValue<T>。
完成一个可运行的初始加载
下面用一个内存仓库模拟远程请求。仓库等待 500 毫秒后返回商品名称,ProductsNotifier.build() 负责调用仓库,页面只观察 provider 并渲染不同状态。
import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
class ProductRepository {
Future<List<String>> fetchProducts() async {
await Future<void>.delayed(const Duration(milliseconds: 500));
return ['键盘', '鼠标', '显示器'];
}
}
final productRepositoryProvider = Provider<ProductRepository>((ref) {
return ProductRepository();
});
final productsProvider =
AsyncNotifierProvider<ProductsNotifier, List<String>>(ProductsNotifier.new);
class ProductsNotifier extends AsyncNotifier<List<String>> {
@override
Future<List<String>> build() async {
final repository = ref.watch(productRepositoryProvider);
return repository.fetchProducts();
}
}
void main() {
runApp(
const ProviderScope(
child: MaterialApp(home: ProductsPage()),
),
);
}
class ProductsPage extends ConsumerWidget {
const ProductsPage({super.key});
@override
Widget build(BuildContext context, WidgetRef ref) {
final products = ref.watch(productsProvider);
return Scaffold(
appBar: AppBar(title: const Text('商品')),
body: products.when(
loading: () => const Center(
child: CircularProgressIndicator(),
),
error: (error, stackTrace) => Center(
child: Text('加载失败:$error'),
),
data: (items) => ListView(
children: [
for (final item in items) ListTile(title: Text(item)),
],
),
),
);
}
}预期结果
页面打开后先显示约 500 毫秒的加载指示器。
随后列表显示:
键盘
鼠标
显示器实际延迟会取决于真实数据源。示例中的 500 毫秒只是为了让 loading 状态可见。
UI 只消费 AsyncValue
ref.watch(productsProvider) 得到的是 AsyncValue<List<String>>,而不是裸 List<String>。这使页面能够用同一个对象处理三条路径:等待时显示进度,成功时显示列表,失败时显示错误信息。
这种结构比在 Widget 中维护 bool isLoading、Object? error、List<String> items 更可靠,因为三个字段可能出现互相矛盾的组合,例如已经有错误却仍然标记为加载中。AsyncValue 把合法的异步状态组合收敛成统一模型。
build 中应该放什么
build() 适合放“这个状态首次需要怎样得到”的逻辑,例如读取远程列表、加载本地缓存,或者先读取依赖再发起请求。它也可以通过 ref.watch 声明依赖;依赖变化时,Riverpod 可以重新计算该异步状态。
不要把需要用户点击才执行的“保存”“删除”“提交”塞进 build()。这类操作应写成 AsyncNotifier 的公开方法,由 UI 使用 ref.read(productsProvider.notifier) 调用。build() 保持为初始状态来源,后续业务动作保持为显式方法,状态职责会更清楚。
初始化失败时的行为
如果真实仓库在 build() 中抛出异常,Riverpod 会把该次初始化表示为 AsyncError,页面的 error 分支会接收到错误对象和堆栈。这里不需要为了“转换成 error 状态”而吞掉异常;只有当你确实要把某类异常转换成业务结果时,才在数据层或 Notifier 中做针对性处理。
把异步初始化集中到 build() 后,Notifier 负责“怎样得到数据”,UI 负责“不同异步状态怎样显示”。这条边界能让首次加载、错误展示和后续刷新都建立在同一个 AsyncValue 模型上。