获取我们在 Firebase 峰会上发布的所有信息,了解 Firebase 可如何帮助您加快应用开发速度并满怀信心地运行应用。了解详情

Accedi ai dati offline

Cloud Firestore supporta la persistenza dei dati offline. Questa funzione memorizza nella cache una copia dei dati di Cloud Firestore che la tua app sta utilizzando attivamente, in modo che la tua app possa accedere ai dati quando il dispositivo è offline. È possibile scrivere, leggere, ascoltare ed eseguire query sui dati memorizzati nella cache. Quando il dispositivo torna online, Cloud Firestore sincronizza tutte le modifiche locali apportate dalla tua app al back-end di Cloud Firestore.

Per utilizzare la persistenza offline, non è necessario apportare alcuna modifica al codice utilizzato per accedere ai dati di Cloud Firestore. Con la persistenza offline abilitata, la libreria client di Cloud Firestore gestisce automaticamente l'accesso ai dati online e offline e sincronizza i dati locali quando il dispositivo torna online.

Configura la persistenza offline

Quando inizializzi Cloud Firestore, puoi abilitare o disabilitare la persistenza offline:

  • Per le piattaforme Android e Apple, la persistenza offline è abilitata per impostazione predefinita. Per disabilitare la persistenza, imposta l'opzione PersistenceEnabled su false .
  • Per il Web, la persistenza offline è disabilitata per impostazione predefinita. Per abilitare la persistenza, chiama il metodo enablePersistence . La cache di Cloud Firestore non viene cancellata automaticamente tra le sessioni. Di conseguenza, se la tua app Web gestisce informazioni riservate, assicurati di chiedere all'utente se si trova su un dispositivo attendibile prima di abilitare la persistenza.

Web version 9

import { enableIndexedDbPersistence } from "firebase/firestore"; 

enableIndexedDbPersistence(db)
  .catch((err) => {
      if (err.code == 'failed-precondition') {
          // Multiple tabs open, persistence can only be enabled
          // in one tab at a a time.
          // ...
      } else if (err.code == 'unimplemented') {
          // The current browser does not support all of the
          // features required to enable persistence
          // ...
      }
  });
// Subsequent queries will use persistence, if it was enabled successfully

Web version 8

firebase.firestore().enablePersistence()
  .catch((err) => {
      if (err.code == 'failed-precondition') {
          // Multiple tabs open, persistence can only be enabled
          // in one tab at a a time.
          // ...
      } else if (err.code == 'unimplemented') {
          // The current browser does not support all of the
          // features required to enable persistence
          // ...
      }
  });
// Subsequent queries will use persistence, if it was enabled successfully
Rapido
Nota: questo prodotto non è disponibile sui target watchOS e App Clip.
let settings = FirestoreSettings()
settings.isPersistenceEnabled = true

// Any additional options
// ...

// Enable offline data persistence
let db = Firestore.firestore()
db.settings = settings
Obiettivo-C
Nota: questo prodotto non è disponibile sui target watchOS e App Clip.
FIRFirestoreSettings *settings = [[FIRFirestoreSettings alloc] init];
settings.persistenceEnabled = YES;

// Any additional options
// ...

// Enable offline data persistence
FIRFirestore *db = [FIRFirestore firestore];
db.settings = settings;

Kotlin+KTX

val settings = firestoreSettings {
    isPersistenceEnabled = true
}
db.firestoreSettings = settings

Java

FirebaseFirestoreSettings settings = new FirebaseFirestoreSettings.Builder()
        .setPersistenceEnabled(true)
        .build();
db.setFirestoreSettings(settings);

Dart

// Apple and Android
db.settings = const Settings(persistenceEnabled: true);

// Web
await db
    .enablePersistence(const PersistenceSettings(synchronizeTabs: true));

Configura la dimensione della cache

