تحميل الملفات باستخدام Cloud Storage على Flutter

يسمح لك Cloud Storage for Firebase بتحميل الملفات بسرعة وسهولة إلى مجموعة Cloud Storage التي توفرها وتديرها Firebase.

تحميل الملفات

لتحميل ملف إلى Cloud Storage، عليك أولاً إنشاء مرجع للمسار الكامل للملف، بما في ذلك اسم الملف.

// Create a storage reference from our app
final storageRef = FirebaseStorage.instance.ref();

// Create a reference to "mountains.jpg"
final mountainsRef = storageRef.child("mountains.jpg");

// Create a reference to 'images/mountains.jpg'
final mountainImagesRef = storageRef.child("images/mountains.jpg");

// While the file names are the same, the references point to different files
assert(mountainsRef.name == mountainImagesRef.name);
assert(mountainsRef.fullPath != mountainImagesRef.fullPath);

بمجرد إنشاء مرجع مناسب، يمكنك بعد ذلك استدعاء الأسلوب putFile() أو putString() أو putData() لتحميل الملف إلى Cloud Storage.

لا يمكنك تحميل البيانات بالإشارة إلى جذر مجموعة التخزين السحابي الخاصة بك. يجب أن يشير مرجعك إلى عنوان URL فرعي.

تحميل من ملف

لتحميل ملف، يجب عليك أولاً الحصول على المسار المطلق لموقعه على الجهاز. على سبيل المثال، إذا كان الملف موجودًا في دليل مستندات التطبيق، فاستخدم حزمة path_provider الرسمية لإنشاء مسار ملف وتمريره إلى putFile() :

Directory appDocDir = await getApplicationDocumentsDirectory();
String filePath = '${appDocDir.absolute}/file-to-upload.png';
File file = File(filePath);

try {
  await mountainsRef.putFile(file);
} on firebase_core.FirebaseException catch (e) {
  // ...
}

تحميل من سلسلة

يمكنك تحميل البيانات كسلسلة مشفرة أولية أو base64 أو base64url أو data_url باستخدام طريقة putString() . على سبيل المثال، لتحميل سلسلة نصية مشفرة كعنوان URL للبيانات:

String dataUrl = 'data:text/plain;base64,SGVsbG8sIFdvcmxkIQ==';

try {
  await mountainsRef.putString(dataUrl, format: PutStringFormat.dataUrl);
} on FirebaseException catch (e) {
  // ...
}

تحميل البيانات الخام

يمكنك تحميل البيانات المكتوبة ذات المستوى الأدنى في شكل Uint8List لتلك الحالات التي يكون فيها تحميل سلسلة أو File غير عملي. في هذه الحالة، قم باستدعاء التابع putData() ‎ مع بياناتك:

try {
  // Upload raw data.
  await mountainsRef.putData(data);
} on firebase_core.FirebaseException catch (e) {
  // ...
}

احصل على عنوان URL للتنزيل

بعد تحميل ملف، يمكنك الحصول على عنوان URL لتنزيل الملف عن طريق استدعاء طريقة getDownloadUrl() في Reference :

await mountainsRef.getDownloadURL();

إضافة بيانات تعريف الملف

يمكنك أيضًا تضمين بيانات التعريف عند تحميل الملفات. تحتوي بيانات التعريف هذه على خصائص بيانات تعريف الملف النموذجية مثل contentType (يُشار إليه عادةً بنوع MIME). تستنتج طريقة putFile() تلقائيًا نوع MIME من امتداد File ، ولكن يمكنك تجاوز النوع الذي تم اكتشافه تلقائيًا عن طريق تحديد contentType في البيانات التعريفية. إذا لم تقم بتوفير contentType ولم يتمكن Cloud Storage من استنتاج الإعداد الافتراضي من امتداد الملف، فإن Cloud Storage يستخدم application/octet-stream . راجع استخدام بيانات تعريف الملف .

try {
  await mountainsRef.putFile(file, SettableMetadata(
    contentType: "image/jpeg",
  ));
} on firebase_core.FirebaseException catch (e) {
  // ...
}

