跨平台开发 / 系统课时

下载文件并显示进度

下载文件并显示进度

下载大文件时,用户通常需要知道任务是否仍在进行以及已经接收了多少数据。本节使用 Dio 的 download 与 onReceiveProgress,把接收字节数同步到 Flutter 页面,并在服务端没有提供总长度时自动退化为不确定进度。

学习目标

  • 使用 Dio.download 将响应体直接保存为文件
  • 使用 onReceiveProgress 更新接收进度
  • 正确处理 total <= 0 的未知总长度响应

下载回调如何驱动页面

Dio.download 会把响应数据持续写入目标文件,同时通过 onReceiveProgress 返回 received 和 total。当服务端提供 Content-Length 时,可以计算 received / total;如果总长度未知,只能确认“已经收到多少字节”,不能可靠计算百分比。

Dio 下载与页面进度更新的数据流

下载到临时目录并更新进度

下面示例下载一个固定大小的测试响应,并保存到系统临时目录。项目需已添加 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 保存状态。应把下载任务提升到独立服务或状态管理层,由页面订阅任务进度;这样页面销毁、重建时,下载状态仍然可恢复。

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

目录与阅读设置

阅读设置

17

记录一个想法

下载文件并显示进度

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

登录哪都通