تحميل ملف في Flutter باستخدام Dio يحتاج مسارًا مناسبًا وحساب تقدم لا يقسم على صفر. المثال القديم الذي يطلب أول مجلد خارجي قد يفشل على منصة لا تعيد قائمة مجلدات. نستخدم هنا مجلد مستندات التطبيق عبر path_provider، ونفصل التنزيل المؤقت عن إعلان نجاح الملف النهائي.
ملف جزئي ثم اسم نهائي
أضف dio 5.11.1 وpath_provider 2.1.6 وpath. المقطع التالي لتطبيقات dart:io وليس لبناء الويب. يكتب التنزيل في امتداد .part، ثم يتحقق من عدم فراغ الملف ويعيد تسميته بعد نجاح العملية. لا تطلق عمليتين متزامنتين إلى الاسم نفسه؛ استخدم اسمًا فريدًا أو سياسة استبدال واضحة.
import 'dart:io';
import 'package:dio/dio.dart';
import 'package:path/path.dart' as paths;
import 'package:path_provider/path_provider.dart';
double? progressRatio(int received, int total) =>
total <= 0 ? null : (received / total).clamp(0.0, 1.0).toDouble();
Future<File> downloadFile({
required Dio dio, required String url, required String fileName,
CancelToken? cancelToken, void Function(double?)? onProgress,
}) async {
if (paths.basename(fileName) != fileName || fileName.isEmpty || fileName == '.' || fileName == '..') {
throw ArgumentError('Use a plain file name');
}
final dir = await getApplicationDocumentsDirectory();
final target = File(paths.join(dir.path, fileName));
final partial = File('${target.path}.part');
try {
await dio.download(url, partial.path, cancelToken: cancelToken,
onReceiveProgress: (received, total) => onProgress?.call(progressRatio(received, total)));
if (await partial.length() == 0) throw const FormatException('Empty file');
return await partial.rename(target.path);
} catch (_) {
if (await partial.exists()) await partial.delete();
rethrow;
}
}
Future<Response<Object?>> uploadFile(Dio dio, String endpoint, String path,
{CancelToken? cancelToken, void Function(double?)? onProgress}) async {
final form = FormData.fromMap({
'file': await MultipartFile.fromFile(path, filename: paths.basename(path)),
});
return dio.post<Object?>(endpoint, data: form, cancelToken: cancelToken,
onSendProgress: (sent, total) => onProgress?.call(progressRatio(sent, total)));
}
تقدم غير محدد وإلغاء الطلب
قد لا يرسل الخادم الحجم الإجمالي. ترجع progressRatio قيمة null عند total غير صالح، وهو ما يصلح لمؤشر تقدم غير محدد بدل NaN أو نسبة خاطئة. عند وجود الحجم تقيد النسبة بين صفر وواحد. مرر CancelToken لإلغاء الطلب عند اختيار المستخدم، وميّز الإلغاء عن فشل الشبكة في رسالة الشاشة.
مجلد التطبيق ليس معرض الهاتف
وجود الملف في getApplicationDocumentsDirectory لا يعني ظهوره في معرض الصور أو مجلد التنزيلات العام. إذا كان المستخدم يريد تصديرًا، استخدم مسار حفظ أو واجهة مشاركة مناسبة للمنصة. لا تطلب MANAGE_EXTERNAL_STORAGE لمجرد حفظ ملف داخل مساحة التطبيق، ولا تستخدم مسار Android ثابتًا على iOS.
تحقق من الملف قبل فتحه
افحص نوع المحتوى وحجمه وفق طبيعة الملف؛ عدم الفراغ وحده لا يثبت أن الملف PDF أو صورة صحيحة. قد يعيد الخادم صفحة HTML باسم zip عند خطأ المصادقة. استخدم HTTPS ومصدرًا موثوقًا، ولا تفتح ملفًا تلقائيًا لمجرد اكتمال التنزيل.
في الواجهة افحص mounted قبل setState بعد await، وعطّل الزر أثناء العمل. اختبر فشل الشبكة والإلغاء والحجم غير المعروف واسم ملف يحتوي مسارًا وإعادة التنزيل. المكوّن يعيد الاستثناء بعد تنظيف الملف الجزئي بدل إظهار رسالة نجاح من whenComplete.
مراجع التنفيذ
لإكمال هذا الجزء، انتقل إلى رفع وتحميل الملفات في Flutter باستخدام Dio وعرض التقدم، ثم طبّق الربط الذي يناسب بنية مشروعك.