إدارة التحميلات

بالإضافة إلى بدء التحميلات، يمكنك إيقاف التحميلات مؤقتًا واستئنافها وإلغائها باستخدام طرق pause() resume() cancel() . يؤدي الإيقاف المؤقت واستئناف الأحداث إلى رفع تغييرات حالة الإيقاف pause progress على التوالي. يؤدي إلغاء التحميل إلى فشل التحميل مع ظهور خطأ يشير إلى أنه تم إلغاء التحميل.

final task = mountainsRef.putFile(largeFile);

// Pause the upload.
bool paused = await task.pause();
print('paused, $paused');

// Resume the upload.
bool resumed = await task.resume();
print('resumed, $resumed');

// Cancel the upload.
bool canceled = await task.cancel();
print('canceled, $canceled');

مراقبة تقدم التحميل

يمكنك الاستماع إلى تدفق أحداث المهمة للتعامل مع النجاح أو الفشل أو التقدم أو التوقف المؤقت في مهمة التحميل الخاصة بك:

نوع الحدث الاستخدام النموذجي
TaskState.running ينبعث بشكل دوري أثناء نقل البيانات ويمكن استخدامه لملء مؤشر التحميل/التنزيل.
TaskState.paused ينبعث في أي وقت يتم إيقاف المهمة مؤقتا.
TaskState.success تنبعث عند اكتمال المهمة بنجاح.
TaskState.canceled ينبعث في أي وقت يتم إلغاء المهمة.
TaskState.error تنبعث عند فشل التحميل. يمكن أن يحدث هذا بسبب انتهاء مهلة الشبكة، أو فشل التفويض، أو إذا قمت بإلغاء المهمة.
mountainsRef.putFile(file).snapshotEvents.listen((taskSnapshot) {
  switch (taskSnapshot.state) {
    case TaskState.running:
      // ...
      break;
    case TaskState.paused:
      // ...
      break;
    case TaskState.success:
      // ...
      break;
    case TaskState.canceled:
      // ...
      break;
    case TaskState.error:
      // ...
      break;
  }
});

معالجة الأخطاء

هناك عدد من الأسباب التي قد تؤدي إلى حدوث أخطاء عند التحميل، بما في ذلك الملف المحلي غير الموجود، أو عدم حصول المستخدم على إذن لتحميل الملف المطلوب. يمكنك العثور على مزيد من المعلومات حول الأخطاء في قسم التعامل مع الأخطاء في المستندات.

مثال كامل

فيما يلي مثال كامل للتحميل مع مراقبة التقدم ومعالجة الأخطاء:

final appDocDir = await getApplicationDocumentsDirectory();
final filePath = "${appDocDir.absolute}/path/to/mountains.jpg";
final file = File(filePath);

// Create the file metadata
final metadata = SettableMetadata(contentType: "image/jpeg");

// Create a reference to the Firebase Storage bucket
final storageRef = FirebaseStorage.instance.ref();

// Upload file and metadata to the path 'images/mountains.jpg'
final uploadTask = storageRef
    .child("images/path/to/mountains.jpg")
    .putFile(file, metadata);

// Listen for state changes, errors, and completion of the upload.
uploadTask.snapshotEvents.listen((TaskSnapshot taskSnapshot) {
  switch (taskSnapshot.state) {
    case TaskState.running:
      final progress =
          100.0 * (taskSnapshot.bytesTransferred / taskSnapshot.totalBytes);
      print("Upload is $progress% complete.");
      break;
    case TaskState.paused:
      print("Upload is paused.");
      break;
    case TaskState.canceled:
      print("Upload was canceled");
      break;
    case TaskState.error:
      // Handle unsuccessful uploads
      break;
    case TaskState.success:
      // Handle successful uploads on complete
      // ...
      break;
  }
});

الآن بعد أن قمت بتحميل الملفات، فلنتعرف على كيفية تنزيلها من Cloud Storage.