تحميل الملفات باستخدام 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.

لا يمكنك تحميل بيانات تشير إلى جذر حزمة 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.