شارك المقالة
رفع وتحميل الملفات في Flutter باستخدام Dio وعرض التقدم

رفع وتحميل الملفات في Flutter باستخدام Dio وعرض التقدم

تعلّم رفع وتحميل الملفات في Flutter باستخدام Dio وMultipartFile، مع إلغاء الطلب ومعالجة الحجم غير المعروف والتحقق من النجاح قبل…

رفع وتحميل الملفات في Flutter باستخدام Dio يجمع عمليتين مختلفتين: تنزيل bytes من الخادم ورفع ملف إلى endpoint يقبل multipart. لا تعلن النجاح من whenComplete لأنه يعمل بعد الفشل أيضًا. نستخدم دوال تعيد Future وندع الواجهة تختار عرض التقدم والإلغاء والإشعار بعد التأكد من النتيجة.

خدمة نقل ملفات مستقلة

أضف Dio وpath_provider وpath. الدالة uploadFile ترسل الحقل file، وهو اسم توضيحي يجب أن يطابق عقد الخادم. لا تستخدم عنوان رفع مجهولًا أو خدمة قديمة من مقال تعليمي لإرسال ملفات المستخدمين. أنشئ endpoint مملوكًا لك وتحقق في الخادم من النوع والحجم والصلاحيات.

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)));
}

التقدم ليس تأكيد معالجة الخادم

onSendProgress يوضح تقدم إرسال bytes، لكنه لا يثبت أن الخادم قبِل الملف أو أنهى معالجته. انتظر الاستجابة وافحص جسمها أو رمزها حسب العقد قبل عرض «تم الرفع». قد تبلغ النسبة 100% ثم يعيد الخادم رفضًا؛ يجب أن تبقى حالة الانتظار واضحة خلال معالجة النتيجة.

الإلغاء والصلاحيات والمسار

مرر CancelToken مستقلًا لكل عملية، ولا تعيد استخدام نموذج FormData مستهلكًا لإعادة محاولة دون بناء جديد. لا تفترض أن FilePicker يعيد path على كل منصة؛ الويب قد يحتاج bytes أو stream بدل MultipartFile.fromFile. المثال هنا موجه لتطبيقات الهاتف وسطح المكتب التي تدعم dart:io.

تُحفظ التنزيلات داخل مجلد التطبيق دون الحاجة لصلاحية وصول شامل للتخزين. إذا أردت ملفًا عامًا أو في المعرض فاستخدم آلية المنصة المناسبة. تحقق من الاسم لتجنب التعامل مع مسار غير مقصود، ونظف الملف الجزئي بعد الإلغاء أو الخطأ دون حذف ملف مستخدم سابق.

الإشعارات واختبار الفشل

يمكن ربط onProgress بإشعار محلي بعد إعداد الحزمة وصلاحياتها، لكن ذلك منفصل عن منطق النقل. لا تنشئ Plugin جديدًا وتعرض إشعارًا عالي الأولوية لكل byte؛ حدّث على فترات مناسبة، وألغِ إشعار التقدم عند انتهاء العملية. اختبر رفض الخادم بعد 100%، وانقطاع الشبكة، والإلغاء، والحجم غير المعروف، وعدم اختيار ملف أصلًا.

مراجع التنفيذ

لإكمال هذا الجزء، انتقل إلى تحميل ملف في Flutter باستخدام Dio مع نسبة التقدم والإلغاء، ثم طبّق الربط الذي يناسب بنية مشروعك.

صور الشرح السابق

How to downloading and uploading in Flutter كيفية الرفع والتحميل من الانترنت باستخدام مكتبة dio مع تحديد مدة التحميل
شاهد أيضًا
مقالات ذات صلة
🚫 مانع الإعلانات مفعل

يجب إيقاف مانع الإعلانات لاستكمال تصفح الموقع