跨平台开发 / 系统课时

用 FutureBuilder 展示异步结果

用 FutureBuilder 展示异步结果

接口请求、文件读取和延时计算都不会立刻得到结果,界面必须在“等待、成功、失败”之间切换。FutureBuilder 可以根据一个 Future 的执行状态提供不同的 AsyncSnapshot,让异步结果直接映射为界面。本课将完成一个可重试示例,并避免在 build 中重复创建异步任务。

学习目标

  • 能根据 AsyncSnapshot 区分等待、成功和失败状态
  • 会把 Future 的创建与 build 过程分离
  • 能实现重新触发异步任务并更新界面

FutureBuilder 在解决什么问题

普通 Widget 的 build 是同步的,但网络请求等操作会稍后完成。如果在请求结束前直接读取结果,界面既不知道该显示加载状态,也很难统一处理异常。FutureBuilder<T> 接收一个 Future<T>,并在 Future 状态变化时通过 builder 提供新的快照。

最常见的判断顺序是先检查 snapshot.connectionState,等待时显示进度指示器;完成后再判断 snapshot.hasError;没有错误时读取 snapshot.data。这样同一个区域就能随着异步任务推进而显示不同内容。

完成等待、成功和失败界面

下面示例提供两个按钮:一个触发成功任务,一个触发失败任务。_future 在 initState 和按钮事件中创建,而不是在 build 中调用异步方法,因此父组件重建时不会无意中重复发起任务。

dart
import 'package:flutter/material.dart';

void main() {
  runApp(const MaterialApp(home: FutureDemoPage()));
}

class FutureDemoPage extends StatefulWidget {
  const FutureDemoPage({super.key});

  @override
  State<FutureDemoPage> createState() => _FutureDemoPageState();
}

class _FutureDemoPageState extends State<FutureDemoPage> {
  late Future<String> _future;

  @override
  void initState() {
    super.initState();
    _future = _loadMessage(shouldFail: false);
  }

  Future<String> _loadMessage({required bool shouldFail}) async {
    await Future<void>.delayed(const Duration(seconds: 1));

    if (shouldFail) {
      throw Exception('模拟请求失败');
    }

    return '数据加载成功';
  }

  void _reload({required bool shouldFail}) {
    setState(() {
      _future = _loadMessage(shouldFail: shouldFail);
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('FutureBuilder Demo')),
      body: Center(
        child: FutureBuilder<String>(
          future: _future,
          builder: (context, snapshot) {
            if (snapshot.connectionState == ConnectionState.waiting) {
              return const CircularProgressIndicator();
            }

            if (snapshot.hasError) {
              return Text('加载失败:${snapshot.error}');
            }

            return Text(snapshot.data ?? '没有数据');
          },
        ),
      ),
      bottomNavigationBar: Padding(
        padding: const EdgeInsets.all(16),
        child: Row(
          children: [
            Expanded(
              child: ElevatedButton(
                onPressed: () => _reload(shouldFail: false),
                child: const Text('加载成功'),
              ),
            ),
            const SizedBox(width: 12),
            Expanded(
              child: ElevatedButton(
                onPressed: () => _reload(shouldFail: true),
                child: const Text('加载失败'),
              ),
            ),
          ],
        ),
      ),
    );
  }
}

预期结果

应用启动后先显示约 1 秒的圆形加载指示器,随后显示“数据加载成功”。点击“加载失败”后再次出现加载指示器,约 1 秒后显示包含“模拟请求失败”的错误文本;点击“加载成功”则恢复为成功结果。

不要在 build 中创建 Future

下面这种写法看起来更短,却把异步任务创建放进了 build:

dart
FutureBuilder<String>(
  future: _loadMessage(shouldFail: false),
  builder: (context, snapshot) {
    return const SizedBox.shrink();
  },
)

这是片段示例,依赖前一个完整示例中的 _loadMessage 方法。它的问题是 build 可能因为父组件、主题、屏幕尺寸或其他状态变化而被多次调用,每次都会得到新的 Future,从而让任务重新开始。

正确做法是像主示例那样,把 Future 保存为状态字段,并在 initState、依赖真正变化时,或用户明确执行“重试”操作时替换它。这样可以让界面重建和异步任务生命周期保持分离。

处理真实接口时的边界

把示例中的延时任务换成 HTTP 请求后,FutureBuilder 仍然只负责“根据 Future 结果构建界面”,不应承担数据解析、缓存、鉴权等所有业务职责。复杂页面通常会把请求逻辑移到独立服务或状态管理层,再把最终的 Future 或状态结果交给界面。

还要区分“没有数据”和“请求失败”。snapshot.hasError 表示 Future 以异常结束,而 snapshot.data == null 可能只是接口合法返回空值。实际项目应根据业务协议分别显示错误提示、空状态或正常内容,而不是把它们统一当成失败。

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

目录与阅读设置

阅读设置

17

记录一个想法

用 FutureBuilder 展示异步结果

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

登录哪都通