flutter pub add background_downloader根據套件公開資料產生的選型評估，僅供參考。
一個跨平台的 Flutter 套件，可在 Android、iOS、macOS、Windows 和 Linux 上實現背景檔案下載與上傳。它允許開發者定義下載/上傳任務，排隊執行並即時監控進度。設計注重可靠性與效率，能處理網路中斷，並在應用重啟後繼續任務。適用於需要大量檔案傳輸而不阻塞 UI 的應用。
以下為關聯原始碼儲存庫的 README 原文快照，最新內容請造訪原始碼儲存庫。
A robust, multi-platform background file transfer plugin for Flutter supporting background downloads, uploads, and data tasks across iOS, Android, MacOS, Windows, and Linux.
Uses native URLSession on iOS and MacOS, and DownloadWorker (WorkManager) / JobService (UIDT) on Android, ensuring transfers continue even when your app is in the background or terminated by the OS.
The easiest and most powerful way to use background_downloader is via the Transfer API.
On app startup (e.g. in main() or your top-level initState()), call FileDownloader().start(autoCleanDatabase: true) to activate persistent database tracking, automatically purge old task records, and reconcile transfers that completed or were interrupted while the app was suspended or closed. Then simply define a DownloadTask or UploadTask, start it using FileDownloader().transfers.start, and receive a reactive Transfer handle:
// 1. Activate database tracking & auto-cleanup on app launch (recommended)
await FileDownloader().start(autoCleanDatabase: true);
// 2. Configure notifications (recommended for userInitiated / UIDT tasks)
FileDownloader().configureNotification(
running: const TaskNotification('Downloading', '{filename}'),
complete: const TaskNotification('Complete', '{filename}'),
progressBar: true,
tapOpensFile: true,
);
// 3. Define the task with smart hints
final task = DownloadTask(
url: 'https://example.com/large_video.mp4',
filename: 'video.mp4',
transferHints: {TransferHint.userInitiated, TransferHint.largeFile},
);
// 4. Start the transfer
final transfer = await FileDownloader().transfers.start(task);
// 5. Directly await the completed File:
final file = await transfer.file;
print('Downloaded to: ${file.path}');
Transfer?transfer.file for the completed File, transfer.result for the TaskStatusUpdate, or transfer.responseBody for server response text.ValueNotifier bindings for Flutter widgets: transfer.progressNotifier (clean 0.0–1.0), transfer.statusNotifier, transfer.networkSpeedNotifier, transfer.timeRemainingNotifier, and transfer.notificationTapNotifier.TransferProgressBar, TransferButton, and TransferListTile.await transfer.pause(), await transfer.resume(), await transfer.cancel().FileDownloader().transfers.startAll(tasks, onProgress: ...).TransferHint (userInitiated, largeFile, smallFile, lowPriority, useSuggestedFilename, binaryUpload) to configure optimal priority, Android 14+ UIDT, and pause resilience automatically.transfer.notificationTapNotifier or open downloaded files automatically with tapOpensFile: true.FileDownloader.scoped('my_feature').stallTimeout).👉 Read the complete Transfers Guide
For specialized workflows or legacy integration, FileDownloader continues to provide direct lower-level methods:
download)Execute a task and wait for completion in a single call with inline callbacks:
final result = await FileDownloader().download(
task,
onProgress: (progress) => print('Progress: ${progress * 100}%'),
onStatus: (status) => print('Status: $status'),
);
if (result.status == TaskStatus.complete) {
print('Download finished!');
}
enqueue / enqueueAll)For pipeline architectures where you monitor tasks centrally via a global stream or callbacks:
// 1. Listen centrally to task updates (typically in initState)
FileDownloader().updates.listen((update) {
switch (update) {
case TaskStatusUpdate():
print('Task ${update.task.taskId} status: ${update.status}');
case TaskProgressUpdate():
print('Task ${update.task.taskId} progress: ${update.progress * 100}%');
}
});
// 2. Start the downloader and activate persistent database tracking
FileDownloader().start();
// 3. Enqueue background tasks
final enqueued = await FileDownloader().enqueue(task);
To ensure file paths work robustly across platform restarts (especially on iOS and Android where container paths can change between app launches), the downloader uses a combination of BaseDirectory, directory (subdirectory) and filename:
BaseDirectory: One of .applicationDocuments, .temporary, .applicationSupport, or .applicationLibrary.directory: An optional subdirectory within the base directory.filename: The name of the file (or DownloadTask.suggestedFilename / '?' to use the server's Content-Disposition header).See File Storage for details on shared and scoped storage.
Check the Topic Index or specific guides:
Transfer handles, reactive notifiers, UI widgets, batches, and scoping.No setup is required for Windows or Linux.
Requires Kotlin 2.1.0 or above. For modern Flutter projects, ensure your android/settings.gradle has:
plugins {
id "org.jetbrains.kotlin.android" version "2.1.0" apply false
}
No special setup is required. By default iOS requires HTTPS connections (see Apple ATS Configuration if HTTP is required).
Add the client network entitlement to macos/Runner/DebugProfile.entitlements and macos/Runner/Release.entitlements:
<key>com.apple.security.network.client</key>
<true/>
allowPause: true (or TransferHint.largeFile / userInitiated), which automatically resumes across 9-minute cycles, or set priority: 0 on Android 14+ to use UIDT (see parameters.md).依賴清單 8 項
^2.6.0^1.15.0>=6.1.3 <8.0.0^1.1.0^1.0.2^2.0.0^1.8.1^2.0.2