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

‫Cloud Storage ویژه 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 خود بارگذاری کنید. مرجع شما باید به نشانی وب فرزند اشاره کند.

بارگذاری از فایل

برای بارگذاری فایل، ابتدا باید مسیر مطلق آن را در مکان درون‌دستگاهی‌اش دریافت کنید. برای مثال، اگر فایلی در فهرست راهنمای اسناد برنامه وجود دارد، از بسته رسمی 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() بارگذاری کنید. برای مثال، برای بارگذاری رشته نوشتاری کدبندی‌شده به‌عنوان نشانی وب داده:

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) {
  // ...
}

دریافت نشانی وب بارگیری

پس‌از بارگذاری فایل، می‌توانید با فراخوانی روش getDownloadUrl() در Reference، نشانی وب را برای بارگیری فایل دریافت کنید:

await mountainsRef.getDownloadURL();

افزودن فراداده فایل

همچنین می‌توانید هنگام بارگذاری فایل‌ها، فراداده اضافه کنید. این فراداده حاوی ویژگی‌های فراداده فایل معمولی مانند contentType (که معمولاً نوع MIME نامیده می‌شود) است. روش putFile() به‌طور خودکار نوع رسانه را از افزونه 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 آشنا شویم.