跨平台开发 / 系统课时
监听上传进度
监听上传进度
上传文件时,页面不能只显示“处理中”。本节用 Dio 的 onSendProgress 获取已发送字节数与请求总字节数,计算 0~1 的进度值,并把它绑定到 Flutter 进度条。示例还处理了总长度未知和组件已销毁两类边界。
学习目标
- 使用
onSendProgress读取sent与total - 将字节进度转换为可绑定到页面的比例
- 避免除零和异步回调更新已销毁页面
上传进度来自哪里
Dio 在请求体持续写入网络时,会调用 onSendProgress。回调中的 sent 表示已经写出的字节数,total 表示本次请求体的总字节数。总长度可用时,进度可按 sent / total 计算;若 total <= 0,就不能计算百分比,应改为不确定进度。

在页面中绑定上传比例
下面示例会先在系统临时目录生成一个 2 MiB 文件,再以 multipart/form-data 上传到测试接口。项目需已添加 dio 依赖。真实业务中,只需把临时文件路径替换为用户选择的文件路径即可。
dart
import 'dart:io';
import 'package:dio/dio.dart';
import 'package:flutter/material.dart';
void main() {
runApp(const MaterialApp(home: UploadProgressPage()));
}
class UploadProgressPage extends StatefulWidget {
const UploadProgressPage({super.key});
@override
State<UploadProgressPage> createState() => _UploadProgressPageState();
}
class _UploadProgressPageState extends State<UploadProgressPage> {
final Dio _dio = Dio();
double? _progress;
String _status = '等待上传';
Future<void> _upload() async {
final file = File('${Directory.systemTemp.path}/upload-demo.bin');
await file.writeAsBytes(List<int>.filled(2 * 1024 * 1024, 65));
setState(() {
_progress = 0;
_status = '正在上传';
});
try {
final formData = FormData.fromMap({
'file': await MultipartFile.fromFile(
file.path,
filename: 'upload-demo.bin',
),
});
await _dio.post(
'https://httpbin.org/post',
data: formData,
onSendProgress: (sent, total) {
if (!mounted) return;
setState(() {
_progress = total > 0 ? sent / total : null;
});
},
);
if (!mounted) return;
setState(() {
_progress = 1;
_status = '上传完成';
});
} 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 · $percent'),
const SizedBox(height: 12),
FilledButton(
onPressed: _upload,
child: const Text('开始上传'),
),
],
),
),
);
}
}预期结果
text
点击“开始上传”后,进度条随已发送字节增长;总长度已知时显示 0%~100%,请求成功后显示“上传完成 · 100%”。如果接口没有返回可用的请求总长度,就不要把 total 强行当作百分比基数。示例把 _progress 设为 null,LinearProgressIndicator 会进入不确定进度模式,比显示错误百分比更可靠。
把进度提供给更复杂的页面
当上传逻辑不在当前 StatefulWidget 内时,核心数据仍然只有“当前比例、状态、错误”。可以把 sent 和 total 转换后的比例写入 ValueNotifier<double?>、状态管理对象或业务层回调,再由页面监听。
同一页面同时上传多个文件时,不应共用一个 _progress。应按任务 ID 保存每个文件自己的 sent、total 和状态,否则多个请求的回调会互相覆盖,页面看到的百分比就失去含义。
按自己的节奏,确认真正理解。