Quando la persistenza è abilitata, Cloud Firestore memorizza nella cache ogni documento ricevuto dal back-end per l'accesso offline. Cloud Firestore imposta una soglia predefinita per le dimensioni della cache. Dopo aver superato il valore predefinito, Cloud Firestore tenta periodicamente di ripulire i documenti meno recenti e inutilizzati. È possibile configurare una soglia di dimensioni della cache diversa o disabilitare completamente il processo di pulizia:

Web version 9

import { initializeFirestore, CACHE_SIZE_UNLIMITED } from "firebase/firestore";

const firestoreDb = initializeFirestore(app, {
  cacheSizeBytes: CACHE_SIZE_UNLIMITED
});

Web version 8

firebase.firestore().settings({
    cacheSizeBytes: firebase.firestore.CACHE_SIZE_UNLIMITED
});
Rapido
Nota: questo prodotto non è disponibile sui target watchOS e App Clip.
// The default cache size threshold is 100 MB. Configure "cacheSizeBytes"
// for a different threshold (minimum 1 MB) or set to "FirestoreCacheSizeUnlimited"
// to disable clean-up.
let settings = Firestore.firestore().settings
settings.cacheSizeBytes = FirestoreCacheSizeUnlimited
Firestore.firestore().settings = settings
Obiettivo-C
Nota: questo prodotto non è disponibile sui target watchOS e App Clip.
// The default cache size threshold is 100 MB. Configure "cacheSizeBytes"
// for a different threshold (minimum 1 MB) or set to "kFIRFirestoreCacheSizeUnlimited"
// to disable clean-up.
FIRFirestoreSettings *settings = [FIRFirestore firestore].settings;
settings.cacheSizeBytes = kFIRFirestoreCacheSizeUnlimited;
[FIRFirestore firestore].settings = settings;
  

Kotlin+KTX


// The default cache size threshold is 100 MB. Configure "setCacheSizeBytes"
// for a different threshold (minimum 1 MB) or set to "CACHE_SIZE_UNLIMITED"
// to disable clean-up.
val settings = FirebaseFirestoreSettings.Builder()
        .setCacheSizeBytes(FirebaseFirestoreSettings.CACHE_SIZE_UNLIMITED)
        .build()
db.firestoreSettings = settings

Java


// The default cache size threshold is 100 MB. Configure "setCacheSizeBytes"
// for a different threshold (minimum 1 MB) or set to "CACHE_SIZE_UNLIMITED"
// to disable clean-up.
FirebaseFirestoreSettings settings = new FirebaseFirestoreSettings.Builder()
        .setCacheSizeBytes(FirebaseFirestoreSettings.CACHE_SIZE_UNLIMITED)
        .build();
db.setFirestoreSettings(settings);

Dart

db.settings = const Settings(
  persistenceEnabled: true,
  cacheSizeBytes: Settings.CACHE_SIZE_UNLIMITED,
);

Ascolta i dati offline

Mentre il dispositivo è offline, se hai abilitato la persistenza offline, i tuoi listener riceveranno eventi di ascolto quando i dati memorizzati nella cache locale cambiano. Puoi ascoltare documenti, raccolte e query.

Per verificare se stai ricevendo dati dal server o dalla cache, usa la proprietà fromCache su SnapshotMetadata nell'evento snapshot. Se fromCache è true , i dati provengono dalla cache e potrebbero essere obsoleti o incompleti. Se fromCache è false , i dati sono completi e aggiornati con gli ultimi aggiornamenti sul server.

Per impostazione predefinita, non viene generato alcun evento se sono stati modificati solo gli SnapshotMetadata . Se fai affidamento sui valori fromCache , specifica l'opzione di ascolto includeMetadataChanges quando colleghi il gestore di ascolto.

Web version 9

import { collection, onSnapshot, where, query } from "firebase/firestore"; 

const q = query(collection(db, "cities"), where("state", "==", "CA"));
onSnapshot(q, { includeMetadataChanges: true }, (snapshot) => {
    snapshot.docChanges().forEach((change) => {
        if (change.type === "added") {
            console.log("New city: ", change.doc.data());
        }

        const source = snapshot.metadata.fromCache ? "local cache" : "server";
        console.log("Data came from " + source);
    });
});

