Przesyłanie plików do Cloud Storage w Flutter

Cloud Storage dla Firebase umożliwia szybkie i łatwe przesyłanie plików do zasobnika Cloud Storage udostępnianego i zarządzanego przez Firebase.

Prześlij pliki

Aby przesłać plik do Cloud Storage, najpierw utwórz odwołanie do pełnej ścieżki pliku, w tym jego nazwy.

// 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);

Gdy utworzysz odpowiednie odwołanie, wywołaj metodę putFile(), putString() lub putData(), aby przesłać plik do Cloud Storage.

Nie możesz przesłać danych odwołujących się do katalogu głównego zasobnika Cloud Storage. Odwoływanie musi wskazywać adres URL podrzędny.

Prześlij z pliku

Aby przesłać plik, musisz najpierw uzyskać ścieżkę bezwzględną do jego lokalizacji na urządzeniu. Jeśli na przykład plik znajduje się w katalogu dokumentów aplikacji, użyj oficjalnego pakietu path_provider, by wygenerować ścieżkę pliku i przekazać go do 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) {
  // ...
}

Prześlij z ciągu

Dane możesz przesyłać w postaci nieprzetworzonego ciągu znaków, zakodowanego w base64, base64url lub data_url, przy użyciu metody putString(). Aby np. przesłać ciąg tekstowy zakodowany jako URL danych:

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

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

Przesyłanie nieprzetworzonych danych

Dane niższego poziomu możesz przesyłać w postaci Uint8List. Jest to przydatne w przypadkach, gdy przesyłanie ciągu znaków lub File nie jest praktyczne. W takim przypadku wywołaj metodę putData() z danymi:

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

Uzyskiwanie adresu URL pobierania

Po przesłaniu pliku możesz uzyskać adres URL umożliwiający jego pobranie, wywołując w Reference metodę getDownloadUrl():

await mountainsRef.getDownloadURL();

Dodawanie metadanych pliku

Podczas przesyłania plików możesz też dołączyć metadane. Zawierają one typowe właściwości metadanych plików, takie jak contentType (powszechnie nazywane typem MIME). Metoda putFile() automatycznie określa typ MIME na podstawie rozszerzenia File, ale możesz zastąpić ten wykryty automatycznie, określając w metadanych contentType. Jeśli nie podasz właściwości contentType, a Cloud Storage nie będzie w stanie wywnioskować wartości domyślnej na podstawie rozszerzenia pliku, Cloud Storage użyje application/octet-stream. Zobacz Używanie metadanych pliku.

try {
  await mountainsRef.putFile(file, SettableMetadata(
    contentType: "image/jpeg",
  ));
} on firebase_core.FirebaseException catch (e) {
  // ...
}

Zarządzaj przesyłaniem

Oprócz uruchamiania przesyłania możesz je wstrzymywać, wznawiać i anulować za pomocą metod pause(), resume() i cancel(). Zmiany stanu wstrzymywania i wznawiania zdarzeń wzrostu wartości pause i progress. Anulowanie przesyłania spowoduje, że zakończy się ono niepowodzeniem i wyświetli się komunikat o błędzie informujący o tym, że przesyłanie zostało anulowane.

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');

Monitorowanie postępu przesyłania

Możesz nasłuchiwać strumienia zdarzeń zadania, aby zapewnić obsługę powodzenia, niepowodzenia, postępu lub wstrzymania zadania przesyłania:

Typ zdarzenia	Typowe zastosowanie
`TaskState.running`	Wysyłane okresowo podczas przesyłania danych. Można ich użyć do wypełnienia wskaźnika przesyłania/pobierania.
`TaskState.paused`	Wysyłane za każdym razem, gdy zadanie jest wstrzymane.
`TaskState.success`	Wysyłane po ukończeniu zadania.
`TaskState.canceled`	Wysyłane po każdym anulowaniu zadania.
`TaskState.error`	Wysyłane, gdy przesyłanie się nie powiodło. Może to wynikać z przekroczenia limitu czasu sieci, błędów autoryzacji lub anulowania zadania.

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;
  }
});

Obsługa błędów

Błędy podczas przesyłania mogą wystąpić z różnych powodów, na przykład dlatego, że plik lokalny nie istnieje lub użytkownik nie ma uprawnień do przesłania odpowiedniego pliku. Więcej informacji o błędach znajdziesz w dokumentacji w sekcji Obsługa błędów.

Pełny przykład

Poniżej przedstawiamy pełny przykład przesyłania z monitorowaniem postępu i obsługą błędów:

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;
  }
});

Dowiedz się, jak pobrać pliki z Cloud Storage.