al_downloader：Flutter 文件下载插件

本文介绍 al_downloader，一个基于 URL 的 Flutter 下载器插件，支持下载任何类型文件并提供便捷的下载管理功能。

al_downloader 简介

al_downloader 是由 jackleemeta 开发的 Flutter 下载插件，基于 flutter_downloader 构建，提供了更简洁的 API 和更强大的下载管理功能。该项目在 GitHub 上拥有 37 stars 和 14 forks，采用 MIT 许可证。

核心定位：A URL-based flutter downloader that supports to download any type of file and automatically manages a lot of things.

核心特性

URL 管理下载任务 - 通过 URL 标识和管理下载任务
简洁的下载状态 - 提供清晰的下载状态反馈
低频次 I/O - 优化文件读写性能
便捷的下载句柄 - 简化下载操作
支持批量下载 - 可同时下载多个文件
自动文件管理 - 无需指定下载路径，自动管理文件
基于 flutter_downloader - 底层使用成熟的下载库

技术栈

语言	占比
Dart	76.2%
C++	10.5%
CMake	9.4%
Ruby	1.4%
HTML	0.9%
Swift	0.8%

安装方法

在 pubspec.yaml 中添加依赖：

yaml

dependencies:
  al_downloader: ^1.8.4

然后执行：

bash

flutter packages get

导入包：

dart

import 'package:al_downloader/al_downloader.dart';

使用方法

初始化

dart

void main() {
  // 初始化下载器
  ALDownloader.initialize();

  // 配置日志打印（可选）
  ALDownloader.configurePrint(true, frequentEnabled: false);

  runApp(MyApp());
}

下载文件

dart

void downloadFile() {
  const url = 'https://example.com/file.pdf';

  ALDownloader.download(
    url,
    directoryPath: directoryPath,  // 可选：指定下载目录
    fileName: fileName,            // 可选：指定文件名
    handlerInterface: ALDownloaderHandlerInterface(
      progressHandler: (progress) {
        // 下载进度回调（0.0 - 1.0）
        print('下载进度: ${(progress * 100).toStringAsFixed(1)}%');
      },
      succeededHandler: () {
        // 下载成功回调
        print('下载成功');
      },
      failedHandler: () {
        // 下载失败回调
        print('下载失败');
      },
      pausedHandler: () {
        // 下载暂停回调
        print('下载已暂停');
      },
    ),
  );
}

批量下载

dart

void batchDownload() {
  final urls = [
    'https://example.com/file1.pdf',
    'https://example.com/file2.pdf',
    'https://example.com/file3.pdf',
  ];

  ALDownloaderBatcher.download(
    urls,
    handlerInterface: ALDownloaderBatcherHandlerInterface(
      progressHandler: (progress) {
        print('批量下载进度: ${(progress * 100).toStringAsFixed(1)}%');
      },
      succeededHandler: () {
        print('所有文件下载成功');
      },
      failedHandler: () {
        print('部分文件下载失败');
      },
    ),
  );
}

文件管理

dart

void manageFiles() async {
  const url = 'https://example.com/file.pdf';

  // 获取文件的物理路径
  final path = await ALDownloaderFileManager.getPhysicalFilePathForUrl(url);
  print('文件路径: $path');

  // 检查文件是否存在
  final exists = await ALDownloaderFileManager.checkFileExistenceForUrl(url);
  print('文件是否存在: $exists');

  // 删除文件
  await ALDownloaderFileManager.removeFileForUrl(url);
}

下载控制

dart

void controlDownload() {
  const url = 'https://example.com/file.pdf';

  // 暂停下载
  ALDownloader.pause(url);

  // 恢复下载
  ALDownloader.resume(url);

  // 取消下载
  ALDownloader.cancel(url);

  // 删除下载任务及文件
  ALDownloader.remove(url);
}

获取下载状态

dart

void checkStatus() async {
  const url = 'https://example.com/file.pdf';

  // 获取下载状态
  final status = await ALDownloader.getStatusForUrl(url);
  print('下载状态: $status');

  // 获取下载进度
  final progress = await ALDownloader.getProgressForUrl(url);
  print('下载进度: $progress');
}

主要 API 分类

类别	功能
ALDownloader	单文件下载、暂停、取消、删除、状态查询
ALDownloaderBatcher	批量下载管理
ALDownloaderFileManager	基于 URL 的文件路径管理

完整示例

dart

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

void main() {
  ALDownloader.initialize();
  ALDownloader.configurePrint(true, frequentEnabled: false);
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: DownloadPage(),
    );
  }
}

class DownloadPage extends StatefulWidget {
  @override
  _DownloadPageState createState() => _DownloadPageState();
}

class _DownloadPageState extends State<DownloadPage> {
  double _progress = 0;
  String _status = '未开始';

  final String _url = 'https://example.com/sample.pdf';

  void _startDownload() {
    ALDownloader.download(
      _url,
      handlerInterface: ALDownloaderHandlerInterface(
        progressHandler: (progress) {
          setState(() {
            _progress = progress;
            _status = '下载中...';
          });
        },
        succeededHandler: () {
          setState(() {
            _status = '下载成功';
          });
        },
        failedHandler: () {
          setState(() {
            _status = '下载失败';
          });
        },
      ),
    );
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('文件下载')),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            Text('状态: $_status'),
            SizedBox(height: 20),
            LinearProgressIndicator(value: _progress),
            SizedBox(height: 10),
            Text('${(_progress * 100).toStringAsFixed(1)}%'),
            SizedBox(height: 40),
            ElevatedButton(
              onPressed: _startDownload,
              child: Text('开始下载'),
            ),
          ],
        ),
      ),
    );
  }
}

注意事项

如果持久化文件被异常手段删除（例如缓存文件夹被业务代码删除），调用 remove 后再调用 download 来重新下载以修复问题。

项目信息

GitHub 仓库：https://github.com/jackleemeta/al_downloader_flutter
Pub.dev：https://pub.dev/packages/al_downloader
最新版本：1.8.4 (2024-03-12)
许可证：MIT
维护者：jackleemeta (jackleemeta@outlook.com)

适用场景

文件下载应用

文档下载器
图片批量下载
视频下载工具

离线功能

离线阅读
缓存管理
预下载资源

更新功能

应用更新
资源更新
增量更新

总结

al_downloader 是一个功能完善、使用简单的 Flutter 下载插件，其核心优势包括：

API 简洁：通过 URL 管理下载，接口直观
功能完整：支持单文件、批量下载，状态管理完善
自动管理：自动处理文件路径和存储
性能优化：低频次 I/O，下载效率高
基于成熟库：底层使用 flutter_downloader，稳定可靠

对于需要在 Flutter 应用中实现文件下载功能的开发者来说，这是一个优秀的选择。

字节笔记本

al_downloader：Flutter 文件下载插件

al_downloader 简介

核心特性

技术栈

安装方法

使用方法

初始化

下载文件

批量下载

文件管理

下载控制

获取下载状态

主要 API 分类

完整示例

注意事项

项目信息

适用场景

文件下载应用

离线功能

更新功能

总结