Web version 8

db.collection("cities").where("state", "==", "CA")
  .onSnapshot({ includeMetadataChanges: true }, (snapshot) => {
      snapshot.docChanges().forEach((change) => {
          if (change.type === "added") {
              console.log("New city: ", change.doc.data());
          }

          var source = snapshot.metadata.fromCache ? "local cache" : "server";
          console.log("Data came from " + source);
      });
  });
Rapido
Nota: questo prodotto non è disponibile sui target watchOS e App Clip.
// Listen to metadata updates to receive a server snapshot even if
// the data is the same as the cached data.
db.collection("cities").whereField("state", isEqualTo: "CA")
    .addSnapshotListener(includeMetadataChanges: true) { querySnapshot, error in
        guard let snapshot = querySnapshot else {
            print("Error retreiving snapshot: \(error!)")
            return
        }

        for diff in snapshot.documentChanges {
            if diff.type == .added {
                print("New city: \(diff.document.data())")
            }
        }

        let source = snapshot.metadata.isFromCache ? "local cache" : "server"
        print("Metadata: Data fetched from \(source)")
}
Obiettivo-C
Nota: questo prodotto non è disponibile sui target watchOS e App Clip.
// Listen to metadata updates to receive a server snapshot even if
// the data is the same as the cached data.
[[[db collectionWithPath:@"cities"] queryWhereField:@"state" isEqualTo:@"CA"]
    addSnapshotListenerWithIncludeMetadataChanges:YES
    listener:^(FIRQuerySnapshot *snapshot, NSError *error) {
      if (snapshot == nil) {
        NSLog(@"Error retreiving snapshot: %@", error);
        return;
      }
      for (FIRDocumentChange *diff in snapshot.documentChanges) {
        if (diff.type == FIRDocumentChangeTypeAdded) {
          NSLog(@"New city: %@", diff.document.data);
        }
      }

      NSString *source = snapshot.metadata.isFromCache ? @"local cache" : @"server";
      NSLog(@"Metadata: Data fetched from %@", source);
    }];

Kotlin+KTX

db.collection("cities").whereEqualTo("state", "CA")
        .addSnapshotListener(MetadataChanges.INCLUDE) { querySnapshot, e ->
            if (e != null) {
                Log.w(TAG, "Listen error", e)
                return@addSnapshotListener
            }

            for (change in querySnapshot!!.documentChanges) {
                if (change.type == DocumentChange.Type.ADDED) {
                    Log.d(TAG, "New city: ${change.document.data}")
                }

                val source = if (querySnapshot.metadata.isFromCache)
                    "local cache"
                else
                    "server"
                Log.d(TAG, "Data fetched from $source")
            }
        }

Java

db.collection("cities").whereEqualTo("state", "CA")
        .addSnapshotListener(MetadataChanges.INCLUDE, new EventListener<QuerySnapshot>() {
            @Override
            public void onEvent(@Nullable QuerySnapshot querySnapshot,
                                @Nullable FirebaseFirestoreException e) {
                if (e != null) {
                    Log.w(TAG, "Listen error", e);
                    return;
                }

                for (DocumentChange change : querySnapshot.getDocumentChanges()) {
                    if (change.getType() == Type.ADDED) {
                        Log.d(TAG, "New city:" + change.getDocument().getData());
                    }

                    String source = querySnapshot.getMetadata().isFromCache() ?
                            "local cache" : "server";
                    Log.d(TAG, "Data fetched from " + source);
                }

            }
        });

Dart

db
    .collection("cities")
    .where("state", isEqualTo: "CA")
    .snapshots(includeMetadataChanges: true)
    .listen((querySnapshot) {
  for (var change in querySnapshot.docChanges) {
    if (change.type == DocumentChangeType.added) {
      final source =
          (querySnapshot.metadata.isFromCache) ? "local cache" : "server";

      print("Data fetched from $source}");
    }
  }
});

Ottieni dati offline

