بارگیری کردن فایل‌ها با Cloud Storage در Flutter

«فضای ذخیره‌سازی ابری ویژه Firebase» به شما امکان می‌دهد به‌سرعت و به‌آسانی فایل‌ها را از یک دسته فضای ذخیره‌سازی ابری که توسط Firebase ارائه و مدیریت می‌شود بارگیری کنید.

ایجاد مرجع

برای بارگیری فایل، ابتدا یک مرجع Cloud Storage برای فایلی که می‌خواهید بارگیری کنید ایجاد کنید.

می‌توانید با افزودن مسیرهای فرزند به ریشه سبد Cloud Storage خود، یک مرجع ایجاد کنید، یا می‌توانید از یک نشانی وب موجود 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");

بارگیری فایل‌ها

وقتی مرجع را دریافت کردید، می‌توانید با فراخوانی getData()، فایل‌ها را از Cloud Storage بارگیری کنید. اگر ترجیح می‌دهید فایل را با کتابخانه دیگری بارگیری کنید، می‌توانید نشانی وب بارگیری را با getDownloadUrl() دریافت کنید.

بارگیری در حافظه

فایل را با روش getData() در UInt8List بارگیری کنید. این ساده‌ترین راه برای بارگیری فایل است، اما باید کل محتوای فایل را در حافظه بار کند. اگر فایلی بزرگ‌تر از حافظه دردسترس برنامه‌تان درخواست کنید، برنامه‌تان ازکار خواهد افتاد. برای محافظت دربرابر مشکلات حافظه، 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;
  }
});

بارگیری داده‌ها ازطریق نشانی وب

اگر ازقبل زیرساخت بارگیری براساس نشانی‌های وب دارید، یا فقط می‌خواهید نشانی وبی برای هم‌رسانی داشته باشید، می‌توانید نشانی وب بارگیری را برای فایل با فراخوانی روش 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 ذخیره شده‌اند، فراداده دریافت و به‌روزرسانی کنید.