跨平台开发 / 系统课时

用 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。

AsyncNotifier 初始加载状态流转

因此,初始加载不需要在 build() 开头手动写 state = const AsyncLoading(),也不需要为了把异常塞进状态而包一层 try/catch。正常返回或抛出异常即可由 Riverpod 转换成对应的 AsyncValue<T>。

完成一个可运行的初始加载

下面用一个内存仓库模拟远程请求。仓库等待 500 毫秒后返回商品名称,ProductsNotifier.build() 负责调用仓库,页面只观察 provider 并渲染不同状态。

dart
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)),
          ],
        ),
      ),
    );
  }
}

预期结果

text
页面打开后先显示约 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 模型上。

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

目录与阅读设置

阅读设置

17

记录一个想法

用 AsyncNotifier 加载初始数据

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

登录哪都通