Se ricevi un documento mentre il dispositivo è offline, Cloud Firestore restituisce i dati dalla cache.

Quando si esegue una query su una raccolta, viene restituito un risultato vuoto se non sono presenti documenti memorizzati nella cache. Quando si recupera un documento specifico, viene invece restituito un errore.

Interroga i dati offline

L'interrogazione funziona con la persistenza offline. È possibile recuperare i risultati delle query con un get diretto o mediante l'ascolto, come descritto nelle sezioni precedenti. Puoi anche creare nuove query sui dati persistenti in locale mentre il dispositivo è offline, ma le query verranno inizialmente eseguite solo sui documenti memorizzati nella cache.

Configura indici di query offline

Per impostazione predefinita, l'SDK di Firestore esegue la scansione di tutti i documenti in una raccolta nella sua cache locale durante l'esecuzione di query offline. Con questo comportamento predefinito, le prestazioni delle query offline possono risentirne quando gli utenti sono offline per lunghi periodi di tempo.

Puoi migliorare le prestazioni delle query offline configurando indici di query locali:

Rapido

L'SDK della piattaforma Apple fornisce un metodo setIndexConfiguration che legge la stessa configurazione strutturata in JSON utilizzata per configurare gli indici sul server, seguendo lo stesso formato di definizione dell'indice .

// You will normally read this from a file asset or cloud storage.
let indexConfigJson = """
  {
    indexes: [
        ...
    ],
    fieldOverrides: [
        ...
    ]
  }
"""

// Apply the configuration.
Firestore.firestore().setIndexConfiguration(indexConfigJson)
Obiettivo-C

L'SDK della piattaforma Apple fornisce setIndexConfiguration , metodi che leggono la stessa configurazione strutturata in JSON utilizzata per configurare gli indici sul server, seguendo lo stesso formato di definizione dell'indice .

// You will normally read this from a file asset or cloud storage.
NSString *indexConfigJson = @" {                   "
                             "   indexes: [        "
                             "     ...             "
                             "   ],                "
                             "   fieldOverrides: [ "
                             "     ...             "
                             "   ]                 "
                             " }                   ";

// Apply the configuration.
[[FIRFirestore firestore] setIndexConfigurationFromJSON:indexConfigJson
                                             completion:^(NSError * _Nullable error) {
    // ...
}];

Java

Android SDK fornisce un metodo setIndexConfiguration che legge la stessa configurazione strutturata in JSON utilizzata per configurare gli indici sul server, seguendo lo stesso formato di definizione dell'indice .

// You will normally read this from a file asset or cloud storage.
String indexConfigJson = " {                   "
                       + "   indexes: [        "
                       + "     ...             "
                       + "   ],                "
                       + "   fieldOverrides: [ "
                       + "     ...             "
                       + "   ]                 "
                       + " }                   ";
// Apply the configuration.
FirebaseFirestore.getInstance().setIndexConfiguration(indexConfigJson);

Kotlin+KTX

Android SDK fornisce un metodo setIndexConfiguration che legge la stessa configurazione strutturata in JSON utilizzata per configurare gli indici sul server, seguendo lo stesso formato di definizione dell'indice .

// You will normally read this from a file asset or cloud storage.
val indexConfigJson = """
{
  indexes: [
      ...
  ],
  fieldOverrides: [
      ...
  ]
}
"""

// Apply the configuration.
FirebaseFirestore.getInstance().setIndexConfiguration(indexConfigJson)

Dart

Flutter SDK fornisce un metodo setIndexConfigurationFromJSON che legge la stessa configurazione strutturata in JSON utilizzata per configurare gli indici sul server, seguendo lo stesso formato di definizione dell'indice .

// You will normally read this from a file asset or cloud storage.
var indexConfigJson = """
{
  indexes: [
      ...
  ],
  fieldOverrides: [
      ...
  ]
}
""";

// Apply the configuration.
await FirebaseFirestore.instance.setIndexConfigurationFromJSON(json: indexConfigJson);

In alternativa, puoi utilizzare il metodo setIndexConfiguration per configurare gli indici con un'API basata su classi.

