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

این صفحه نحوه استفاده از کیت توسعه نرم‌افزار Cloud Storage for Firebase را برای بارگیری فایل‌ها از یک دسته Cloud Storage شرح می‌دهد.

ایجاد مرجع

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

می‌توانید با افزودن مسیرهای فرزند به ریشه سبد Cloud Storage خود، یک مرجع ایجاد کنید، یا می‌توانید از یک نشانی وب موجود gs:// یا https:// که به شیئی در Cloud Storage ارجاع می‌دهد، یک مرجع ایجاد کنید.

// Create a storage reference from your 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 ذخیره شده‌اند، فراداده دریافت و به‌روزرسانی کنید.