跨平台开发 / 系统课时

监听上传进度

监听上传进度

上传文件时,页面不能只显示“处理中”。本节用 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 和状态,否则多个请求的回调会互相覆盖,页面看到的百分比就失去含义。

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

目录与阅读设置

阅读设置

17

记录一个想法

监听上传进度

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

登录哪都通