var indexes = [
  Index(
    collectionGroup: "posts",
    queryScope: QueryScope.collection,
    fields: [
      IndexField(fieldPath: "author", arrayConfig: ArrayConfig.contains),
      IndexField(fieldPath: "timestamp", order: Order.descending)
    ],
  ),
];
await FirebaseFirestore.instance.setIndexConfiguration(indexes: indexes);

La configurazione dell'indice offline da usare dipende dalle raccolte e dai documenti a cui la tua app accede in modo massiccio mentre è offline e dalle prestazioni offline desiderate. Anche se puoi esportare la configurazione dell'indice back-end per l'utilizzo sul client, i modelli di accesso offline della tua app probabilmente differiscono in modo significativo dai modelli di accesso online, pertanto la tua configurazione dell'indice online potrebbe non essere adatta per l'utilizzo offline. A quali raccolte e documenti vuoi che la tua app acceda offline con prestazioni elevate? Dopo aver analizzato il comportamento della tua app, segui i principi per la definizione dell'indice dalla guida all'indicizzazione .

Per rendere le configurazioni dell'indice offline disponibili per il caricamento nell'app client:

  • compilali e distribuiscili con la tua app
  • scaricarli da un CDN
  • recuperali da un sistema di archiviazione come Cloud Storage for Firebase .

Disabilita e abilita l'accesso alla rete

Puoi utilizzare il metodo seguente per disabilitare l'accesso alla rete per il tuo client Cloud Firestore. Mentre l'accesso alla rete è disabilitato, tutti i listener di snapshot e le richieste di documenti recuperano i risultati dalla cache. Le operazioni di scrittura vengono messe in coda finché non viene riabilitato l'accesso alla rete.

Web version 9

import { disableNetwork } from "firebase/firestore"; 

await disableNetwork(db);
console.log("Network disabled!");
// Do offline actions
// ...

Web version 8

firebase.firestore().disableNetwork()
    .then(() => {
        // Do offline actions
        // ...
    });
Rapido
Nota: questo prodotto non è disponibile sui target watchOS e App Clip.
Firestore.firestore().disableNetwork { (error) in
    // Do offline things
    // ...
}
Obiettivo-C
Nota: questo prodotto non è disponibile sui target watchOS e App Clip.
[[FIRFirestore firestore] disableNetworkWithCompletion:^(NSError *_Nullable error) {
  // Do offline actions
  // ...
}];

Kotlin+KTX

db.disableNetwork().addOnCompleteListener {
    // Do offline things
    // ...
}

Java

db.disableNetwork()
        .addOnCompleteListener(new OnCompleteListener<Void>() {
            @Override
            public void onComplete(@NonNull Task<Void> task) {
                // Do offline things
                // ...
            }
        });

Dart

db.disableNetwork().then((_) {
  // Do offline things
});

Utilizzare il seguente metodo per riattivare l'accesso alla rete:

Web version 9

import { enableNetwork } from "firebase/firestore"; 

await enableNetwork(db);
// Do online actions
// ...

Web version 8

firebase.firestore().enableNetwork()
    .then(() => {
        // Do online actions
        // ...
    });
Rapido
Nota: questo prodotto non è disponibile sui target watchOS e App Clip.
Firestore.firestore().enableNetwork { (error) in
    // Do online things
    // ...
}
Obiettivo-C
Nota: questo prodotto non è disponibile sui target watchOS e App Clip.
[[FIRFirestore firestore] enableNetworkWithCompletion:^(NSError *_Nullable error) {
  // Do online actions
  // ...
}];

Kotlin+KTX

db.enableNetwork().addOnCompleteListener {
    // Do online things
    // ...
}

Java

db.enableNetwork()
        .addOnCompleteListener(new OnCompleteListener<Void>() {
            @Override
            public void onComplete(@NonNull Task<Void> task) {
                // Do online things
                // ...
            }
        });

Dart

db.enableNetwork().then((_) {
  // Back online
});