Cloud Storage for Firebase ti consente di caricare rapidamente e facilmente file su un bucket Cloud Storage fornito e gestito da Firebase.
Caricare files
Per caricare un file su Cloud Storage, devi prima creare un riferimento al percorso completo del file, incluso il nome del file.
// 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);
Dopo aver creato un riferimento appropriato, chiami il putFile()
, putString()
o putData()
per caricare il file su Cloud Storage.
Non puoi caricare dati con un riferimento alla radice del tuo bucket di Cloud Storage. Il tuo riferimento deve puntare a un URL figlio.
Carica da un file
Per caricare un file, devi prima ottenere il percorso assoluto della sua posizione sul dispositivo. Ad esempio, se esiste un file nella directory dei documenti dell'applicazione, utilizzare il pacchetto path_provider
ufficiale per generare un percorso di file e passarlo a 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) {
// ...
}
Carica da una stringa
Puoi caricare i dati come stringa codificata raw, base64
, base64url
o data_url
usando il metodo putString()
. Ad esempio, per caricare una stringa di testo codificata come URL dati:
String dataUrl = 'data:text/plain;base64,SGVsbG8sIFdvcmxkIQ==';
try {
await mountainsRef.putString(dataUrl, format: PutStringFormat.dataUrl);
} on FirebaseException catch (e) {
// ...
}
Caricamento di dati grezzi
Puoi caricare dati digitati di livello inferiore sotto forma di Uint8List
per quei casi in cui il caricamento di una stringa o di un File
non è pratico. In questo caso, chiama il metodo putData()
con i tuoi dati:
try {
// Upload raw data.
await mountainsRef.putData(data);
} on firebase_core.FirebaseException catch (e) {
// ...
}
Ottieni un URL per il download
Dopo aver caricato un file, puoi ottenere un URL per scaricare il file chiamando il metodo getDownloadUrl()
su Reference
:
await mountainsRef.getDownloadURL();
Aggiungi metadati del file
Puoi anche includere metadati quando carichi file. Questi metadati contengono proprietà tipiche dei metadati di file come contentType
(comunemente denominato tipo MIME). Il metodo putFile()
deduce automaticamente il tipo MIME dall'estensione File
, ma puoi sovrascrivere il tipo rilevato automaticamente specificando contentType
nei metadati. Se non fornisci un contentType
e Cloud Storage non può dedurre un valore predefinito dall'estensione del file, Cloud Storage utilizza application/octet-stream
. Vedere Utilizzare i metadati dei file .
try {
await mountainsRef.putFile(file, SettableMetadata(
contentType: "image/jpeg",
));
} on firebase_core.FirebaseException catch (e) {
// ...
}
Gestisci caricamenti
Oltre ad avviare i caricamenti, puoi mettere in pausa, riprendere e annullare i caricamenti utilizzando i metodi pause()
, resume()
e cancel()
. Gli eventi di pausa e ripresa generano rispettivamente le modifiche alla pause
e allo stato di progress
. L'annullamento di un caricamento provoca il fallimento del caricamento con un errore che indica che il caricamento è stato annullato.
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');
Monitora l'avanzamento del caricamento
Puoi ascoltare il flusso di eventi di un'attività per gestire l'esito positivo, negativo, l'avanzamento o le pause dell'attività di caricamento:
Tipo di evento | Uso tipico |
---|---|
TaskState.running | Emesso periodicamente durante il trasferimento dei dati e può essere utilizzato per popolare un indicatore di caricamento/scaricamento. |
TaskState.paused | Emesso ogni volta che l'attività viene messa in pausa. |
TaskState.success | Emesso quando l'attività è stata completata con successo. |
TaskState.canceled | Emesso ogni volta che l'attività viene annullata. |
TaskState.error | Emesso quando il caricamento non è riuscito. Ciò può verificarsi a causa di timeout della rete, errori di autorizzazione o se si annulla l'attività. |
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;
}
});
Gestione degli errori
Esistono diversi motivi per cui possono verificarsi errori durante il caricamento, incluso il file locale non esistente o l'utente che non dispone dell'autorizzazione per caricare il file desiderato. Puoi trovare maggiori informazioni sugli errori nella sezione Gestisci errori dei documenti.
Esempio completo
Di seguito è riportato un esempio completo di caricamento con monitoraggio dello stato di avanzamento e gestione degli errori:
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;
}
});
Ora che hai caricato i file, impariamo come scaricarli da Cloud Storage.