在 Flutter 中使用 Cloud Storage 上傳檔案

Cloud Storage for Firebase 可讓您輕鬆快速地將檔案上傳至由 Firebase 提供及管理的 Cloud Storage 值區。

上傳檔案

如要將檔案上傳至 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) {
  // ...
}

從字串上傳

您可以使用 putString() 方法，以原始、base64、base64url 或 data_url 編碼字串上傳資料。舉例來說，如要上傳編碼成資料網址的文字字串：

String dataUrl = 'data:text/plain;base64,SGVsbG8sIFdvcmxkIQ==';

try {
  await mountainsRef.putString(dataUrl, format: PutStringFormat.dataUrl);
} on FirebaseException catch (e) {
  // ...
}

上傳原始資料

對於上傳字串或 File 不符實際的情況，您可以上傳 Uint8List 格式來上傳較低層級的類型資料。在這種情況下，請使用您的資料呼叫 putData() 方法：

try {
  // Upload raw data.
  await mountainsRef.putData(data);
} on firebase_core.FirebaseException catch (e) {
  // ...
}

取得下載網址

上傳檔案後，您可以在 Reference 上呼叫 getDownloadUrl() 方法，取得下載檔案的網址：

await mountainsRef.getDownloadURL();

新增檔案中繼資料

您也可以在上傳檔案時加入中繼資料。這個中繼資料包含一般檔案中繼資料屬性，例如 contentType (通常稱為 MIME 類型)。putFile() 方法會從 File 擴充功能自動推論 MIME 類型，但您可以在中繼資料中指定 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 下載這些檔案。