跨平台开发 / 系统课时

在页面中渲染异步状态

在页面中渲染异步状态

拿到 AsyncValue 只是异步状态管理的一半,另一半是让用户始终知道页面正在发生什么。本节把 AsyncNotifier 的 loading、data、error 三个分支完整映射到 Flutter 界面,并加入失败后的重试路径。

学习目标

  • 使用 AsyncValue.when 为三种异步结果构建不同界面
  • 在 AsyncNotifier 执行期间显示加载、成功和错误反馈
  • 为失败状态提供可操作的重试入口

先把三种页面反馈补齐

异步页面最容易遗漏的是失败分支。只显示进度条和成功内容时,一旦请求抛出异常,用户既不知道发生了什么,也没有恢复入口。

一个完整页面至少需要明确三种反馈:loading 阶段告诉用户仍在处理;data 阶段渲染真正内容;error 阶段说明操作失败,并在适合重试的场景提供按钮。when 正好要求调用方分别处理这三条路径。

用 AsyncNotifier 驱动完整页面

下面示例不依赖代码生成。ProfileNotifier 首次加载成功后,可以主动触发一次失败;错误页面再通过“重新加载”恢复到成功状态。这样能够实际观察三种 UI 分支如何切换。

dart
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('重新加载'),
              ),
            ],
          ),
        ),
      ),
    );
  }
}

预期结果

text
启动后:先显示圆形加载指示器,约 600 毫秒后显示“欢迎,Ada Lovelace”。
点击“模拟加载失败”:再次显示加载指示器,随后进入错误页面。
点击“重新加载”:显示加载指示器,随后恢复为“欢迎,Ada Lovelace”。

为什么更新前先进入 Loading

reload 先把 state 设置为 AsyncLoading,页面就会立即获得新的状态并显示进度反馈。异步函数结束后,AsyncValue.guard 会把返回值包装成 AsyncData,或者把抛出的异常包装成 AsyncError,避免在每个请求方法中重复编写 try、catch 和状态赋值。

这种写法尤其适合用户主动点击刷新、重试或提交后需要明确等待反馈的操作。页面只观察 provider,不需要知道请求内部用了 HTTP、数据库还是其他数据源。

错误页面应该提供恢复路径

示例没有把异常对象原样显示给最终用户,而是给出“资料加载失败,请稍后重试”的稳定提示。异常和堆栈更适合交给日志与监控系统;页面应告诉用户当前结果以及下一步能做什么。

对于无网络、服务暂时不可用等可恢复问题,可以提供重试按钮。权限不足、参数非法等无法通过重复请求解决的问题,则应给出相应说明,而不是让用户无限重试。

检查页面是否真正完整

验收异步页面时,不要只验证正常返回数据的路径。至少实际触发一次 loading、一次成功和一次失败,并确认失败后能够回到正常状态。只要这三条路径都由同一个 AsyncValue 驱动,页面状态与业务状态就能保持一致,后续替换真实数据源时也更容易维护。

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

目录与阅读设置

阅读设置

17

记录一个想法

在页面中渲染异步状态

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

登录哪都通