跨平台开发 / 系统课时
下载文件并显示进度
下载文件并显示进度
下载大文件时,用户通常需要知道任务是否仍在进行以及已经接收了多少数据。本节使用 Dio 的 download 与 onReceiveProgress,把接收字节数同步到 Flutter 页面,并在服务端没有提供总长度时自动退化为不确定进度。
学习目标
- 使用
Dio.download将响应体直接保存为文件 - 使用
onReceiveProgress更新接收进度 - 正确处理
total <= 0的未知总长度响应
下载回调如何驱动页面
Dio.download 会把响应数据持续写入目标文件,同时通过 onReceiveProgress 返回 received 和 total。当服务端提供 Content-Length 时,可以计算 received / total;如果总长度未知,只能确认“已经收到多少字节”,不能可靠计算百分比。

下载到临时目录并更新进度
下面示例下载一个固定大小的测试响应,并保存到系统临时目录。项目需已添加 dio 依赖。生产应用若要把文件长期保存到用户可访问目录,还需要按目标平台选择合适目录并处理存储权限。
dart
import 'dart:io';
import 'package:dio/dio.dart';
import 'package:flutter/material.dart';
void main() {
runApp(const MaterialApp(home: DownloadProgressPage()));
}
class DownloadProgressPage extends StatefulWidget {
const DownloadProgressPage({super.key});
@override
State<DownloadProgressPage> createState() => _DownloadProgressPageState();
}
class _DownloadProgressPageState extends State<DownloadProgressPage> {
final Dio _dio = Dio();
double? _progress;
int _received = 0;
int _total = 0;
String _status = '等待下载';
Future<void> _download() async {
final savePath = '${Directory.systemTemp.path}/sample.bin';
setState(() {
_progress = 0;
_received = 0;
_total = 0;
_status = '正在下载';
});
try {
await _dio.download(
'https://httpbin.org/bytes/262144',
savePath,
onReceiveProgress: (received, total) {
if (!mounted) return;
setState(() {
_received = received;
_total = total;
_progress = total > 0 ? received / total : null;
});
},
);
if (!mounted) return;
setState(() {
_progress = 1;
_status = '下载完成:$savePath';
});
} on DioException catch (e) {
if (!mounted) return;
setState(() {
_status = '下载失败:${e.type.name}';
});
}
}
@override
Widget build(BuildContext context) {
final percent = _progress == null
? '未知总长度'
: '${(_progress! * 100).toStringAsFixed(0)}%';
return Scaffold(
appBar: AppBar(title: const Text('下载进度')),
body: Padding(
padding: const EdgeInsets.all(24),
child: Column(
mainAxisSize: MainAxisSize.min,
children: [
LinearProgressIndicator(value: _progress),
const SizedBox(height: 12),
Text('$_status\n$percent · $_received / $_total bytes'),
const SizedBox(height: 12),
FilledButton(
onPressed: _download,
child: const Text('开始下载'),
),
],
),
),
);
}
}预期结果
text
点击“开始下载”后,页面持续更新 received/total 字节数和进度条;下载成功后状态中显示临时文件路径,并最终显示 100%。这里的 total 可能是 -1。这通常意味着响应没有可用于计算总大小的信息,而不是下载失败。此时示例把 _progress 设为 null,让进度条显示为不确定状态,同时继续展示 _received,用户仍能确认数据正在到达。
进度显示与文件保存要分开判断
“进度达到 100%”只说明响应字节已接收完成,不等于文件一定满足业务要求。重要下载任务还应在请求完成后检查文件是否存在、大小是否合理,必要时再校验哈希值。若要支持取消任务,可给 download 传入 CancelToken,并把“取消”作为独立状态展示,避免与网络失败混为一类。
页面离开后仍要继续下载时,不应只依赖当前 Widget 的 setState 保存状态。应把下载任务提升到独立服务或状态管理层,由页面订阅任务进度;这样页面销毁、重建时,下载状态仍然可恢复。
按自己的节奏,确认真正理解。