Flutter文件下载管理插件fl_downloader的使用

插件介绍

fl_downloader 是一个用于Flutter应用程序的插件，它允许您通过原生功能下载文件。在Android上，它使用系统的DownloadManager服务；在Windows上，它使用BITS（Background Intelligent Transfer Service）将文件下载到用户的Downloads文件夹中；在iOS上，它使用URLSession将文件下载到App Documents文件夹。

• Pub Version

iOS配置

如果您不想让用户在Files应用中看到已下载的文件，则无需特殊配置。 如果希望用户能在Files应用中查看已下载的文件，请在您的info.plist文件中添加以下行：

<key>LSSupportsOpeningDocumentsInPlace</key>
<true/>
<key>UIFileSharingEnabled</key>
<true/>

Android配置

对于Android 10+，无需特殊配置。 如果您的应用支持Android 9（API 28）或更低版本，在调用download()之前必须调用requestPermission()并检查权限状态。

注意：此插件期望compileSdk是最新版本的Android SDK，例如：

android {
    compileSdk 34

    [...]
}

Windows配置

Windows平台无需特殊配置。

需要注意的是，了解BITS的限制和测试其使用情况非常重要，相关文档如下：

• About BITS
• HTTP Requirements for BITS Downloads
• BITSAdmin tool

示例代码

下面是一个完整的示例demo，展示了如何使用fl_downloader插件进行文件下载，并实时更新下载进度、处理不同状态等。

import 'dart:async';

import 'package:fl_downloader/fl_downloader.dart';
import 'package:flutter/material.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatefulWidget {
  const MyApp({super.key});

  @override
  State<MyApp> createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  final TextEditingController fileNameController = TextEditingController(
    text: 'test.pdf',
  );
  final TextEditingController urlController = TextEditingController(
    text:
        'https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf',
  );

  int progress = 0;
  dynamic downloadId;
  String? status;
  late StreamSubscription progressStream;

  @override
  void initState() {
    FlDownloader.initialize();
    progressStream = FlDownloader.progressStream.listen((event) {
      if (event.status == DownloadStatus.successful) {
        debugPrint('event.progress: ${event.progress}');
        setState(() {
          progress = event.progress;
          downloadId = event.downloadId;
          status = event.status.name;
        });
        // 自动打开下载完成后的文件
        FlDownloader.openFile(filePath: event.filePath);
      } else if (event.status == DownloadStatus.running) {
        debugPrint('event.progress: ${event.progress}');
        setState(() {
          progress = event.progress;
          downloadId = event.downloadId;
          status = event.status.name;
        });
      } else if (event.status == DownloadStatus.failed) {
        debugPrint('event: $event');
        setState(() {
          progress = event.progress;
          downloadId = event.downloadId;
          status = event.status.name;
        });
      } else if (event.status == DownloadStatus.paused) {
        debugPrint('Download paused');
        setState(() {
          progress = event.progress;
          downloadId = event.downloadId;
          status = event.status.name;
        });
        // 在暂停后重新附加下载进度
        Future.delayed(
          const Duration(milliseconds: 250),
          () => FlDownloader.attachDownloadProgress(event.downloadId),
        );
      } else if (event.status == DownloadStatus.pending) {
        debugPrint('Download pending');
        setState(() {
          progress = event.progress;
          downloadId = event.downloadId;
          status = event.status.name;
        });
      }
    });
    super.initState();
  }

  @override
  void dispose() {
    progressStream.cancel();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      theme: ThemeData.light(useMaterial3: true),
      darkTheme: ThemeData.dark(useMaterial3: true),
      home: Scaffold(
        appBar: AppBar(
          title: const Text('FlDownloader example app'),
        ),
        body: Column(
          children: [
            if (progress > 0 && progress < 100)
              LinearProgressIndicator(
                value: progress / 100,
                color: Colors.orange,
              ),
            Padding(
              padding: const EdgeInsets.symmetric(horizontal: 16, vertical: 8),
              child: TextField(
                controller: urlController,
                decoration: const InputDecoration(
                  label: Text('URL'),
                  border: OutlineInputBorder(),
                ),
              ),
            ),
            Padding(
              padding: const EdgeInsets.symmetric(horizontal: 16, vertical: 8),
              child: TextField(
                controller: fileNameController,
                decoration: const InputDecoration(
                  label: Text('File name'),
                  border: OutlineInputBorder(),
                ),
              ),
            ),
            const Spacer(),
            Text(
              'Download id: $downloadId\n'
              'Status: $status\n'
              'Progress: $progress%',
            ),
            const Spacer(),
          ],
        ),
        floatingActionButton: Row(
          mainAxisAlignment: MainAxisAlignment.end,
          children: [
            FloatingActionButton(
              backgroundColor: Colors.red[300],
              child: const Icon(Icons.close),
              onPressed: () async {
                final cancelList = [downloadId];
                final cancelled = await FlDownloader.cancel(cancelList);
                if (cancelled == cancelList.length) {
                  setState(() {
                    progress = 0;
                    downloadId = null;
                    status = 'All downloads cancelled';
                  });
                } else {
                  setState(() {
                    progress = 0;
                    downloadId = null;
                    status = 'Cancelled $cancelled downloads from the list';
                  });
                }
              },
            ),
            const SizedBox(width: 10),
            FloatingActionButton(
              child: const Icon(Icons.download_sharp),
              onPressed: () async {
                final permission = await FlDownloader.requestPermission();
                if (permission == StoragePermissionStatus.granted) {
                  await FlDownloader.download(
                    urlController.text,
                    fileName: fileNameController.text,
                  );
                } else {
                  debugPrint('Permission denied =(');
                }
              },
            ),
          ],
        ),
      ),
    );
  }
}

这个示例提供了一个简单的界面，允许用户输入文件的URL和名称，然后点击按钮开始下载。同时，它还显示了下载进度条以及当前的下载状态。当下载完成后，会尝试自动打开下载的文件。此外，也提供了取消下载的功能。