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

تتيح لك خدمة "مساحة تخزين سحابية لـ Firebase" تنزيل الملفات بسرعة وسهولة من حزمة Cloud Storage التي توفّرها Firebase وتديرها.

إنشاء مرجع

لتنزيل ملف، عليك أولاً إنشاء مرجع Cloud Storage للملف الذي تريد تنزيله.

يمكنك إنشاء مرجع عن طريق إلحاق مسارات فرعية بجذر حزمة Cloud Storage، أو يمكنك إنشاء مرجع من عنوان URL حالي gs:// أو https:// يشير إلى عنصر في Cloud Storage.

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

// Create a reference with an initial file path and name
final pathReference = storageRef.child("images/stars.jpg");

// Create a reference to a file from a Google Cloud Storage URI
final gsReference =
    FirebaseStorage.instance.refFromURL("gs://YOUR_BUCKET/images/stars.jpg");

// Create a reference from an HTTPS URL
// Note that in the URL, characters are URL escaped!
final httpsReference = FirebaseStorage.instance.refFromURL(
    "https://firebasestorage.googleapis.com/b/YOUR_BUCKET/o/images%20stars.jpg");

تنزيل الملفات

بعد الحصول على مرجع، يمكنك تنزيل الملفات من Cloud Storage من خلال استدعاء getData(). إذا كنت تفضّل تنزيل الملف باستخدام مكتبة أخرى، يمكنك الحصول على عنوان URL للتنزيل باستخدام getDownloadUrl().

التنزيل في الذاكرة

نزِّل الملف إلى UInt8List باستخدام الطريقة getData(). هذه هي أسهل طريقة لتنزيل ملف، ولكن يجب تحميل محتوى الملف بالكامل في الذاكرة. إذا طلبت ملفًا أكبر من الذاكرة المتاحة لتطبيقك، سيتعطّل تطبيقك. للحماية من مشاكل الذاكرة، يحدّد getData() الحد الأقصى لعدد وحدات البايت التي يمكن تنزيلها. اضبط الحد الأقصى للحجم على قيمة تعرف أنّ تطبيقك يمكنه التعامل معها، أو استخدِم طريقة تنزيل أخرى.

final islandRef = storageRef.child("images/island.jpg");

try {
  const oneMegabyte = 1024 * 1024;
  final Uint8List? data = await islandRef.getData(oneMegabyte);
  // Data for "images/island.jpg" is returned, use this as needed.
} on FirebaseException catch (e) {
  // Handle any errors.
}

تنزيل الملف إلى ملف محلي

تنزّل طريقة writeToFile() ملفًا مباشرةً على جهاز محلي. استخدِم هذه الطريقة إذا كان المستخدمون يريدون الوصول إلى الملف بلا اتصال بالإنترنت أو مشاركته في تطبيق آخر. تعرض الدالة writeToFile() القيمة DownloadTask التي يمكنك استخدامها لإدارة عملية التنزيل وتتبُّع حالتها.

final islandRef = storageRef.child("images/island.jpg");

final appDocDir = await getApplicationDocumentsDirectory();
final filePath = "${appDocDir.absolute}/images/island.jpg";
final file = File(filePath);

final downloadTask = islandRef.writeToFile(file);
downloadTask.snapshotEvents.listen((taskSnapshot) {
  switch (taskSnapshot.state) {
    case TaskState.running:
      // TODO: Handle this case.
      break;
    case TaskState.paused:
      // TODO: Handle this case.
      break;
    case TaskState.success:
      // TODO: Handle this case.
      break;
    case TaskState.canceled:
      // TODO: Handle this case.
      break;
    case TaskState.error:
      // TODO: Handle this case.
      break;
  }
});

تنزيل البيانات من خلال عنوان URL

إذا كانت لديك بنية أساسية للتنزيل تستند إلى عناوين URL، أو إذا كنت تريد فقط الحصول على عنوان URL لمشاركته، يمكنك الحصول على عنوان URL للتنزيل لملف من خلال استدعاء الطريقة getDownloadURL() في مرجع Cloud Storage.

final imageUrl =
    await storageRef.child("users/me/profile.png").getDownloadURL();

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

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

مثال كامل

في ما يلي مثال كامل على عملية تنزيل مع معالجة الأخطاء:

final islandRef = storageRef.child("images/island.jpg");

final appDocDir = await getApplicationDocumentsDirectory();
final filePath = "${appDocDir.absolute}/images/island.jpg";
final file = File(filePath);

final downloadTask = islandRef.writeToFile(file);
downloadTask.snapshotEvents.listen((taskSnapshot) {
  switch (taskSnapshot.state) {
    case TaskState.running:
      // TODO: Handle this case.
      break;
    case TaskState.paused:
      // TODO: Handle this case.
      break;
    case TaskState.success:
      // TODO: Handle this case.
      break;
    case TaskState.canceled:
      // TODO: Handle this case.
      break;
    case TaskState.error:
      // TODO: Handle this case.
      break;
  }
});

يمكنك أيضًا الحصول على البيانات الوصفية وتعديلها للملفات المخزّنة في Cloud Storage.