تنزيل الملفات باستخدام 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 وتعديلها.