跨平台开发 / 系统课时
用 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 中调用异步方法,因此父组件重建时不会无意中重复发起任务。
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:
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 可能只是接口合法返回空值。实际项目应根据业务协议分别显示错误提示、空状态或正常内容,而不是把它们统一当成失败。