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

‫Cloud Storage for 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() به‌طور خودکار نوع MIME را از افزونه 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 آشنا شویم.